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

# Start a call

> Queues a call to one number and dials it as soon as a line is free and calling hours allow. Returns the call at once (usually `queued` or `dialing`); the outcome arrives on your webhook, or poll `GET /calls/{id}`.

Scope: `calls:write`.



## OpenAPI

````yaml /api-reference/openapi.json post /calls
openapi: 3.1.0
info:
  title: Telleo API
  version: 1.0.0
  description: Start AI phone calls from your own systems and get each call's outcome back.
servers:
  - url: https://api.telleo.ai/v1
security:
  - ApiKey: []
tags:
  - name: Calls
  - name: Batches
  - name: Agents
  - name: Webhook
paths:
  /calls:
    post:
      tags:
        - Calls
      summary: Start a call
      description: >-
        Queues a call to one number and dials it as soon as a line is free and
        calling hours allow. Returns the call at once (usually `queued` or
        `dialing`); the outcome arrives on your webhook, or poll `GET
        /calls/{id}`.


        Scope: `calls:write`.
      operationId: createCall
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            maxLength: 255
          description: >-
            Any unique string, e.g. your lead id. Retrying with the same key and
            body returns the first call instead of calling twice.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCall'
            example:
              agent_id: 17ea33d2-5b6c-4c1e-9a1f-2d4e6f8a9b0c
              phone_number: '+919876543210'
              contact:
                name: Asha Verma
                external_id: lead-8812
              variables:
                course: NEET 2027
      responses:
        '200':
          description: >-
            Replay: a call with this `Idempotency-Key` already exists and is
            returned unchanged (`idempotent_replay: true`).
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Call'
        '201':
          description: The call was created.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Call'
              example:
                id: call_6f1d2c9a8b7e4f3a2d1c0b9a
                object: call
                status: queued
                agent_id: 17ea33d2-5b6c-4c1e-9a1f-2d4e6f8a9b0c
                phone_number: '+919876543210'
                contact:
                  name: Asha Verma
                  email: asha@example.com
                  external_id: lead-8812
                variables:
                  course: NEET 2027
                  city: Indore
                metadata:
                  crm_owner: u_42
                batch_id: null
                test: false
                duration_seconds: null
                created_at: '2026-10-13T09:30:02Z'
                dialed_at: null
                ended_at: null
                recording_url: null
                recording_expires_at: null
                outcome: null
        '400':
          description: The request is not valid.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    error:
                      code: invalid_request
                      message: >-
                        phone_number must be in E.164 format, e.g.
                        +919876543210.
                      request_id: req_8f2c1a7e
        '401':
          description: The key is missing, unknown, revoked or expired.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_api_key:
                  value:
                    error:
                      code: missing_api_key
                      message: Send your API key in the X-API-Key header.
                      request_id: req_8f2c1a7e
                invalid_api_key:
                  value:
                    error:
                      code: invalid_api_key
                      message: This API key is not valid.
                      request_id: req_8f2c1a7e
        '402':
          description: Your account is out of calling credits.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                insufficient_credits:
                  value:
                    error:
                      code: insufficient_credits
                      message: >-
                        This account is out of AI calling credits. Top up to
                        place calls.
                      request_id: req_8f2c1a7e
        '403':
          description: The key lacks the scope this request needs.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                insufficient_scope:
                  value:
                    error:
                      code: insufficient_scope
                      message: This key does not have the calls:write scope.
                      request_id: req_8f2c1a7e
        '404':
          description: The agent does not exist.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                agent_not_found:
                  value:
                    error:
                      code: agent_not_found
                      message: >-
                        No agent 17ea33d2-… in this account. List your agents
                        with GET /v1/agents.
                      request_id: req_8f2c1a7e
        '409':
          description: >-
            The call conflicts with an existing one or the agent cannot call
            out.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                call_already_queued:
                  value:
                    error:
                      code: call_already_queued
                      message: This number already has a call waiting for a line.
                      request_id: req_8f2c1a7e
                idempotency_key_reused:
                  value:
                    error:
                      code: idempotency_key_reused
                      message: This Idempotency-Key was used for a different request.
                      request_id: req_8f2c1a7e
                agent_disabled:
                  value:
                    error:
                      code: agent_disabled
                      message: Agent 17ea33d2-… is turned off.
                      request_id: req_8f2c1a7e
                agent_inbound_only:
                  value:
                    error:
                      code: agent_inbound_only
                      message: Agent 17ea33d2-… only answers incoming calls.
                      request_id: req_8f2c1a7e
        '429':
          description: Too many requests for this key.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying.
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rate_limited:
                  value:
                    error:
                      code: rate_limited
                      message: Too many requests. Retry after 12 seconds.
                      request_id: req_8f2c1a7e
components:
  schemas:
    CreateCall:
      allOf:
        - $ref: '#/components/schemas/CallInput'
        - type: object
          required:
            - agent_id
          properties:
            test:
              type: boolean
              default: false
              description: >-
                Simulate the call: no phone rings and nothing is billed. It
                completes at once with a sample outcome and fires your webhook.
    Call:
      type: object
      properties:
        id:
          type: string
          example: call_6f1d2c9a8b7e4f3a2d1c0b9a
        object:
          type: string
          const: call
        status:
          type: string
          enum:
            - queued
            - dialing
            - in_progress
            - completed
            - no_answer
            - busy
            - failed
            - canceled
            - expired
        status_reason:
          type: string
          description: >-
            Why a call is waiting or did not happen, in plain words. Present
            only when there is one.
        scheduled_for:
          type: string
          format: date-time
          description: >-
            Present while a queued call is held until a later time (outside
            calling hours, a recall gap, the daily limit).
        agent_id:
          type: string
        phone_number:
          type: string
        contact:
          $ref: '#/components/schemas/Contact'
        variables:
          type: object
          additionalProperties: true
        metadata:
          type: object
          additionalProperties: true
        batch_id:
          type:
            - string
            - 'null'
        test:
          type: boolean
        duration_seconds:
          type:
            - integer
            - 'null'
        created_at:
          type: string
          format: date-time
        dialed_at:
          type:
            - string
            - 'null'
          format: date-time
        ended_at:
          type:
            - string
            - 'null'
          format: date-time
        recording_url:
          type:
            - string
            - 'null'
          description: >-
            A temporary link to the recording. Fetch the call again for a fresh
            link after `recording_expires_at`.
        recording_expires_at:
          type:
            - string
            - 'null'
          format: date-time
        outcome:
          $ref: '#/components/schemas/Outcome'
        idempotent_replay:
          type: boolean
          description: >-
            Only on `POST /calls`: `true` when this is the call created by an
            earlier request with the same `Idempotency-Key`.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Machine-readable code. Branch on this, not on the message.
              example: invalid_request
            message:
              type: string
              description: A sentence you can log or show to an operator.
            request_id:
              type: string
              description: Quote this when you contact support.
            details:
              type: object
              additionalProperties: true
              description: >-
                Extra context, e.g. `errors: [{field, message}]` for validation
                errors or `call_id` for conflicts.
    CallInput:
      type: object
      required:
        - phone_number
      properties:
        agent_id:
          type: string
          description: >-
            The agent that makes the call. Required on `POST /calls`; on a batch
            row it overrides the batch's `agent_id`. List yours with `GET
            /agents`.
        phone_number:
          type: string
          description: >-
            E.164, e.g. `+919876543210`. Spaces, dashes, dots and brackets are
            ignored; a leading `00` is read as `+`.
          example: '+919876543210'
        contact:
          $ref: '#/components/schemas/Contact'
        variables:
          type: object
          maxProperties: 50
          additionalProperties:
            type:
              - string
              - number
              - boolean
          description: >-
            Values for the `{{placeholders}}` in the agent's script. Keys: a
            letter, then letters, digits, `_` or spaces, at most 40 characters.
            Values: text, number or boolean, at most 500 characters.
          example:
            course: NEET 2027
            city: Indore
        metadata:
          type: object
          additionalProperties: true
          description: >-
            Anything you want back on the call and its webhook (at most 8 KB as
            JSON). The agent never sees it.
          example:
            crm_owner: u_42
    Contact:
      type: object
      properties:
        name:
          type:
            - string
            - 'null'
          maxLength: 120
          description: >-
            How the agent addresses the person. Fills `{{name}}` in the agent's
            script.
        email:
          type:
            - string
            - 'null'
          format: email
        external_id:
          type:
            - string
            - 'null'
          maxLength: 255
          description: >-
            Your own id for this person or lead (CRM record id). Echoed back and
            filterable on `GET /calls`.
    Outcome:
      type:
        - object
        - 'null'
      description: >-
        What the AI took from the conversation. `null` until it has been
        processed (usually within a minute of the call ending), and for calls
        that did not connect.
      properties:
        disposition:
          type:
            - string
            - 'null'
          description: >-
            The agent's label for how the call went, from the dispositions
            configured on the agent (e.g. Interested, Not interested, Call back
            later).
        summary:
          type:
            - string
            - 'null'
        answers:
          type: object
          additionalProperties: true
          description: Each of the agent's extraction questions and the answer given.
        lead_rating:
          type:
            - integer
            - 'null'
          minimum: 1
          maximum: 10
          description: >-
            The AI's 1–10 score of the contact's interest; `null` when it could
            not tell.
        callback_requested:
          type: boolean
        callback_time_text:
          type:
            - string
            - 'null'
          description: >-
            When the contact asked to be called back, in their words (e.g.
            `tomorrow after 6 pm`).
        follow_up:
          type:
            - string
            - 'null'
          enum:
            - CALL
            - CALL_LATER
            - SKIP
            - null
          description: >-
            Whether a person should call this contact: `CALL` (now),
            `CALL_LATER` or `SKIP`. `null` when not assessed; never read `null`
            as `CALL`.
        follow_up_note:
          type:
            - string
            - 'null'
          description: >-
            One sentence on why, for the person deciding whether to call (at
            most 240 characters).
        meeting:
          type: object
          description: >-
            A meeting, demo, visit or callback the contact AGREED to at a
            specific day or time. `requested` is false when no time was agreed.
          properties:
            requested:
              type: boolean
            at:
              type:
                - string
                - 'null'
              description: >-
                ISO-8601 with offset, resolved from what was said, e.g.
                `2026-10-14T18:00:00+05:30`.
            time_text:
              type:
                - string
                - 'null'
              description: The contact's own words, e.g. `tomorrow 6 pm`.
            type:
              type:
                - string
                - 'null'
              description: '`demo`, `visit`, `call` or `meeting`.'
        transcript:
          type: array
          items:
            type: object
            properties:
              speaker:
                type: string
                enum:
                  - agent
                  - contact
              text:
                type: string
  headers:
    RequestId:
      schema:
        type: string
      description: Unique id of this request. Quote it to support.
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Your AI calling API key (`vak_call_…`). `Authorization: Bearer <key>`
        also works.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.