> ## Documentation Index
> Fetch the complete documentation index at: https://docs.callcow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger Call

> Initiates an AI phone call workflow to the specified recipient. Requires an API key for authentication.

## Idempotency

To prevent duplicate calls from retries, you can pass an optional `idempotency_key` in the request body. If the same key is sent within a 5-minute window, the API returns the cached response without creating a new call.

```json theme={null}
{
  "workflow_id": "wf_abc123xyz",
  "recipient_phone": "+14155552671",
  "idempotency_key": "order-12345-call"
}
```


## OpenAPI

````yaml POST /call
openapi: 3.1.0
info:
  title: CallCow Workflow API
  description: API to trigger AI phone call workflows
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://www.callcow.ai/api
security:
  - bearerAuth: []
paths:
  /call:
    post:
      summary: Trigger AI Phone Call
      description: >-
        Initiates an AI phone call workflow to the specified recipient. Requires
        an API key for authentication.
      operationId: triggerCall
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerCallRequest'
      responses:
        '200':
          description: Call successfully triggered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerCallSuccess'
        '400':
          description: Validation failed or invalid phone number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized — missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden — workflow belongs to a different organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded (60 requests/minute per organization)
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Failed to initiate call
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    TriggerCallRequest:
      type: object
      required:
        - recipient_phone
        - workflow_id
      properties:
        recipient_name:
          type: string
          description: Name of the call recipient
          example: John Doe
        recipient_email:
          type: string
          format: email
          description: >-
            Email address of the call recipient. Recommended for meeting booking
            calls.
          example: john@example.com
        recipient_phone:
          type: string
          description: Phone number of the call recipient in E.164 format
          example: '+14155552671'
        recipient_context:
          type: string
          description: Additional context to provide to the AI agent during the call
          example: Customer interested in premium plan
        workflow_id:
          type: string
          description: >-
            ID of the workflow to execute. Get workflow IDs from the List
            Workflows endpoint or your dashboard.
          example: wf_abc123xyz
        idempotency_key:
          type: string
          description: >-
            Optional unique key to prevent duplicate calls on retries. Scoped to
            your organization with a 5-minute TTL.
          example: order-12345-call
    TriggerCallSuccess:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Thanks! Our AI agent will call you shortly.
    ValidationError:
      type: object
      properties:
        error:
          type: string
          example: Validation failed
        details:
          type: object
          description: Zod validation error details
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key generated from Settings → API Keys. Format: `ck_live_...`'

````