openapi: 3.0.3
info:
  title: Exotel Call Details Voice API
  description: 'Exotel is an Indian cloud telephony and customer-engagement (CPaaS) platform. This OpenAPI describes a representative, grounded subset of Exotel''s documented public REST API: placing outbound voice calls (connect two numbers, or connect a number to a call flow / applet), sending SMS, retrieving call details, looking up phone-number metadata, and managing call campaigns.


    Base URL is region-specific and Twilio-style: `https://<subdomain>/v1/Accounts/<account_sid>/...` for the v1 telephony APIs and `https://<subdomain>/v2/accounts/<account_sid>/...` for the v2 Campaigns API. All requests use HTTP Basic authentication with your API Key as the username and API Token as the password (credentials may also be embedded in the URL as `https://<key>:<token>@<subdomain>/...`).


    GROUNDING NOTE: Endpoint paths and HTTP methods for Calls/connect, Calls/{CallSid}, Numbers/{Number}, Sms/send, and the v2 Campaigns resource are confirmed from Exotel''s developer docs. Request/response SCHEMAS below are MODELED from the documented parameter lists and Exotel''s Twilio-style conventions - Exotel does not publish a machine OpenAPI, so field-level schemas should be verified against the live docs before production use. Exotel APIs return XML by default; append `.json` to a resource path to receive JSON (shown here as the JSON variants).'
  version: '1.0'
  contact:
    name: Exotel Developer Support
    url: https://developer.exotel.com
  x-grounding:
    confirmedEndpoints:
    - POST /v1/Accounts/{sid}/Calls/connect
    - GET /v1/Accounts/{sid}/Calls/{CallSid}
    - GET /v1/Accounts/{sid}/Numbers/{Number}
    - POST /v1/Accounts/{sid}/Sms/send
    - POST /v2/accounts/{sid}/campaigns
    - GET /v2/accounts/{sid}/campaigns/{campaign_id}
    - GET /v2/accounts/{sid}/campaigns/{campaign_id}/call-details
    modeledEndpoints:
    - GET /v1/Accounts/{sid}/Calls (bulk list; documented as existing, path follows Exotel convention)
    - GET /v1/Accounts/{sid}/Sms/Messages/{SmsSid} (SMS details; documented as existing, path follows Exotel convention)
    schemaStatus: All request/response body and form-field schemas are modeled from documented parameter lists, not from a vendor-published OpenAPI.
servers:
- url: https://api.exotel.com
  description: Singapore cluster (default)
- url: https://api.in.exotel.com
  description: Mumbai / India cluster
security:
- basicAuth: []
tags:
- name: Voice
  description: Place and control outbound voice calls.
paths:
  /v1/Accounts/{sid}/Calls/connect.json:
    parameters:
    - $ref: '#/components/parameters/AccountSid'
    post:
      operationId: connectCall
      tags:
      - Voice
      summary: Connect two numbers or connect a number to a call flow
      description: Places an outbound call. In the "connect two numbers" mode, Exotel first calls `From`, and when answered connects to `To`. In the "connect to a flow" mode, provide `Url` pointing to an Exotel call flow (App/applet, e.g. `http://my.exotel.com/{sid}/exoml/start_voice/{flow_id}`) instead of `To`. Confirmed endpoint; body schema modeled from documented form parameters.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ConnectCallRequest'
      responses:
        '200':
          description: Call queued/initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  parameters:
    AccountSid:
      name: sid
      in: path
      required: true
      description: Your Exotel account Sid (Account SID).
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid API Key/Token.
    TooManyRequests:
      description: Rate limit exceeded (Voice APIs are limited to ~200 calls/minute).
  schemas:
    ConnectCallRequest:
      type: object
      required:
      - From
      - CallerId
      properties:
        From:
          type: string
          description: The number Exotel calls first (E.164 preferred).
        To:
          type: string
          description: The number to connect to. Use this OR Url.
        Url:
          type: string
          description: An Exotel call-flow URL to connect the call to instead of a second number, e.g. http://my.exotel.com/{sid}/exoml/start_voice/{flow_id}.
        CallerId:
          type: string
          description: Your ExoPhone / virtual number shown as caller ID.
        CallType:
          type: string
          enum:
          - trans
          - promo
          description: Call type classification.
        TimeLimit:
          type: integer
          description: Max call duration in seconds (up to 14400).
        TimeOut:
          type: integer
          description: Ring timeout in seconds.
        WaitUrl:
          type: string
          description: Audio URL to play while the callee is being connected.
        Record:
          type: boolean
          description: Whether to record the call.
        StatusCallback:
          type: string
          description: Webhook URL called on call state changes.
        StatusCallbackEvents:
          type: array
          items:
            type: string
            enum:
            - terminal
            - answered
        CustomField:
          type: string
    CallResponse:
      type: object
      properties:
        Sid:
          type: string
        AccountSid:
          type: string
        Status:
          type: string
          enum:
          - queued
          - in-progress
          - completed
          - failed
          - busy
          - no-answer
        From:
          type: string
        To:
          type: string
        PhoneNumberSid:
          type: string
          description: The ExoPhone / virtual number used.
        Direction:
          type: string
        Duration:
          type: integer
        Price:
          type: string
        RecordingUrl:
          type: string
        DateCreated:
          type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication. Username = API Key, Password = API Token (both from Exotel Dashboard -> Settings -> API Settings). May also be embedded in the URL as https://<key>:<token>@<subdomain>/...