Create Call

Trigger a new call to a customer

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

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.

Request

phone_number · string · required

The phone number to call (E.164 format, e.g., [phone])

invoice_id · string · required

The unique identifier of the invoice associated with this call

voice_agent_id · string · required

The unique identifier of the voice agent to handle this call

call_purpose · string

The purpose of the call (e.g., “payment_reminder”, “follow_up”, “verification”)

scheduled_time · string

ISO 8601 timestamp for when to make the call (optional, defaults to immediate)

customer_name · string

The name of the customer being called (for personalization)

metadata · object

Additional metadata for the call (campaign_id, department, etc.)

Authorization · string · required

Bearer token for API authentication

cURL

curl --request POST \
     --url https://api.credira.com/v1/calls \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
       "phone_number": "[phone]",
       "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"
       }
     }'

Response

{
  "success": true,
  "data": {
    "id": "call_123456789",
    "invoice_id": "inv_987654321",
    "phone_number": "[phone]",
    "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"
  }
}

Response

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required field: phone_number"
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "request_id": "req_123456789"
  }
}

Response

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "request_id": "req_123456789"
  }
}

Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid phone number format",
    "details": "Phone number must be in E.164 format (e.g., [phone])"
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "request_id": "req_123456789"
  }
}

Response

{
  "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"
  }
}