> ## Documentation Index > Fetch the complete documentation index at: https://docs.replify.ai/llms.txt > Use this file to discover all available pages before exploring further. # Initiate outbound call > Schedule a single outbound call for a specific assistant (`agentId`). The call is queued after validation and placed shortly. **Required headers:** `x-api-key`, `Content-Type: application/json`. **Required fields** - `agentId` — assistant that places and handles the call, can be found in the URL after selecting that assistant. - `contact.phoneNumber` — callee number in **E.164** format (e.g. `+15551234567`). - **Messaging** — send **both** `introMessage` and `voicemailMessage`, **or** send `callInstructions` alone. You cannot send only one of `introMessage` / `voicemailMessage`. **Optional fields** - `contact.firstName`, `contact.lastName`, `contact.email`; trimmed and used for assistant context. - `metadata` — custom key/value pairs (strings, numbers, or booleans) to give the assistant context. **Assistant requirements** The assistant must exist, belong to your organization (from the API key), be `active`, and have phone enabled and fully configured. ## OpenAPI ````yaml /api-reference/outbound-phone-api.openapi.json post /outbound/call openapi: 3.0.1 info: title: Replify Outbound Phone API version: 1.0.0 description: >- Schedule immediate outbound phone calls for a specific assistant. **Authentication** See the [API overview](/api-reference/overview) for API keys (`x-api-key`) and required headers. This endpoint requires `Content-Type: application/json`. **Migrating from the legacy API?** If you use the [legacy Outbound Phone Calling API](/api-documentation/outbound-phone-calling-api-legacy), switch to this API by **July 1, 2026**. Your account manager can help with endpoint and testing changes. servers: - url: https://api.heylibby.com/api/v1 description: Production security: - api_key: [] paths: /outbound/call: post: tags: - Outbound Calling summary: Initiate outbound call description: >- Schedule a single outbound call for a specific assistant (`agentId`). The call is queued after validation and placed shortly. **Required headers:** `x-api-key`, `Content-Type: application/json`. **Required fields** - `agentId` — assistant that places and handles the call, can be found in the URL after selecting that assistant. - `contact.phoneNumber` — callee number in **E.164** format (e.g. `+15551234567`). - **Messaging** — send **both** `introMessage` and `voicemailMessage`, **or** send `callInstructions` alone. You cannot send only one of `introMessage` / `voicemailMessage`. **Optional fields** - `contact.firstName`, `contact.lastName`, `contact.email`; trimmed and used for assistant context. - `metadata` — custom key/value pairs (strings, numbers, or booleans) to give the assistant context. **Assistant requirements** The assistant must exist, belong to your organization (from the API key), be `active`, and have phone enabled and fully configured. operationId: initiate-outbound-call parameters: - name: Content-Type in: header required: true schema: type: string enum: - application/json description: Must be `application/json`. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OutboundCallRequest' examples: IntroAndVoicemail: summary: Intro and voicemail messages description: >- Provide both messages when you want explicit scripts for a human answer and for voicemail. value: agentId: your-agent-uuid contact: phoneNumber: '+15551234567' firstName: Jane lastName: Doe email: jane@example.com metadata: formLocation: Ballard formGoals: get in shape utmSource: facebook introMessage: >- Hi Jane, this is Libby calling from Acme Fitness, calling you back about your membership inquiry... voicemailMessage: >- Hi Jane, sorry we missed you. This is Libby from Acme Fitness. Call us back to learn about our May promotion... CallInstructions: summary: Call instructions only description: >- Use when you want the assistant to generate behavior from instructions instead of fixed intro/voicemail scripts. value: agentId: your-agent-uuid contact: phoneNumber: '+15551234567' callInstructions: >- Follow up about their membership inquiry. Be friendly and brief. responses: '200': description: Call accepted and queued. content: application/json: schema: $ref: '#/components/schemas/OutboundCallSuccessResponse' examples: Queued: summary: Call scheduled value: success: true message: Your call has been scheduled and will be placed shortly. '400': description: >- Invalid request — missing/invalid fields, incomplete messaging pair, unsupported campaign mode, or agent phone not active. content: application/json: schema: $ref: '#/components/schemas/OutboundCallErrorResponse' examples: MissingAgentId: summary: Missing agentId value: error: agentId is required InvalidPhone: summary: Invalid contact.phoneNumber value: error: contact.phoneNumber must be a valid E.164 phone number IncompleteMessaging: summary: Only one of intro/voicemail value: error: >- introMessage and voicemailMessage must both be provided, or use callInstructions instead AgentPhoneInactive: summary: Agent phone not active value: error: Agent phone status is not active '403': description: Agent not in your organization (from API key `orgId`). content: application/json: schema: $ref: '#/components/schemas/OutboundCallErrorResponse' examples: AgentNotInOrg: summary: Agent not in organization value: error: Agent does not belong to your organization '404': description: Agent not found. content: application/json: schema: $ref: '#/components/schemas/OutboundCallErrorResponse' examples: AgentNotFound: summary: Agent not found value: error: Agent not found security: - api_key: [] components: schemas: OutboundCallRequest: type: object required: - agentId - contact properties: agentId: type: string format: uuid description: Agent that places and handles the call. Required. contact: $ref: '#/components/schemas/OutboundCallContact' metadata: type: object additionalProperties: oneOf: - type: string - type: number - type: boolean description: >- Optional key/value context (e.g. form or UTM fields). Values may be strings, numbers, or booleans. introMessage: type: string description: >- Message spoken when a human answers. Must be sent together with `voicemailMessage`, unless you use `callInstructions` instead. voicemailMessage: type: string description: >- Message left when voicemail is detected. Must be sent together with `introMessage`, unless you use `callInstructions` instead. callInstructions: type: string description: >- Instructions for the call when you are not providing `introMessage` and `voicemailMessage`. Use this option alone; do not send only one of the intro/voicemail pair. OutboundCallSuccessResponse: type: object properties: success: type: boolean description: Whether the call was accepted and queued. example: true message: type: string description: Human-readable confirmation. example: Your call has been scheduled and will be placed shortly. OutboundCallErrorResponse: type: object properties: error: type: string description: Human-readable error message. OutboundCallContact: type: object required: - phoneNumber properties: phoneNumber: type: string description: Callee number in E.164 format (e.g. `+15551234567`). example: '+15551234567' firstName: type: string description: Callee first name (trimmed). Used for agent context. lastName: type: string description: Callee last name (trimmed). Used for agent context. email: type: string format: email description: Callee email. Used for agent context. securitySchemes: api_key: type: apiKey name: x-api-key in: header description: >- API key secret from API Key Management. API Gateway validates the key and forwards the request to the outbound service. ````