> ## Documentation Index > Fetch the complete documentation index at: https://docs.uselevers.com/llms.txt > Use this file to discover all available pages before exploring further. > Initiate bulk AI-powered phone calls to multiple contacts simultaneously # Call Contact Bulk ## Authorization All endpoints require Bearer token authentication. | Header | Type | Required | Description | | --------------- | ------ | -------- | --------------------------------------------------------- | | `Authorization` | string | Yes | Bearer authentication header of the form `Bearer ` | ### Getting Your API Key See the [Quickstart guide](/quickstart) for instructions on obtaining your API credentials. ## Use Cases * **Mass Collections Campaigns**: Send AI-powered payment reminders to many contacts at once * **Batch Customer Outreach**: Handle routine communication across your contact database efficiently * **Scalable Follow-ups**: Follow up on overdue invoices at scale with personalized conversations ## Request Body | Parameter | Type | Required | Description | | ---------------------- | ------------- | -------- | ----------------------------------------------------------------------------------------------------------- | | `contacts` | array | Yes | List of contact objects to call. Each requires `numberToCall`. See [Contact Object](#contact-object). | | `aiSettingsTemplateId` | string (UUID) | No | AI settings template ID for customizing call behavior (applied to all contacts) | | `updateExisting` | boolean | No | When `true`, updates `firstName`, `lastName`, and `email` if an existing contact is found. Default: `false` | | `countryCode` | string | No | ISO 3166-1 alpha-2 region code (e.g. 'SA', 'US') to parse local numbers | | `batchSize` | integer | No | Batch size for processing contacts. Must be between 10 and 1000. Overrides environment variable if provided | ### Contact Object Each object in the `contacts` array: | Parameter | Type | Required | Description | | -------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------- | | `numberToCall` | string | Yes | Phone number to call | | `firstName` | string | No | Contact's first name | | `lastName` | string | No | Contact's last name | | `metadata` | object | No | Extra payload data included in webhook responses as `requestMetadata` | | `promptTags` | object | No | Key-value pairs for variable substitution in the system prompt template. See [Prompt Tags](#prompt-tags). | ## Response Returns a 201 status on successful initiation of all calls. ## Example Request ```json theme={null} { "aiSettingsTemplateId": "550e8400-e29b-41d4-a716-446655440000", "countryCode": "SA", "updateExisting": true, "batchSize": 50, "contacts": [ { "numberToCall": "+966500000001", "firstName": "Ahmed", "lastName": "Al-Rashid", "metadata": { "invoiceNumber": "INV-001", "amount": "5000.00" }, "promptTags": { "amount": "5,000 SAR", "due_date": "January 15, 2026" } }, { "numberToCall": "+966500000002", "firstName": "Sara", "lastName": "Mohammed", "metadata": { "invoiceNumber": "INV-002", "amount": "3200.00" }, "promptTags": { "amount": "3,200 SAR", "due_date": "January 20, 2026" } } ] } ``` ## Prompt Tags `promptTags` is an optional object of key-value pairs used for **template variable substitution** in the system prompt. Each key maps to a placeholder in your prompt template, and the value replaces it before the call starts. This is separate from `metadata` — `metadata` is stored on the call log and included in webhooks, while `promptTags` is consumed at call time to populate the system prompt. ### How It Works Your system prompt template uses `{{key}}` placeholders. When each call is initiated, the `{{key}}` from that contact's `promptTags` is replaced. **System prompt template:** ``` You are a collections agent. The customer owes {{amount}} due by {{due_date}}. Be professional and offer payment plan options if the customer cannot pay in full. ``` **Per-contact promptTags (from the contacts array):** ```json theme={null} { "amount": "5,000 SAR", "due_date": "January 15, 2026" } ``` **Resulting system prompt for that contact:** ``` You are a collections agent. The customer owes 5,000 SAR due by January 15, 2026. Be professional and offer payment plan options if the customer cannot pay in full. ``` ### Prompt Tags vs Metadata | Field | Purpose | Where It Goes | | ------------ | --------------------------------------------------- | --------------------------------------------------------------------- | | `promptTags` | Variable substitution in the system prompt template | Consumed at call time, injected into the prompt | | `metadata` | Arbitrary data attached to the call record | Stored on call log, included in webhook payloads as `requestMetadata` | ## OpenAPI ````yaml post /ai/phone-calls/action/call-bulk openapi: 3.1.0 info: title: api_service description: Provide API endpoints for other services version: 0.169.9 servers: - url: /api-service/v1 security: - JWTAuth: [] paths: /ai/phone-calls/action/call-bulk: post: tags: - ai-features - Phone Calls - public summary: Call Contact Bulk operationId: call_contact_bulk_ai_phone_calls_action_call_bulk_post requestBody: content: application/json: schema: $ref: '#/components/schemas/OutboundAIPhoneCallSchemaBulk' required: true responses: '201': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: OutboundAIPhoneCallSchemaBulk: properties: aiSettingsTemplateId: anyOf: - type: string format: uuid - type: 'null' title: Aisettingstemplateid updateExisting: type: boolean title: Updateexisting default: false contacts: items: $ref: '#/components/schemas/_BulkContactSchema' type: array title: Contacts countryCode: anyOf: - type: string maxLength: 2 minLength: 2 pattern: ^[A-Z]{2}$ - type: 'null' title: Countrycode description: >- ISO 3166-1 alpha-2 region code (e.g. 'SA', 'US') to parse local numbers. batchSize: anyOf: - type: integer - type: 'null' title: Batchsize description: >- Batch size for processing contacts. Must be between 10 and 1000. Overrides environment variable if provided. type: object required: - contacts title: OutboundAIPhoneCallSchemaBulk HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError _BulkContactSchema: properties: numberToCall: type: string maxLength: 100 minLength: 1 title: Numbertocall firstName: anyOf: - type: string - type: 'null' title: Firstname lastName: anyOf: - type: string - type: 'null' title: Lastname metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata promptTags: anyOf: - additionalProperties: true type: object - type: 'null' title: Prompttags description: >- Key-value pairs injected as template variables into system/knowledge base prompt. type: object required: - numberToCall title: _BulkContactSchema ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: JWTAuth: type: http scheme: bearer bearerFormat: JWT description: >- Enter JWT token obtained from authentication endpoint. Format: Bearer ````