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

# Create a call



## OpenAPI

````yaml POST /v1/calls
openapi: 3.0.1
info:
  title: Volubile API
  version: v1
servers:
  - url: https://api.eu.volubile.ai
    description: Generated server url
security: []
paths:
  /v1/calls:
    post:
      tags:
        - Call
      summary: Create a call
      operationId: create_1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCallRequest'
        required: true
      responses:
        '201':
          description: Created
          headers:
            X-CallRateLimit-Limit:
              description: >-
                Maximum number of concurrent scheduled outbound calls allowed on
                the platform
              style: simple
              schema:
                type: integer
            X-CallRateLimit-Remaining:
              description: >-
                Number of remaining concurrent scheduled outbound calls
                available
              style: simple
              schema:
                type: integer
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            Unauthorized access. The request has not been applied because it
            lacks valid authentication credentials.

            Possible reasons include that the API key is missing from the
            request headers, the provided API key is disabled,

            or the API key is associated with a customer account that is
            disabled.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - Api key: []
        - Bearer token: []
components:
  schemas:
    CreateCallRequest:
      required:
        - agentId
        - recipient
      type: object
      properties:
        agentId:
          type: string
          description: Unique identifier of the OUTBOUND agent to use for the call
          format: uuid
        campaignId:
          type: string
          description: Unique identifier of a callback campaign
          format: uuid
        recipient:
          $ref: '#/components/schemas/CreateCallRecipientRequest'
    ErrorResponse:
      type: object
      properties:
        timestamp:
          type: string
          description: |
            Date and time when the error occurs.

            Format: UTC time - yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
          format: date-time
        status:
          type: integer
          description: Http status code
          format: int32
        message:
          type: string
          description: Information about the error
        errors:
          type: array
          description: List of specific validation errors
          items:
            $ref: '#/components/schemas/ValidationError'
    CreateCallRecipientRequest:
      required:
        - phone
      type: object
      properties:
        phone:
          type: string
          description: Phone number to call, in the E.164 international standard format
          example: '+33612345678'
        context:
          type: object
          additionalProperties:
            type: object
            description: >
              Custom object for dynamic content injection into the agent prompt.

              Keys in this map correspond to placeholders in the prompt
              template: e.g {{ firstName }}.

              At runtime, each placeholder will be replaced with its
              corresponding value.

              ⚠️ All sent variables not found in configured agent prompt will be
              ignored.
            example:
              firstName: firstname
              lastName: lastname
              orderNumber: 5HZ99FRT
          description: >
            Custom object for dynamic content injection into the agent prompt.

            Keys in this map correspond to placeholders in the prompt template:
            e.g {{ firstName }}.

            At runtime, each placeholder will be replaced with its corresponding
            value.

            ⚠️ All sent variables not found in configured agent prompt will be
            ignored.
          example:
            firstName: firstname
            lastName: lastname
            orderNumber: 5HZ99FRT
        segmentationTags:
          type: array
          description: Optional list of segmentationTags to categorize or label the call
          example:
            - reg:aura
            - client:165265
            - existing-customer
          items:
            type: string
            description: Optional list of segmentationTags to categorize or label the call
            example: '["reg:aura","client:165265","existing-customer"]'
      description: Recipient to call
    ValidationError:
      type: object
      properties:
        field:
          type: string
          description: Field in error
        rejectedValue:
          type: object
          description: Value in error
        message:
          type: string
          description: Description of the failed validation
      description: List of specific validation errors
  securitySchemes:
    Api key:
      type: apiKey
      description: Your API key.
      name: X-Api-Key
      in: header
    Bearer token:
      type: http
      description: Short lived Bearer token issued by /v1/auth/token.
      scheme: bearer
      bearerFormat: JWT

````