> ## Documentation Index
> Fetch the complete documentation index at: https://credira.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Call

> Trigger a new call to a customer

Trigger a new call to a customer using their phone number and associated invoice.

<Note>
  This endpoint initiates a call to the specified phone number and associates it
  with the given invoice. The call will be handled by the configured voice
  agent.
</Note>

## Request

<ParamField body="phone_number" type="string" required>
  The phone number to call (E.164 format, e.g., +1234567890)
</ParamField>

<ParamField body="invoice_id" type="string" required>
  The unique identifier of the invoice associated with this call
</ParamField>

<ParamField body="voice_agent_id" type="string" required>
  The unique identifier of the voice agent to handle this call
</ParamField>

<ParamField body="call_purpose" type="string">
  The purpose of the call (e.g., "payment\_reminder", "follow\_up",
  "verification")
</ParamField>

<ParamField body="scheduled_time" type="string">
  ISO 8601 timestamp for when to make the call (optional, defaults to immediate)
</ParamField>

<ParamField body="customer_name" type="string">
  The name of the customer being called (for personalization)
</ParamField>

<ParamField body="metadata" type="object">
  Additional metadata for the call (campaign\_id, department, etc.)
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for API authentication
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
       --url https://api.credira.com/v1/calls \
       --header 'Authorization: Bearer YOUR_API_KEY' \
       --header 'Content-Type: application/json' \
       --data '{
         "phone_number": "+1234567890",
         "invoice_id": "inv_987654321",
         "voice_agent_id": "agent_456789123",
         "call_purpose": "payment_reminder",
         "customer_name": "John Doe",
         "scheduled_time": "2024-01-15T14:30:00Z",
         "metadata": {
           "campaign_id": "camp_123",
           "department": "billing",
           "priority": "high"
         }
       }'
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch("https://api.credira.com/v1/calls", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      phone_number: "+1234567890",
      invoice_id: "inv_987654321",
      voice_agent_id: "agent_456789123",
      call_purpose: "payment_reminder",
      customer_name: "John Doe",
      scheduled_time: "2024-01-15T14:30:00Z",
      metadata: {
        campaign_id: "camp_123",
        department: "billing",
        priority: "high",
      },
    }),
  });

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample status="200" summary="Success">
  ```json theme={null}
  {
    "success": true,
    "data": {
      "id": "call_123456789",
      "invoice_id": "inv_987654321",
      "phone_number": "+1234567890",
      "voice_agent_id": "agent_456789123",
      "status": "initiated",
      "call_purpose": "payment_reminder",
      "customer_name": "John Doe",
      "scheduled_time": "2024-01-15T14:30:00Z",
      "account_id": "acc_789123456",
      "created_time": "2024-01-15T10:30:00Z",
      "estimated_duration": 180,
      "call_priority": "high",
      "metadata": {
        "campaign_id": "camp_123",
        "department": "billing",
        "priority": "high"
      }
    },
    "meta": {
      "timestamp": "2024-01-15T10:30:00Z",
      "request_id": "req_123456789",
      "message": "Call has been initiated successfully"
    }
  }
  ```
</ResponseExample>

<ResponseExample status="400" summary="Bad Request">
  ```json theme={null}
  {
    "success": false,
    "error": {
      "code": "INVALID_REQUEST",
      "message": "Missing required field: phone_number"
    },
    "meta": {
      "timestamp": "2024-01-15T10:30:00Z",
      "request_id": "req_123456789"
    }
  }
  ```
</ResponseExample>

<ResponseExample status="401" summary="Unauthorized">
  ```json theme={null}
  {
    "success": false,
    "error": {
      "code": "UNAUTHORIZED",
      "message": "Invalid or missing API key"
    },
    "meta": {
      "timestamp": "2024-01-15T10:30:00Z",
      "request_id": "req_123456789"
    }
  }
  ```
</ResponseExample>

<ResponseExample status="422" summary="Unprocessable Entity">
  ```json theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid phone number format",
      "details": "Phone number must be in E.164 format (e.g., +1234567890)"
    },
    "meta": {
      "timestamp": "2024-01-15T10:30:00Z",
      "request_id": "req_123456789"
    }
  }
  ```
</ResponseExample>

<ResponseExample status="429" summary="Too Many Requests">
  ```json theme={null}
  {
    "success": false,
    "error": {
      "code": "RATE_LIMITED",
      "message": "Too many call requests. Please wait before making another call."
    },
    "meta": {
      "timestamp": "2024-01-15T10:30:00Z",
      "request_id": "req_123456789"
    }
  }
  ```
</ResponseExample>