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

# Create an outbound call

> Place an outbound call with one of your agents.

Returns as soon as the call is queued; it does not wait for the call to be
answered. `call.started`, `call.ended` and `call.analyzed` webhooks follow
if you have an endpoint subscribed, and `GET /v1/calls/{call_id}` returns
the current state at any time.

Retell-compatible field names are accepted as aliases: `override_agent_id`
→ `agent_id`, `retell_llm_dynamic_variables` → `variables`.
`override_agent_version` and any unknown fields are ignored, so a client
written for Retell's create-call endpoint works with only a URL change.



## OpenAPI

````yaml api-reference/openapi.json POST /v1/calls
openapi: 3.1.0
info:
  description: >-
    Programmatic access to Contour from your own backend: place outbound calls,
    read their results, and manage the webhook endpoints that receive signed
    `call.started`, `call.ended` and `call.analyzed` events.
  title: Contour API
  version: '1.0'
servers:
  - url: https://api.contourvoice.com
security:
  - HTTPBearer: []
tags:
  - description: Place outbound calls and read their state and recordings.
    name: Calls
  - description: >-
      Register URLs to receive signed events, send test events, and inspect or
      retry deliveries.
    name: Webhook Endpoints
paths:
  /v1/calls:
    post:
      tags:
        - Calls
      summary: Create an outbound call
      description: >-
        Place an outbound call with one of your agents.


        Returns as soon as the call is queued; it does not wait for the call to
        be

        answered. `call.started`, `call.ended` and `call.analyzed` webhooks
        follow

        if you have an endpoint subscribed, and `GET /v1/calls/{call_id}`
        returns

        the current state at any time.


        Retell-compatible field names are accepted as aliases:
        `override_agent_id`

        → `agent_id`, `retell_llm_dynamic_variables` → `variables`.

        `override_agent_version` and any unknown fields are ignored, so a client

        written for Retell's create-call endpoint works with only a URL change.
      operationId: create_call
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCallRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallCreatedResponse'
          description: Successful Response
        '400':
          content:
            application/json:
              example:
                detail:
                  error: Agent is not active.
                  error_code: agent_inactive
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: >-
            The agent can't place calls: `agent_not_outbound` or
            `agent_inactive`.
        '401':
          content:
            application/json:
              example:
                detail: Invalid or expired API key
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Missing or invalid API key.
        '404':
          content:
            application/json:
              example:
                detail:
                  error: Agent not found.
                  error_code: agent_not_found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '`agent_not_found`: no such agent in your organization.'
        '422':
          content:
            application/json:
              example:
                detail:
                  error: 'Required variables are missing: patient_dob'
                  error_code: missing_variables
                  missing_variables:
                    - patient_dob
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: >-
            `missing_variables` (see `missing_variables`),
            `from_number_mismatch` (see `expected_from_number`), or
            `dnc_blocked` / `number_blocked` (the number is on a do-not-call or
            block list; a call record exists with `status: failed`).
        '502':
          content:
            application/json:
              example:
                detail:
                  call_id: 9d2f7a3c-8e4b-4f1d-a6c7-2b3c4d5e6f70
                  error: Could not dispatch the call.
                  error_code: dispatch_error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: >-
            `dispatch_error` or `dispatch_failed`: transient failure placing the
            call. Safe to retry.
      security:
        - HTTPBearer: []
components:
  schemas:
    CreateCallRequest:
      examples:
        - agent_id: 3f1c1b2e-6d1a-4c0e-9b2f-1a2b3c4d5e6f
          from_number: '+15555550199'
          metadata:
            your_order_id: ORD-8812
          to_number: '+15555550100'
          variables:
            appointment_date: '2026-09-15'
            patient_name: Jane Doe
        - from_number: '+15555550199'
          metadata:
            your_order_id: ORD-8812
          override_agent_id: 3f1c1b2e-6d1a-4c0e-9b2f-1a2b3c4d5e6f
          override_agent_version: 2
          retell_llm_dynamic_variables:
            patient_name: Jane Doe
          to_number: '+15555550100'
      properties:
        agent_id:
          description: >-
            The agent to place the call with. Contour gives you this id. Retell
            alias: `override_agent_id`.
          format: uuid
          title: Agent Id
          type: string
        from_number:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Caller ID. Optional; if sent it must equal the agent's configured
            outbound number or the request is rejected with
            `from_number_mismatch`.
          title: From Number
        metadata:
          additionalProperties: true
          description: >-
            Any JSON object. Stored untouched and echoed back on every webhook
            and on `GET /v1/calls/{call_id}`.
          title: Metadata
          type: object
        to_number:
          description: Number to dial. E.164 (`+1...`) preferred.
          title: To Number
          type: string
        variables:
          additionalProperties: true
          description: >-
            Per-call values the agent's script uses. Some are required per
            agent; a missing one is a `422` listing the keys. Retell alias:
            `retell_llm_dynamic_variables`.
          title: Variables
          type: object
      required:
        - agent_id
        - to_number
      title: CreateCallRequest
      type: object
    CallCreatedResponse:
      examples:
        - agent_id: 3f1c1b2e-6d1a-4c0e-9b2f-1a2b3c4d5e6f
          call_id: 9d2f7a3c-8e4b-4f1d-a6c7-2b3c4d5e6f70
          created_at: '2026-09-10T14:03:11.412Z'
          from_number: '+15555550199'
          status: queued
          to_number: '+15555550100'
      properties:
        agent_id:
          description: The agent placing the call.
          format: uuid
          title: Agent Id
          type: string
        call_id:
          description: >-
            Stable for the life of the call: the same id on every webhook and on
            `GET /v1/calls/{call_id}`.
          title: Call Id
          type: string
        created_at:
          description: When the call was accepted.
          format: date-time
          title: Created At
          type: string
        from_number:
          anyOf:
            - type: string
            - type: 'null'
          description: The caller ID the call is placed from.
          title: From Number
        status:
          description: Always `queued` on creation.
          title: Status
          type: string
        to_number:
          description: The number being dialed.
          title: To Number
          type: string
      required:
        - call_id
        - status
        - agent_id
        - to_number
        - created_at
      title: CallCreatedResponse
      type: object
    ErrorResponse:
      description: |-
        Every error is wrapped in a `detail` key. Validation and dispatch
        failures carry an object; auth and not-found errors carry a string.
      properties:
        detail:
          anyOf:
            - $ref: '#/components/schemas/ErrorDetail'
            - type: string
          description: An `ErrorDetail` object, or a plain message.
          title: Detail
      required:
        - detail
      title: ErrorResponse
      type: object
    ErrorDetail:
      description: |-
        Structured error body for validation and dispatch failures on
        `POST /v1/calls`.
      properties:
        call_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            With dispatch failures: the id of the call record that was created
            and marked `failed`.
          title: Call Id
        error:
          description: Human-readable explanation.
          title: Error
          type: string
        error_code:
          description: >-
            Machine-readable code: `agent_not_found`, `agent_not_outbound`,
            `agent_inactive`, `missing_variables`, `from_number_mismatch`,
            `dnc_blocked`, `number_blocked`, `dispatch_error`,
            `dispatch_failed`.
          title: Error Code
          type: string
        expected_from_number:
          anyOf:
            - type: string
            - type: 'null'
          description: 'With `from_number_mismatch`: the caller ID to send.'
          title: Expected From Number
        missing_variables:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: 'With `missing_variables`: the variable keys to add.'
          title: Missing Variables
      required:
        - error
        - error_code
      title: ErrorDetail
      type: object
  securitySchemes:
    HTTPBearer:
      description: >-
        Your organization's API key (`sk_cont_...`), sent as `Authorization:
        Bearer sk_cont_...`. Keep it server-side.
      scheme: bearer
      type: http

````