> ## Documentation Index > Fetch the complete documentation index at: https://docs.pam.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a voice call > Starts an outbound voice call using either agentSlug or agentId. PAM accepts the request asynchronously and returns queued status. PAM creates a conversation after the call is placed. Use call webhooks to follow call start, end, analysis, and placement failure events. The authenticated API key controls attribution and billing. ## OpenAPI ````yaml /openapi/v1.json post /calls openapi: 3.0.3 info: title: PAM Outbound API version: 1.0.0 description: >- External API for creating outbound calls, starting SMS conversations, managing API keys, and receiving webhook events. servers: - url: https://api.pamhq.com/v1 description: Production security: - bearerApiKey: [] tags: - name: Calls description: Start and manage outbound voice calls. - name: SMS Conversations description: Start and manage outbound SMS conversations. - name: API Keys description: Create, list, inspect, and revoke API keys. - name: Webhooks description: Configure direct call and SMS conversation webhook destinations. - name: Webhook Events description: Canonical webhook payloads emitted by calls and SMS conversations. paths: /calls: post: tags: - Calls summary: Create a voice call description: >- Starts an outbound voice call using either agentSlug or agentId. PAM accepts the request asynchronously and returns queued status. PAM creates a conversation after the call is placed. Use call webhooks to follow call start, end, analysis, and placement failure events. The authenticated API key controls attribution and billing. operationId: createCall parameters: - $ref: '#/components/parameters/idempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VoiceCallCreateRequest' examples: pamManagedAgent: summary: PAM recall voice agent value: agentSlug: voice-recall toNumber: '+15555550199' fromNumber: '+15555550123' welcomeMessage: >- Hi Ada, this is PAM Motors following up on your service recall. dynamicVariables: contact_first_name: Ada contact_last_name: Lovelace dealership_name: PAM Motors recall_id: 24V-123 service_ids: RECALL_SERVICE vin: 1HGBH41JXMN109186 vehicle_year: '2021' vehicle_make: Honda vehicle_model: Accord metadata: externalContactId: contact_123 externalReferenceId: touchpoint_123 idempotencyKey: call_01HV7K4ZD3Q9X8P1M8Y2K9A0BC webhookUrl: https://partner.example.com/pam/webhooks responses: '202': description: Call request accepted content: application/json: schema: $ref: '#/components/schemas/VoiceCallCreateResponse' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/ServerError' components: parameters: idempotencyKey: name: Idempotency-Key in: header required: false schema: type: string minLength: 1 maxLength: 255 description: >- Stable key for safely retrying a create request. For call creation, send either this header or idempotencyKey in the request body. schemas: VoiceCallCreateRequest: allOf: - $ref: '#/components/schemas/AgentSelector' - type: object required: - toNumber properties: toNumber: $ref: '#/components/schemas/E164PhoneNumber' fromNumber: $ref: '#/components/schemas/E164PhoneNumber' description: >- Required when you use agentSlug. Ignored when the selected agent has a configured phone number. welcomeMessage: type: string description: >- Opening text used as the Retell begin message. Required when you use a PAM-managed voice agent. dynamicVariables: allOf: - $ref: '#/components/schemas/DynamicVariables' description: >- Required when you use a PAM-managed recall or retention voice agent. Send only public variables documented in the Agents guide; generated prompt blocks are internal. metadata: type: object additionalProperties: true description: Opaque metadata stored with the conversation for reconciliation. externalReferenceId: type: string minLength: 1 maxLength: 255 description: >- Optional opaque caller-owned reference echoed as top-level externalReferenceId on webhook payloads. PAM does not interpret this value, does not require it to be globally unique, and does not use it as an idempotency key. idempotencyKey: type: string minLength: 1 maxLength: 255 description: >- Stable key for safely retrying this create request. Use this field if you do not send the Idempotency-Key header. webhookUrl: type: string format: uri pattern: ^https:// description: >- Optional HTTPS destination for webhook events from this call. The URL overrides only this call's destination; event subscriptions, custom headers, and signing secret still come from the matching webhook registration. VoiceCallCreateResponse: allOf: - $ref: '#/components/schemas/ResponseEnvelope' - type: object properties: data: $ref: '#/components/schemas/VoiceCallCreated' AgentSelector: type: object description: >- Select exactly one agent. Use agentSlug for PAM-managed agents, or agentId for a specific custom agent. properties: agentId: type: string format: uuid description: Specific custom agent id. agentSlug: type: string minLength: 1 maxLength: 255 description: Stable slug for a PAM-managed agent. oneOf: - required: - agentId - required: - agentSlug E164PhoneNumber: type: string pattern: ^\+\d{7,15}$ description: Phone number in E.164 format. DynamicVariables: type: object additionalProperties: type: string description: >- Public string values used by the selected agent. PAM-managed recall, retention, and declined-services agents require the variables listed in the Agents guide. PAM may generate internal prompt context blocks from these values; generated context blocks are not returned by conversation GET or list responses. ResponseEnvelope: type: object properties: data: {} meta: $ref: '#/components/schemas/Meta' VoiceCallCreated: type: object required: - conversationId - status properties: id: type: string format: uuid description: >- Conversation id, present after PAM creates the conversation for the call. conversationId: type: string format: uuid nullable: true description: >- Present after PAM creates the conversation for the call. Null while the call is still queued for dispatch. status: $ref: '#/components/schemas/ConversationStatus' ErrorResponse: type: object properties: error: type: object properties: code: type: string message: type: string details: description: Optional field-level validation details. nullable: true meta: $ref: '#/components/schemas/Meta' Meta: type: object properties: requestId: type: string ConversationStatus: type: string enum: - queued - in_progress - completed - failed - cancelled responses: ValidationError: description: Request validation failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Missing, expired, revoked, or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Conflict: description: Request conflicts with the current resource state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ServerError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerApiKey: type: http scheme: bearer description: 'API key provided as `Authorization: Bearer `.' x-default: pk_live_your_api_key ````