> ## Documentation Index > Fetch the complete documentation index at: https://docs.payable.run/llms.txt > Use this file to discover all available pages before exploring further. # Request an AI collection call > Queues an outbound call to the client about a debt. `medium=whatsapp` first asks the debtor for WhatsApp call permission and dials once accepted. Returns the call row (status `queued` or `awaiting_permission`) plus soft `warnings`. Errors: `VOICE_CALLS_DISABLED`, `VOICE_MEDIUM_UNAVAILABLE`, `VOICE_INVALID_PHONE`, `CHANNEL_OPTED_OUT`, `CALL_IN_PROGRESS`, `OUTSIDE_CALL_WINDOW`, `VOICE_DAILY_ATTEMPTS_REACHED`, `INSUFFICIENT_BALANCE`. ## OpenAPI ````yaml /openapi.json post /api/v1/voice-calls openapi: 3.0.0 info: title: Payable API description: >- REST API for integrating with Payable programmatically. Authenticate with Clerk JWT (web app) or API keys (`esk_live_` / `esk_test_`). Test keys operate in sandbox mode without wallet charges or real WhatsApp. Request bodies and query parameters are documented from class-validator / class-transformer DTOs. Every error is RFC 9457 `application/problem+json`; branch on `code`, not `detail`. version: '1.0' contact: {} servers: - url: https://api.payable.run description: Production - url: https://localhost:3000 description: Local security: [] tags: [] paths: /api/v1/voice-calls: post: tags: - voice-calls summary: Request an AI collection call description: >- Queues an outbound call to the client about a debt. `medium=whatsapp` first asks the debtor for WhatsApp call permission and dials once accepted. Returns the call row (status `queued` or `awaiting_permission`) plus soft `warnings`. Errors: `VOICE_CALLS_DISABLED`, `VOICE_MEDIUM_UNAVAILABLE`, `VOICE_INVALID_PHONE`, `CHANNEL_OPTED_OUT`, `CALL_IN_PROGRESS`, `OUTSIDE_CALL_WINDOW`, `VOICE_DAILY_ATTEMPTS_REACHED`, `INSUFFICIENT_BALANCE`. operationId: VoiceController_create parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateVoiceCallDto' responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/VoiceCallResponseDto' default: description: RFC 9457 problem details. Inspect `code` for programmatic handling. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' security: - bearer: [] components: schemas: CreateVoiceCallDto: type: object properties: clientId: type: string format: uuid description: Client to call debtId: type: string format: uuid description: >- Open debt the call is about. Calls are always tied to a charge of this client. medium: type: string enum: - pstn - whatsapp description: >- `pstn` = regular phone call; `whatsapp` = WhatsApp voice call (asks the debtor for call permission first). Defaults to the flow setting. allowOutsideWindow: type: boolean description: >- Place the call even outside the flow calling window (API keys only; the dashboard always may, with a warning). fallbackToPstn: type: boolean description: >- WhatsApp medium only: fall back to a regular phone call when the debtor denies or ignores the permission request. Default true. dryRunOutcome: type: string description: 'Local dry-run provider only: which outcome to simulate.' enum: - negotiated - promise_to_pay - paid_during_call - callback_requested - refused - no_answer - busy - voicemail - wrong_number - transferred_to_human - permission_denied - failed required: - clientId - debtId VoiceCallResponseDto: type: object properties: id: type: string format: uuid organizationId: type: string format: uuid clientId: type: string format: uuid debtId: type: object format: uuid nullable: true enrollmentId: type: object format: uuid nullable: true stepExecutionId: type: object format: uuid nullable: true conversationId: type: object format: uuid nullable: true provider: type: string example: retell providerCallId: type: object nullable: true medium: type: string enum: - pstn - whatsapp direction: type: string enum: - outbound - inbound fromNumber: type: object nullable: true toNumber: type: string example: '+5511999990000' status: type: string enum: - queued - awaiting_permission - dialing - in_progress - completed - failed - cancelled outcome: type: string enum: - negotiated - promise_to_pay - paid_during_call - callback_requested - refused - no_answer - busy - voicemail - wrong_number - transferred_to_human - permission_denied - failed nullable: true trigger: type: string enum: - manual - flow - api - retry attemptNumber: type: number requestedByUserId: type: object nullable: true scheduledFor: type: object nullable: true startedAt: type: object nullable: true answeredAt: type: object nullable: true endedAt: type: object nullable: true durationSeconds: type: object nullable: true hasRecording: type: boolean description: >- Whether a recording can be fetched via GET /voice-calls/:id/recording transcript: nullable: true type: array items: $ref: '#/components/schemas/VoiceTranscriptTurnDto' summary: type: object nullable: true analysis: nullable: true allOf: - $ref: '#/components/schemas/VoiceCallAnalysisDto' promiseToPayAmount: type: object nullable: true promiseToPayDate: type: object nullable: true example: '2026-06-15' callbackRequestedAt: type: object nullable: true transferredTo: type: object nullable: true transferredAt: type: object nullable: true disconnectionReason: type: object nullable: true billedAmountCents: type: object nullable: true billedMinutes: type: object nullable: true errorMessage: type: object nullable: true warnings: type: array items: type: string createdAt: type: string updatedAt: type: string client: nullable: true allOf: - $ref: '#/components/schemas/VoiceCallClientDto' debt: nullable: true allOf: - $ref: '#/components/schemas/VoiceCallDebtDto' required: - id - organizationId - clientId - provider - medium - direction - toNumber - status - trigger - attemptNumber - hasRecording - createdAt - updatedAt ProblemDetails: type: object required: - type - title - status - detail - instance - code - requestId properties: type: type: string format: uri example: https://docs.payable.run/errors/validation_error title: type: string example: Bad Request status: type: integer example: 400 detail: type: string example: One or more request fields are invalid. instance: type: string example: /api/v1/clients code: type: string example: VALIDATION_ERROR requestId: type: string format: uuid errors: type: array items: type: object required: - message properties: field: type: string message: type: string VoiceTranscriptTurnDto: type: object properties: role: type: string enum: - agent - user content: type: string startSeconds: type: object nullable: true required: - role - content VoiceCallAnalysisDto: type: object properties: outcome: type: string enum: - negotiated - promise_to_pay - paid_during_call - callback_requested - refused - no_answer - busy - voicemail - wrong_number - transferred_to_human - permission_denied - failed summary: type: string confidence: type: number minimum: 0 maximum: 100 promiseToPayDate: type: object nullable: true promiseToPayAmount: type: object nullable: true source: type: string enum: - deterministic - model - provider required: - outcome - summary - confidence - source VoiceCallClientDto: type: object properties: id: type: string format: uuid firstName: type: string lastName: type: string phone: type: string nullable: true required: - id - firstName - lastName - phone VoiceCallDebtDto: type: object properties: id: type: string format: uuid productName: type: string amount: type: string example: '230.00' dueDate: type: string example: '2026-06-10' required: - id - productName - amount - dueDate securitySchemes: bearer: scheme: bearer bearerFormat: API Key or JWT type: http description: >- Use `Authorization: Bearer esk_live_...` or `esk_test_...` for API access ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.