Skip to main content

​
Initiate call

Queue an outbound call to be processed by your AI agent. 
POST /api/v1/business/{businessId}/call/initiate

​
Path parameters

​
businessId
integer
required
The unique identifier for your business

​
Request body

This endpoint accepts multipart/form-data with a maximum size of 10MB.
​
RecipientNumber
string
required
Phone number to call in E.164 format (e.g., +1234567890)
​
NumberId
string
required
ID of the phone number to call from (must be configured in your business)
​
AgentId
string
required
ID of the AI agent to use for this call
​
CampaignId
string
Optional campaign ID to associate with this call for tracking and analytics
​
ScheduledTime
string
ISO 8601 timestamp to schedule the call for a future time. If not provided, the call is queued immediately.
​
DynamicVariables
object
Key-value pairs of dynamic variables to use during the call (e.g., customer name, account number). These are available to the agent during conversation.
​
Metadata
object
Additional metadata to attach to the call for your own tracking purposes

​
Response

​
Success
boolean
Indicates whether the call was successfully queued
​
Data
array
Array containing the queue ID(s) for the initiated call(s)
​
Code
string
Error code if Success is false
​
Message
string
Error message if Success is false or success confirmation

​
Example request

curl -X POST https://api.iqra.ai/api/v1/business/12345/call/initiate \
  -H "Authorization: Token YOUR_API_KEY" \
  -F "RecipientNumber=+1234567890" \
  -F "NumberId=num_abc123" \
  -F "AgentId=agent_xyz789" \
  -F "CampaignId=campaign_001" \
  -F "DynamicVariables[CustomerName]=John Doe" \
  -F "DynamicVariables[AccountNumber]=12345" \
  -F "Metadata[Source]=API"

​
Example response

{
  "Success": true,
  "Data": [
    "queue_abc123xyz789"
  ]
}

​
Error response example

{
  "Success": false,
  "Code": "InitiateCall:INSUFFICIENT_BALANCE",
  "Message": "Insufficient balance or minutes to make this call",
  "Data": null
}

​
Call queue lifecycle

When you initiate a call, it goes through the following states:
  1. Queued - Call is in the queue waiting to be processed
  2. Processing - Call is being dialed
  3. In Progress - Call is connected and conversation is active
  4. Completed - Call has ended
  5. Failed - Call could not be completed
You can track call status using the Queue endpoints.

​
Permissions required

This endpoint requires:
  • Valid API key with access to the specified business
  • MakeCall module permission with Full access
  • User and business must not be disabled
  • Business must have editing enabled
  • Sufficient balance or package minutes for making calls

​
Rate limits and quotas

Call initiation is subject to your account’s balance and usage limits.
  • Each call consumes minutes from your package or balance
  • You must have sufficient credits before the call can be queued
  • The system validates your balance before accepting the call request

​
Common error codes

CodeDescription
InitiateCall:INSUFFICIENT_BALANCENot enough credits or minutes to make the call
InitiateCall:INVALID_NUMBERInvalid recipient phone number format
InitiateCall:INVALID_AGENTAgent ID not found or disabled
InitiateCall:INVALID_NUMBER_IDCalling number ID not found or not configured
InitiateCall:PERMISSION_DENIEDInsufficient permissions to make calls
InitiateCall:BUSINESS_DISABLEDBusiness account is disabled
InitiateCall:EXCEPTIONInternal server error

​
Best practices

​
Phone numbers

  • Always use E.164 format for recipient numbers (+[country code][number])
  • Verify numbers are valid before making calls
  • Respect do-not-call lists and local regulations

​
Dynamic variables

  • Use dynamic variables to personalize conversations
  • Keep variable names consistent across your integration
  • Don’t include sensitive information in metadata

​
Scheduling

  • Schedule calls during appropriate business hours for the recipient’s timezone
  • Use campaigns to batch and track related calls
  • Monitor queue status to ensure calls are being processed

​
Error handling

  • Always check the Success field in the response
  • Log queue IDs for tracking and debugging
  • Implement retry logic for transient failures
  • Handle balance/quota errors gracefully

​
Notes

  • Calls are processed asynchronously; the API returns immediately after queuing
  • Use the queue ID to track call status and retrieve conversation details
  • Maximum request size is 10MB for the entire multipart form
  • Scheduled calls are processed at the specified time (subject to queue availability)

Build docs developers (and LLMs) love

Get started for freeTalk to us