> ## Documentation Index > Fetch the complete documentation index at: https://docs.unleashx.ai/llms.txt > Use this file to discover all available pages before exploring further. # Make Call # Make Call API This documentation explains how to initiate a call using a voice agent. ## Endpoint **POST** `/api/v1/global/agents/call` ## Authentication Include your API token in the request header: ``` token: ``` or ``` api_access_token: ``` ## Request Body ```json theme={null} { "agent_id": 123, "phone_number": "+1234567890", "metadata": { "customer_id": "CUST001", "call_reason": "Follow-up", "order_id": "ORD123" } } ``` ## Required Fields | Field | Type | Description | | -------------- | ------- | ------------------------------------------------------------------------------------- | | `agent_id` | integer | ID of the agent to use for the call | | `phone_number` | string | Phone number to call. Must include country code with `+` prefix (e.g., `+1234567890`) | ## Optional Fields | Field | Type | Description | | ---------- | ------ | --------------------------------------------------------------------------------- | | `metadata` | object | Additional metadata to pass with the call. Can include any custom key-value pairs | ## Success Response **Status Code:** `200 OK` ```json theme={null} { "success": true, "message": "Call initiated successfully", "data": { "execution_id": "550e8400-e29b-41d4-a716-446655440000", "agent_id": 123, "phone_number": "+1234567890", "call_status": "initiated" } } ``` ## Response Fields | Field | Type | Description | | -------------- | ------- | --------------------------------------------------------------------- | | `execution_id` | string | Unique identifier for this call execution. Use this to track the call | | `agent_id` | integer | ID of the agent used for the call | | `phone_number` | string | Phone number that was called | | `call_status` | string | Status of the call ("initiated") | ## Error Responses ### 400 Bad Request ```json theme={null} { "error": true, "message": "Phone Number is required" } ``` or ```json theme={null} { "error": true, "message": "Agent ID is required" } ``` ### 401 Unauthorized ```json theme={null} { "error": true, "message": "Invalid Auth Key or Session Expired" } ``` ### 404 Not Found ```json theme={null} { "error": true, "message": "Agent not found or not active" } ``` ### 422 Unprocessable Entity ```json theme={null} { "error": true, "message": "Validation error message" } ``` ## Example Request ```bash theme={null} curl -X POST https://www.tryunleashx.com/api/v1/global/agents/call \ -H "Content-Type: application/json" \ -H "token: your_api_token_here" \ -d '{ "agent_id": 123, "phone_number": "+1234567890", "metadata": { "customer_id": "CUST001", "call_reason": "Follow-up" } }' ``` ## Important Notes ### Phone Number Format * **Required:** Phone numbers must include country code with `+` prefix * **Correct:** `+1234567890`, `+919876543210` * **Incorrect:** `1234567890`, `919876543210` (missing `+`) The API will automatically add the `+` prefix if it's missing, but it's recommended to include it. ### Agent Requirements * The agent must be **active** (status = 1) to make calls * Only voice agents (agent\_type = 3) can be used for calls * The agent must belong to your workspace * For outbound calls (making calls to customers), the agent should have `calling_type: 1` * For inbound calls (receiving calls), the agent should have `calling_type: 2` ### Calling Types | ID | Type | Description | | -- | ------------ | ----------------------------------------------------------------------------------------------------------- | | 1 | **Outbound** | Agent makes calls to customers. Use this when you want the agent to initiate calls to phone numbers. | | 2 | **Inbound** | Agent receives calls from customers. Use this when customers call your phone numbers and the agent answers. | **Note:** When making calls using this API, ensure the agent's `calling_type` is set to `1` (Outbound) for outbound calling scenarios. ### Execution ID * Store the `execution_id` returned in the response for tracking purposes * This ID can be used to query call status and details later ### Metadata * The `metadata` field is optional but useful for passing context * Common use cases: * Customer information * Order details * Call reason/purpose * Custom tracking IDs * Metadata will be available during the call for the agent to reference ## Best Practices 1. **Validate Phone Numbers**: Ensure phone numbers are in correct format before making the call 2. **Check Agent Status**: Verify the agent is active before initiating calls 3. **Store Execution IDs**: Keep track of execution IDs for call monitoring and analytics 4. **Use Metadata**: Pass relevant context in metadata for better call handling 5. **Error Handling**: Implement proper error handling for failed call attempts 6. **Rate Limiting**: Be mindful of rate limits when making multiple calls ## Common Issues ### Issue: "Agent not found or not active" * **Solution**: Verify the agent exists and has status = 1 (active). Use the Get Agent API to check status. ### Issue: "Phone Number is required" * **Solution**: Ensure `phone_number` is included in the request body. ### Issue: Invalid phone number format * **Solution**: Ensure phone number includes country code with `+` prefix (e.g., `+1234567890`). ## OpenAPI ````yaml api-reference/openapi.json POST /agents/call openapi: 3.1.0 info: title: >- UnleashX - Build human like conversations | Voice Agents | Automations | AI Workforce version: 1.0.0 description: UnleashX - Your home for human like conversations servers: - url: https://www.tryunleashx.com/api/v1/global/ security: - bearerAuth: [] paths: /agents/call: post: tags: - Voice AI summary: Make call parameters: - name: token in: header required: true description: API token for authentication schema: type: string requestBody: required: true content: application/json: schema: type: object required: - agent_id - phone_number properties: agent_id: type: integer description: ID of the agent to use for the call phone_number: type: string description: >- Phone number to call. Must include country code with + prefix (e.g., '+1234567890') metadata: type: object description: >- Additional metadata to pass with the call. Can include any custom key-value pairs responses: '200': description: Call initiated successfully content: application/json: schema: type: object properties: success: type: boolean message: type: string data: type: object properties: execution_id: type: string format: uuid agent_id: type: integer phone_number: type: string call_status: type: string '400': description: Bad Request - Phone Number or Agent ID is required '401': description: Unauthorized '404': description: Agent not found or not active '422': description: Validation error security: [] components: securitySchemes: bearerAuth: type: http scheme: bearer ````