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

# Place a call

> Start an outbound voice call with one of your agents.

<Note>
  The `202` is an acknowledgement — the call dials asynchronously. Track its outcome via
  [webhooks](/developers/webhooks/overview) or [`GET /v1/calls/{id}`](/developers/calls/get).
</Note>


## OpenAPI

````yaml developers/openapi.json POST /v1/calls
openapi: 3.1.0
info:
  title: Vocily API
  description: >-
    Public REST API for placing outbound voice calls and reading their results.
    Authenticate with a workspace API key as a Bearer token.
  version: v1
servers:
  - url: https://api.vocily.com
    description: Production
security: []
paths:
  /v1/calls:
    post:
      tags:
        - calls
      summary: Place a call
      description: >-
        Start an outbound call with one of your agents. Returns a `202`
        acknowledgement with the call's `execution_id`; the call then dials and
        runs asynchronously — track it with
        [webhooks](/developers/webhooks/overview) or `GET /v1/calls/{id}`. An
        `Idempotency-Key` header is required.
      operationId: create_outbound_call_v1_calls_post
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Idempotency-Key
        - name: authorization
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
        - name: X-Vocily-Workspace
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Vocily-Workspace
        - name: X-Vocily-Org
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Vocily-Org
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallCreate'
            example:
              agent_id: 9b1c3d5e-7a90-4c21-8b6d-2e4f6a8c0d11
              to_number: '+919876543210'
              from_number: '+911171366867'
              variables:
                customer_name: Rahul
              metadata:
                order_id: '88431'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallRead'
              example:
                execution_id: c7a1e2b3-4d5f-6789-a0b1-c2d3e4f5a6b7
                call_sid: null
                status: started
                message: Outbound call initiated; it will begin dialing shortly
                metadata:
                  order_id: '88431'
        '400':
          description: The Idempotency-Key header is required for API-key requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                code: idempotency_key_required
                message: The Idempotency-Key header is required for API-key requests.
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                code: unauthorized
                message: Missing or invalid API key.
        '402':
          description: Wallet balance is below the reserve required for this call.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                code: insufficient_balance
                message: Wallet balance is below the reserve required for this call.
        '403':
          description: This API key is not permitted to use that agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                code: agent_not_allowed
                message: This API key is not permitted to use that agent.
        '404':
          description: Agent not found in this workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                code: agent_not_found
                message: Agent not found in this workspace.
        '409':
          description: All outbound lines are currently in use.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                code: concurrency_exceeded
                message: All outbound lines are currently in use.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate limit exceeded — honor Retry-After.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                code: rate_limited
                message: Rate limit exceeded — honor Retry-After.
        '501':
          description: The telephony provider is not configured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                code: provider_not_configured
                message: The telephony provider is not configured.
      security:
        - bearerAuth: []
components:
  schemas:
    CallCreate:
      properties:
        agent_id:
          type: string
          title: Agent Id
          description: Agent to use for the call
        to_number:
          type: string
          title: To Number
          description: Destination number (E.164)
        from_number:
          anyOf:
            - type: string
            - type: 'null'
          title: From Number
          description: Our number (must be in workspace); optional if only one number
        variables:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Variables
          description: 'Prompt variables e.g. {customer_name: ''Rahul''}'
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
          description: Opaque customer JSON, stored + echoed on reads/webhooks
      type: object
      required:
        - agent_id
        - to_number
      title: CallCreate
      description: Outbound call request.
    CallRead:
      properties:
        execution_id:
          type: string
          title: Execution Id
        call_sid:
          anyOf:
            - type: string
            - type: 'null'
          title: Call Sid
        status:
          type: string
          title: Status
          default: started
        message:
          type: string
          title: Message
          default: Outbound call initiated; it will begin dialing shortly
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
      type: object
      required:
        - execution_id
      title: CallRead
      description: Outbound call response.
    ApiError:
      type: object
      properties:
        code:
          type: string
          example: invalid_request
        message:
          type: string
          example: Malformed request parameter.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your API key as a Bearer token, e.g. `Authorization: Bearer vk_…`.'

````