openapi: 3.1.1
info:
  title: Callr REST API v2.0
  summary: The voice API your business runs on - Voice, SMS, and AI on Callr's own carrier network
  description: |-
    The Callr REST API gives you programmatic control over the only API-first voice
    platform that owns its carrier network. Build voice and SMS into your product -
    without becoming a telco - across 220+ countries.

    With the Callr REST API, you can:
    - Make, receive, and control phone calls and SMS with standard HTTP requests
    - Search, buy, and manage phone numbers worldwide
    - Automate call flows with Callr Actions - a declarative, YAML-based framework
      inspired by GitHub Actions: IVRs, routing, AI Voice Agents, and more
    - Record and transcribe calls, and turn every conversation into structured data:
      transcripts, AI summaries, sentiment, and intent - defined in your prompts, not ours
    - Bring your own AI model - GPT, Claude, Mistral, Llama, or your in-house stack
    - Receive real-time webhooks for calls, SMS, numbers, billing, and more
    - Push conversation data into your CRM, BI, or analytics stack

    Everything runs serverless on carrier-grade infrastructure - owned, not resold -
    handling millions of calls a day, with your choice of EU or US jurisdiction for
    data sovereignty.
  version: 2.1.0
  contact:
    name: Callr Support
    email: support@callr.com
  license:
    name: Proprietary
    url: https://www.callr.com/terms/
servers:
  - url: https://api.callr.com/v2.0
    description: Production
security:
  - ApiKeyAuth: []
  - BasicAuth: []
tags:
  - name: System
    description: Health check endpoint
  - name: Actions
    description: Create, Manage and Run Callr Actions scenarios
  - name: Audio Files
    description: Manage your audio files
  - name: Billing
    description: Manage billing
  - name: Calls
    description: Manage calls
  - name: End Users
    description: Manage end users
  - name: Phone Numbers
    description: Manage your phone numbers
  - name: Phone Numbers Store
    description: Order phone numbers
  - name: Recordings
    description: Manage call recordings
  - name: SMS
    description: Send and receive SMS messages
  - name: Tasks
    description: Check the status of tasks
  - name: Webhooks
    description: Manage webhooks
externalDocs:
  description: Callr Docs
  url: https://docs.callr.com/
paths:
  /ping:
    get:
      tags:
        - System
      summary: Ping the API
      description: |
        You can use this endpoint to check if the API is up and running.
      operationId: Ping
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PingResponse'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /actions:
    get:
      tags:
        - Actions
      summary: Search scenarios
      description: |
        Search for Callr Actions scenarios.
      operationId: ActionsSearch
      parameters:
        - in: query
          name: name
          description: Scenario name. You can use a partial name.
          schema:
            type: string
            maxLength: 64
        - in: query
          name: sort
          description: Sort by one field
          schema:
            type: string
            default: updated
            enum:
              - name
              - created
              - updated
        - $ref: '#/components/parameters/SearchOrder'
        - $ref: '#/components/parameters/SearchOffset'
        - $ref: '#/components/parameters/SearchLimit'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionsSearchResult'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    post:
      tags:
        - Actions
      summary: Create scenario
      description: |
        Create a new Callr Actions scenario.
      operationId: ActionsCreate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionCreate'
      responses:
        '201':
          description: Actions scenario created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Action'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /actions/{sid}:
    get:
      tags:
        - Actions
      summary: Get scenario
      description: |
        Get a Callr Actions scenario.
      operationId: ActionsGet
      parameters:
        - $ref: '#/components/parameters/SIDPath'
      responses:
        '200':
          description: Actions scenario
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Action'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    patch:
      tags:
        - Actions
      summary: Update scenario
      description: |
        Update a Callr Actions scenario. You may send a partial object.
      operationId: ActionsUpdate
      parameters:
        - $ref: '#/components/parameters/SIDPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionBase'
      responses:
        '200':
          description: The updated actions scenario
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Action'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    delete:
      tags:
        - Actions
      summary: Delete scenario
      description: |
        Delete a Callr Actions scenario.
      operationId: ActionsDelete
      parameters:
        - $ref: '#/components/parameters/SIDPath'
      responses:
        '204':
          description: Scenario deleted
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /actions/{sid}/runs:
    post:
      tags:
        - Actions
      summary: Start scenario
      description: |
        Run a Callr Actions scenario offline. This will execute the `api-initiated` branch of the scenario.
      operationId: ActionsStartOfflineRun
      parameters:
        - $ref: '#/components/parameters/SIDPath'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionsStartInput'
      responses:
        '202':
          description: Starting `api-initiated` branch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionsStartOutput'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /actions/{sid}/runs/{runid}:
    get:
      tags:
        - Actions
      summary: Get an offline run
      description: |
        Get the status of an offline run. This will return the variables and their values.
      operationId: ActionsGetOfflineRun
      parameters:
        - $ref: '#/components/parameters/SIDPath'
        - in: path
          name: runid
          required: true
          schema:
            $ref: '#/components/schemas/ActionRunID'
          description: Run ID
      responses:
        '200':
          description: Run status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionRunStatus'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    delete:
      tags:
        - Actions
      summary: Cancel an offline run
      description: |
        Cancel an offline run. This will stop the execution of the scenario.
      operationId: ActionsCancelOfflineRun
      parameters:
        - $ref: '#/components/parameters/SIDPath'
        - in: path
          name: runid
          required: true
          schema:
            $ref: '#/components/schemas/ActionRunID'
          description: Run ID
      responses:
        '204':
          description: Run canceled
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /actions/{sid}/numbers/{number}:
    put:
      tags:
        - Actions
      summary: Attach number to scenario
      description: |
        Attach a phone number to a Callr Actions scenario. Calls to this number will execute the `inbound-call` branch of the scenario. SMS received on this number will execute the `inbound-sms` branch of the scenario.
      operationId: ActionsAttachNumber
      parameters:
        - $ref: '#/components/parameters/SIDPath'
        - in: path
          name: number
          description: Phone number to attach
          required: true
          schema:
            $ref: '#/components/schemas/PhoneNumber'
      responses:
        '204':
          description: Phone number attached
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    delete:
      tags:
        - Actions
      summary: Detach number from scenario
      description: |
        Detach a phone number from a Callr Actions scenario.
      operationId: ActionsDetachNumber
      parameters:
        - $ref: '#/components/parameters/SIDPath'
        - in: path
          name: number
          description: Phone number to detach
          required: true
          schema:
            $ref: '#/components/schemas/PhoneNumber'
      responses:
        '204':
          description: Phone number detached
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /audio-files:
    get:
      tags:
        - Audio Files
      summary: Search audio files
      operationId: AudioFilesSearch
      description: |
        Search for audio files.
      parameters:
        - in: query
          name: name
          description: Audio file name. You can use a partial name.
          schema:
            type: string
            minLength: 1
            maxLength: 64
        - in: query
          name: status
          description: Audio file status
          schema:
            $ref: '#/components/schemas/AudioFileStatus'
        - in: query
          name: source
          description: Audio file source
          schema:
            $ref: '#/components/schemas/AudioFileSource'
        - in: query
          name: sort
          description: Sort by one field
          schema:
            type: string
            default: updated
            enum:
              - name
              - created
              - updated
        - $ref: '#/components/parameters/SearchOrder'
        - $ref: '#/components/parameters/SearchOffset'
        - $ref: '#/components/parameters/SearchLimit'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudioFilesSearchResult'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    post:
      tags:
        - Audio Files
      summary: Upload audio file
      description: |
        Upload a new audio file. To upload an audio file, the body should be a
        `multipart/form-data`. If you're sending an `application/json` body, you can only
        specify the name of the new audio file. The content will be empty (the `status`
        property will be set to `pending-content`). In this scenario, you should use the
        `POST /audio-files/{sid}/file` method to upload the file content.

        When sending a `multipart/form-data` body, the content will be processed
        asynchronously. The `status` property of the resulting audio file will transition
        through the following stages:

        - `pending-conversion`
        - `processing`
        - Finally, it will be either `ready` or `error`

        The supported formats are `audio/flac`, `audio/mpeg`, `audio/mp4`, `audio/ogg`,
        `audio/wav`.

        You can use webhooks to receive updates on the status.
      operationId: AudioFilesUpload
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - name
              additionalProperties: false
              properties:
                file:
                  type: string
                  format: binary
                  description: The audio file to upload
                name:
                  $ref: '#/components/schemas/AudioFileName'
          application/json:
            schema:
              type: object
              required:
                - name
              additionalProperties: false
              properties:
                name:
                  $ref: '#/components/schemas/AudioFileName'
      responses:
        '201':
          description: Audio file created, empty content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudioFile'
        '202':
          description: Audio file created, content processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudioFile'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /audio-files/{sid}:
    get:
      tags:
        - Audio Files
      summary: Get audio file
      description: |
        Get audio file by SID.
      operationId: AudioFilesGet
      parameters:
        - $ref: '#/components/parameters/SIDPath'
      responses:
        '200':
          description: Audio file
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudioFile'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    delete:
      tags:
        - Audio Files
      summary: Delete audio file
      description: |
        Delete an audio file.
      operationId: AudioFilesDelete
      parameters:
        - $ref: '#/components/parameters/SIDPath'
      responses:
        '204':
          description: Audio file deleted
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    patch:
      tags:
        - Audio Files
      summary: Update audio file properties
      description: |
        Update the properties of an audio file. You can only update the name.
      operationId: AudioFilesUpdate
      parameters:
        - $ref: '#/components/parameters/SIDPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AudioFileUpdate'
      responses:
        '200':
          description: Audio file updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudioFile'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /audio-files/{sid}/file:
    put:
      tags:
        - Audio Files
      summary: Update audio file with upload
      description: |
        Update the content of an existing audio file. The content will be processed
        asynchronously. The `status` property of the updated audio file will transition
        through the following stages:

        - `pending-conversion`
        - `processing`
        - Finally, it will be either `ready` or `error`

        The supported formats are `audio/flac`, `audio/mpeg`, `audio/mp4`, `audio/ogg`,
        `audio/wav`.

        You can use webhooks to receive updates on the status.
      operationId: AudioFilesUploadFile
      parameters:
        - $ref: '#/components/parameters/SIDPath'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              additionalProperties: false
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '202':
          description: Audio file updating
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudioFile'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /audio-files/{sid}/phone-id:
    put:
      tags:
        - Audio Files
      summary: Update audio file on the phone
      description: |
        Update the content of an existing audio file by recording yourself over the phone.
        For a given audio file `sid`, this method will return a phone number and a code to
        enter as DTMF to record yourself.

        Once you have confirmed the changes over the phone, the content will be processed
        asynchronously. The `status` property of  the updated audio file will transition
        through the following stages:

        - `pending-conversion`
        - `processing`
        - Finally, it will be either `ready` or `error`

        You can use webhooks to receive updates on the status.
      operationId: AudioFilesPhoneID
      parameters:
        - $ref: '#/components/parameters/SIDPath'
        - in: query
          name: country
          required: true
          schema:
            $ref: '#/components/schemas/CountryCode'
          description: |
            The country code of the desired country for the recording phone number. If not available, we will provide the closest possible.
      responses:
        '201':
          description: Phone ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudioFilePhoneID'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /billing/credit:
    get:
      tags:
        - Billing
      summary: Get credit balance
      description: |
        Get your credit balance (for prepaid accounts only). **The value is in cents**.
      operationId: BillingGetCredit
      responses:
        '200':
          description: Prepaid credit balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingCredit'
              examples:
                Five:
                  summary: Five euros
                  value:
                    amount: '500.00'
                    currency: EUR
                FiftyCents:
                  summary: Fifty cents
                  value:
                    amount: '50.00'
                    currency: USD
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /billing/destinations:
    get:
      tags:
        - Billing
      summary: Get billing destinations
      description: |
        Get the list of billing destinations.
      operationId: BillingGetDestinations
      responses:
        '200':
          description: Billing destinations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BillingDestination'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /calls/{callid}:
    delete:
      tags:
        - Calls
      summary: Hangup a live call
      description: |
        Hang up a live call.
      operationId: CallsHangup
      parameters:
        - in: path
          name: callid
          required: true
          schema:
            $ref: '#/components/schemas/CallID'
      responses:
        '204':
          description: Call hung up
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /calls/export:
    post:
      tags:
        - Calls
      summary: Export calls
      description: |-
        Export calls to a CSV file. The CSV file will be available for download for 24 hours.
        The export will be performed asynchronously. The task status can be checked with
        the `Tasks` endpoints.

        You cannot export more than 31 days of calls at once. If you need to export more
        than 31 days,you will need to split the export in multiple requests.

        Exporting calls is a heavy operation. It can take a long time to complete, depending
        on the amount of calls to export. **That is why you are limited to a maximum of 5
        exports per day.**

        If you need to process calls in real-time, you should use webhooks, or the `fetch`
        action with Callr Actions.
      operationId: CallsExport
      parameters:
        - in: query
          name: direction
          required: true
          schema:
            $ref: '#/components/schemas/Direction'
        - in: query
          name: from
          required: true
          schema:
            $ref: '#/components/schemas/Datetime'
        - in: query
          name: to
          required: true
          schema:
            $ref: '#/components/schemas/Datetime'
        - in: query
          name: scenario
          description: |
            The SID of the scenario that was used to process the calls. If you want to export all calls, regardless of the scenario, you can omit this parameter.
          schema:
            $ref: '#/components/schemas/SID'
        - in: query
          name: number
          description: |
            A Callr phone number you own that received the calls. With direction `inbound`, this will export the inbound calls received on this number. With direction `outbound`, this will export the outbound calls forwarded by this number.
          schema:
            $ref: '#/components/schemas/PhoneNumber'
      responses:
        '202':
          description: Export is running (Task ID in response)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskID'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /end-users:
    get:
      tags:
        - End Users
      summary: Search end users
      description: |
        Search for end users.
      operationId: EndUserSearch
      parameters:
        - in: query
          name: name
          description: End user name. You can use a partial name.
          schema:
            type: string
            maxLength: 32
        - in: query
          name: sort
          description: Sort by one field
          schema:
            type: string
            default: updated
            enum:
              - name
              - created
              - updated
        - $ref: '#/components/parameters/SearchOrder'
        - $ref: '#/components/parameters/SearchOffset'
        - $ref: '#/components/parameters/SearchLimit'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndUserSearchResult'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    post:
      tags:
        - End Users
      summary: Create end user
      description: |
        Create an end user.
      operationId: EndUserCreate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndUserCreate'
      responses:
        '201':
          description: End user created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndUser'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /end-users/{sid}:
    get:
      tags:
        - End Users
      summary: Get end user
      description: |
        Get an end user.
      operationId: EndUserGet
      parameters:
        - $ref: '#/components/parameters/SIDPath'
      responses:
        '200':
          description: End user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndUser'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    patch:
      tags:
        - End Users
      summary: Update end user
      description: |
        Update an end user. You may send a partial object.
      operationId: EndUserUpdate
      parameters:
        - $ref: '#/components/parameters/SIDPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndUserUpdate'
      responses:
        '200':
          description: The updated end user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndUser'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    delete:
      tags:
        - End Users
      summary: Delete end user
      description: |
        Delete an end user. **You cannot delete an end user that is associated with a Caller ID, or a Phone Number.**
      operationId: EndUserDelete
      parameters:
        - $ref: '#/components/parameters/SIDPath'
      responses:
        '204':
          description: End user deleted
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /numbers:
    get:
      tags:
        - Phone Numbers
      summary: Search phone numbers
      description: |
        Search for your phone numbers.
      operationId: NumberSearch
      parameters:
        - in: query
          name: sid
          description: Phone number SID
          schema:
            $ref: '#/components/schemas/SID'
        - in: query
          name: class
          description: Number class
          schema:
            $ref: '#/components/schemas/NumberClass'
        - in: query
          name: type
          description: Number type
          schema:
            $ref: '#/components/schemas/NumberType'
        - in: query
          name: contains
          description: Search by number. You can use a partial number.
          schema:
            type: string
            pattern: ^(\+[1-9])?[0-9]{1,32}$
          examples:
            French starts with +33184:
              summary: French number with +33184 prefix
              value: '+33184'
            Contains '42':
              summary: Numbers containing "42"
              value: '42'
            Contains '0000':
              summary: Numbers containing "0000"
              value: '0000'
        - in: query
          name: detached
          description: |
            Search for detached numbers only. You can only pass `true` to this parameter. Detached numbers are phone numbers that are currently not attached to any scenario.
          schema:
            type: boolean
            const: true
        - in: query
          name: sort
          description: Sort by one field
          schema:
            type: string
            default: assigned
            enum:
              - assigned
              - e164
        - $ref: '#/components/parameters/SearchOrder'
        - $ref: '#/components/parameters/SearchOffset'
        - $ref: '#/components/parameters/SearchLimit'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberSearchResult'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /numbers/{number}:
    get:
      tags:
        - Phone Numbers
      summary: Get phone number
      description: |
        Get a phone number.
      operationId: NumberGet
      parameters:
        - in: path
          name: number
          required: true
          schema:
            $ref: '#/components/schemas/PhoneNumber'
      responses:
        '200':
          description: Phone number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Number'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    delete:
      tags:
        - Phone Numbers
      summary: Remove phone number from your account
      description: |
        Terminate the number subscription and immediately free up the number. If the number is currently attached to an actions scenario, it will be detached. Should there be a contract associated with the number, your account will be billed for the remaining contractual days.
      operationId: NumberRemove
      parameters:
        - in: path
          name: number
          required: true
          schema:
            $ref: '#/components/schemas/PhoneNumber'
      responses:
        '204':
          description: Phone number removed
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    patch:
      tags:
        - Phone Numbers
      summary: Update a phone number
      description: |
        Update a phone number. Attach the number to a Callr Actions scenario, or change the end user.
      operationId: NumberUpdate
      parameters:
        - in: path
          name: number
          required: true
          schema:
            $ref: '#/components/schemas/PhoneNumber'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NumberUpdate'
      responses:
        '204':
          description: Phone number updated
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /numbers/{number}/scenario:
    delete:
      tags:
        - Phone Numbers
      summary: Detach phone number from scenario
      description: |
        Detach a phone number from its scenario.

        While the number remains allocated to your account, it is not engaged in any
        scenario. Any calls made to this number will be declined with an "unallocated number"
        message.
      operationId: NumberDetach
      parameters:
        - in: path
          name: number
          required: true
          schema:
            $ref: '#/components/schemas/PhoneNumber'
      responses:
        '204':
          description: Phone number detached
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /numbers/{number}/scenario/{sid}:
    put:
      tags:
        - Phone Numbers
      summary: Attach phone number to scenario
      description: |
        Attach a phone number to a Callr Actions scenario.
      operationId: NumberAttach
      parameters:
        - in: path
          name: number
          required: true
          description: The phone number to attach
          schema:
            $ref: '#/components/schemas/PhoneNumber'
        - $ref: '#/components/parameters/SIDPath'
      responses:
        '204':
          description: Phone number attached
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /numbers/{number}/enduser/{sid}:
    put:
      tags:
        - Phone Numbers
      summary: Assign phone number to end user
      description: |
        Assign a phone number to an end user.
      operationId: NumberAssignEndUser
      parameters:
        - in: path
          name: number
          required: true
          description: The phone number to assign
          schema:
            $ref: '#/components/schemas/PhoneNumber'
        - $ref: '#/components/parameters/SIDPath'
      responses:
        '204':
          description: Phone number assigned to end user
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /numbers/store:
    post:
      tags:
        - Phone Numbers Store
      summary: Reserve numbers
      description: |
        Reserve numbers before ordering. This method gives you a token to use with the `POST /numbers/store/{token}` method. Your booking is held for a maximum of 5 minutes. You can have only one reservation at a time.
      operationId: NumberStoreReserve
      parameters:
        - in: query
          name: country
          schema:
            $ref: '#/components/schemas/CountryCode'
          required: true
          description: Country code
          examples:
            France:
              value: FR
              summary: France
            United States:
              value: US
              summary: United States
        - in: query
          name: type
          schema:
            $ref: '#/components/schemas/NumberType'
          required: true
          description: Type of number
          examples:
            Geographic:
              value: geographic
              summary: Geographic
            Mobile:
              value: mobile
              summary: Mobile
        - in: query
          name: quantity
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 1
          description: Quantity to reserve
        - in: query
          name: class
          schema:
            $ref: '#/components/schemas/NumberClass'
            default: classic
          description: Class of number
        - in: query
          name: prefix
          schema:
            type: string
            pattern: ^\+[1-9][0-9]{0,8}$
          description: The prefix of the number
          examples:
            France +331:
              value: '+331'
              summary: France (01)
            United States +1415:
              value: '+1415'
              summary: United States (415)
        - in: query
          name: area
          schema:
            type: string
            pattern: ^[\p{L}0-9 '-]{0,32}$
            maxLength: 32
          description: The area/city of the number
          examples:
            Paris:
              value: Paris
              summary: Paris
            New York:
              value: NYC
              summary: New York City
            Nice:
              value: Nice
              summary: Nice
      responses:
        '200':
          description: Reservation status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberStoreReservation'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /numbers/store/{token}:
    post:
      tags:
        - Phone Numbers Store
      summary: Buy phone numbers
      description: |
        Buy phone numbers previously reserved, with the token returned by the `/numbers/store` endpoint.
      operationId: NumberStoreBuyOrder
      parameters:
        - in: path
          name: token
          required: true
          schema:
            description: Reservation token
            type: string
            minLength: 40
      responses:
        '200':
          description: Phone numbers bought
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberStoreBuyResult'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    get:
      tags:
        - Phone Numbers Store
      summary: Get reservation status
      description: |
        Get the status of a phone number reservation.
      operationId: NumberStoreViewOrder
      parameters:
        - in: path
          name: token
          required: true
          schema:
            description: Reservation token
            type: string
            minLength: 40
      responses:
        '200':
          description: Reservation status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberStoreReservation'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    delete:
      tags:
        - Phone Numbers Store
      summary: Cancel reservation
      description: |
        Cancel a phone number reservation.
      operationId: NumberStoreCancelOrder
      parameters:
        - in: path
          name: token
          required: true
          schema:
            description: Reservation token
            type: string
            minLength: 40
      responses:
        '204':
          description: Reservation canceled
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /numbers/store/countries:
    get:
      tags:
        - Phone Numbers Store
      summary: List available countries
      description: |
        Get the list of countries available in the number store.
      operationId: NumberStoreCountries
      responses:
        '200':
          description: Countries available in the number store
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CountryStore'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /numbers/store/types:
    get:
      tags:
        - Phone Numbers Store
      summary: List available number types
      description: |
        Get the list of number types available in the number store.
      operationId: NumberStoreTypes
      parameters:
        - in: query
          name: country
          required: true
          schema:
            $ref: '#/components/schemas/CountryCode'
          examples:
            France:
              value: FR
              summary: France
            United States:
              value: US
              summary: United States
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NumberStoreType'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /numbers/store/prefixes:
    get:
      tags:
        - Phone Numbers Store
      summary: List available prefixes
      description: |
        Get the list of prefixes available in the number store.
      operationId: NumberStorePrefixes
      parameters:
        - in: query
          name: country
          required: true
          schema:
            $ref: '#/components/schemas/CountryCode'
          examples:
            France:
              value: FR
              summary: France
            United States:
              value: US
              summary: United States
        - in: query
          name: type
          required: true
          schema:
            $ref: '#/components/schemas/NumberType'
          examples:
            Geographic:
              value: geographic
      responses:
        '200':
          description: Prefixes available
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NumberAreaCode'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /recordings:
    get:
      tags:
        - Recordings
      summary: Search recordings
      description: |
        Search for your recordings.
      operationId: RecordingsSearch
      parameters:
        - in: query
          name: sid
          description: Recording SID
          schema:
            $ref: '#/components/schemas/SID'
        - in: query
          name: type
          description: Recording type
          schema:
            $ref: '#/components/schemas/RecordingType'
        - in: query
          name: caller
          description: Caller number
          schema:
            $ref: '#/components/schemas/PhoneNumber'
        - in: query
          name: callee
          description: Callee number
          schema:
            $ref: '#/components/schemas/PhoneNumber'
        - in: query
          name: callid
          description: Call ID
          schema:
            $ref: '#/components/schemas/CallID'
        - in: query
          name: read
          description: Read status
          schema:
            type: boolean
            examples:
              - true
        - in: query
          name: readAfter
          schema:
            $ref: '#/components/schemas/Datetime'
        - in: query
          name: readBefore
          schema:
            $ref: '#/components/schemas/Datetime'
        - in: query
          name: createdAfter
          schema:
            $ref: '#/components/schemas/Datetime'
        - in: query
          name: createdBefore
          schema:
            $ref: '#/components/schemas/Datetime'
        - in: query
          name: minDuration
          schema:
            type: integer
            description: Minimum call duration
            minimum: 0
            examples:
              - 5
        - in: query
          name: sort
          description: Sort by one field
          schema:
            type: string
            default: created
            const: created
        - $ref: '#/components/parameters/SearchOrder'
        - $ref: '#/components/parameters/SearchOffset'
        - $ref: '#/components/parameters/SearchLimit'
      responses:
        '200':
          description: Recordings search result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordingsSearchResult'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    patch:
      tags:
        - Recordings
      summary: Update recordings
      description: |
        Update recordings in bulk. You may update the `read` status of your recordings by specifying the `sid` of the recording(s) you want to update. To update all of your recordings, do not specify any `sid`.
      operationId: RecordingsUpdateBulk
      parameters:
        - in: query
          name: sid
          schema:
            type: array
            maxItems: 100
            items:
              $ref: '#/components/schemas/SID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordingUpdate'
      responses:
        '202':
          description: Updating recordings (Task ID in response)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskID'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    delete:
      tags:
        - Recordings
      summary: Delete recordings
      description: |
        Delete recordings in bulk. You may delete your recordings by specifying the `sid` of the recording(s) you want to delete. To delete all of your recordings, do not specify any `sid`.
      operationId: RecordingsDeleteBulk
      parameters:
        - in: query
          name: sid
          schema:
            type: array
            maxItems: 100
            items:
              $ref: '#/components/schemas/SID'
      responses:
        '202':
          description: Deleting recordings (Task ID in response)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskID'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /recordings/{sid}:
    get:
      tags:
        - Recordings
      summary: Get recording
      description: |
        Retrieve a recording.
      operationId: RecordingsGet
      parameters:
        - $ref: '#/components/parameters/SIDPath'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recording'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    patch:
      tags:
        - Recordings
      summary: Update recording
      description: |
        Update a recording. You may send a partial object.
      operationId: RecordingsUpdateOne
      parameters:
        - $ref: '#/components/parameters/SIDPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordingUpdate'
      responses:
        '200':
          description: Recording updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recording'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    delete:
      tags:
        - Recordings
      summary: Delete recording
      description: |
        Delete a recording.
      operationId: RecordingsDeleteOne
      parameters:
        - $ref: '#/components/parameters/SIDPath'
      responses:
        '204':
          description: Recording deleted
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /sms:
    get:
      tags:
        - SMS
      summary: Search SMS
      description: |
        Search for your SMS messages.
      operationId: SMSSearch
      parameters:
        - in: query
          name: direction
          required: true
          schema:
            $ref: '#/components/schemas/Direction'
        - in: query
          name: from
          description: SMS sender
          schema:
            $ref: '#/components/schemas/SMSSender'
        - in: query
          name: to
          description: SMS to
          schema:
            $ref: '#/components/schemas/PhoneNumber'
        - in: query
          name: contains
          description: SMS text body contains
          schema:
            type: string
            maxLength: 64
        - in: query
          name: trafficType
          description: SMS traffic type
          schema:
            $ref: '#/components/schemas/SMSTrafficType'
        - in: query
          name: status
          schema:
            $ref: '#/components/schemas/SMSStatus'
        - in: query
          name: createdAfter
          required: true
          schema:
            $ref: '#/components/schemas/Datetime'
        - in: query
          name: createdBefore
          required: true
          schema:
            $ref: '#/components/schemas/Datetime'
        - in: query
          name: sort
          description: Sort by one field
          schema:
            type: string
            default: created
            enum:
              - created
              - updated
        - $ref: '#/components/parameters/SearchOrder'
        - $ref: '#/components/parameters/SearchOffset'
        - $ref: '#/components/parameters/SearchLimit'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SMSSearchResult'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    post:
      tags:
        - SMS
      summary: Send SMS
      description: |
        Send an SMS. If accepted, the SMS will cycle through the following statuses:

        - `created`
        - `pending`
        - `sent`
        - `remote-queued`
        - `delivered`

        At any time, the SMS can be in the following statuses:
        - `error`: was not accepted
        - `failed`: rejected by the carrier
        - `expired`: was not delivered to the recipient
      operationId: SMSSend
      parameters:
        - in: query
          name: to
          description: SMS recipient
          required: true
          schema:
            $ref: '#/components/schemas/PhoneNumber'
        - in: query
          name: from
          description: |
            The SMS sender. If empty, a value will be automatically set depending on the destination. Otherwise, the sender must be either a phone number, or an alphanumeric sender (with at least one character - 11 chars maximum). Custom SMS senders must be approved by our team and downstream carriers. You can request a custom sender on https://app.callr.com.
          schema:
            $ref: '#/components/schemas/SMSSender'
          examples:
            Alphanumeric:
              summary: Alphanumeric sender
              value: MyCompany
            Phone Number:
              summary: Phone number sender
              value: '+15551230000'
        - in: query
          name: encoding
          description: |
            By default, we automatically detect the encoding based on the characters used in the body. If you want to force the encoding, you can use this field. The SMS body will be processed according to the encoding specified. Depending on the encoding, messages may be split into parts of 153 (GSM 03.38) or 67 (UNICODE) characters. Please note that some countries only support GSM encoding.
          schema:
            $ref: '#/components/schemas/SMSEncoding'
        - in: query
          name: trafficType
          description: |
            Traffic type of an SMS message. Carriers require this to be set to either `marketing` or `alerting`.
          schema:
            $ref: '#/components/schemas/SMSTrafficType'
            default: marketing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SMSBody'
      responses:
        '202':
          description: SMS accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SMS'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /sms/{sid}:
    get:
      tags:
        - SMS
      summary: Get SMS
      description: |
        Get an SMS.
      operationId: SMSGet
      parameters:
        - $ref: '#/components/parameters/SIDPath'
      responses:
        '200':
          description: SMS
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SMS'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /tasks/{taskid}:
    get:
      tags:
        - Tasks
      summary: Get task
      description: |
        Return the status of a task.
      operationId: TaskGet
      parameters:
        - in: path
          name: taskid
          required: true
          schema:
            $ref: '#/components/schemas/TaskID'
      responses:
        '200':
          description: Task
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    delete:
      tags:
        - Tasks
      summary: Cancel task
      description: |
        Cancel a task. The task must be in a `PENDING` or `RUNNING` state. If the task is `RUNNING`, the result is undefined.
      operationId: TaskCancel
      parameters:
        - in: path
          name: taskid
          required: true
          schema:
            $ref: '#/components/schemas/TaskID'
      responses:
        '204':
          description: Task canceled
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /webhooks:
    get:
      tags:
        - Webhooks
      summary: Search webhooks
      description: |
        Search for your webhooks.
      operationId: WebhookSearch
      parameters:
        - in: query
          name: sid
          schema:
            $ref: '#/components/schemas/SID'
        - in: query
          name: type
          schema:
            $ref: '#/components/schemas/WebhookType'
        - in: query
          name: status
          schema:
            $ref: '#/components/schemas/WebhookStatus'
        - in: query
          name: sort
          description: Sort by one field
          schema:
            type: string
            default: created
            const: created
        - $ref: '#/components/parameters/SearchOrder'
        - $ref: '#/components/parameters/SearchOffset'
        - $ref: '#/components/parameters/SearchLimit'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSearchResult'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    post:
      tags:
        - Webhooks
      summary: Create webhook
      description: |
        Create a new webhook.
      operationId: WebhookCreate
      parameters:
        - in: query
          name: type
          required: true
          schema:
            $ref: '#/components/schemas/WebhookType'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreate'
      responses:
        '201':
          description: Webhook created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /webhooks/{sid}:
    get:
      tags:
        - Webhooks
      summary: Get webhook
      description: |
        Get a webhook.
      operationId: WebhookGet
      parameters:
        - $ref: '#/components/parameters/SIDPath'
      responses:
        '200':
          description: Webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    patch:
      tags:
        - Webhooks
      summary: Update webhook
      description: |
        Update a webhook. You cannot change the endoint URL. To change the URL, create a new webhook.
      operationId: WebhookUpdate
      parameters:
        - $ref: '#/components/parameters/SIDPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookUpdate'
      responses:
        '200':
          description: Webhook updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    delete:
      tags:
        - Webhooks
      summary: Delete webhook
      description: |
        Delete a webhook.
      operationId: WebhookDelete
      parameters:
        - $ref: '#/components/parameters/SIDPath'
      responses:
        '204':
          description: Webhook deleted
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /webhooks/logs:
    get:
      tags:
        - Webhooks
      summary: Search webhook logs
      description: |
        Search for your webhook logs.
      operationId: WebhookLogsSearch
      parameters:
        - in: query
          name: endpoint
          schema:
            $ref: '#/components/schemas/URI'
        - in: query
          name: at
          schema:
            $ref: '#/components/schemas/Datetime'
        - in: query
          name: id
          description: Event ID
          schema:
            type: string
            maxLength: 50
            minLength: 0
        - in: query
          name: sid
          description: Webhook SID
          schema:
            $ref: '#/components/schemas/SID'
        - in: query
          name: httpcode
          schema:
            type: integer
            minimum: 100
        - in: query
          name: try
          schema:
            type: integer
            minimum: 0
        - in: query
          name: type
          schema:
            $ref: '#/components/schemas/WebhookType'
        - in: query
          name: sort
          description: Sort by one field
          schema:
            type: string
            default: at
            const: at
        - $ref: '#/components/parameters/SearchOrder'
        - $ref: '#/components/parameters/SearchOffset'
        - $ref: '#/components/parameters/SearchLimit'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookLogsSearchResult'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
webhooks:
  v2.billing.credit.topup:
    post:
      operationId: billingCreditTopupWebhook
      summary: Prepaid account credited
      description: Your prepaid account has been credited
      requestBody:
        required: true
        content:
          application/json:
            schema:
              unevaluatedProperties: false
              allOf:
                - $ref: '#/components/schemas/WebhookPayloadBase'
                - type: object
                  required:
                    - type
                  properties:
                    type:
                      type: string
                      const: v2.billing.credit.topup
                - $ref: '#/components/schemas/WebhookPayloadCredit'
      responses:
        2XX:
          description: OK
  v2.billing.credit.warning:
    post:
      operationId: billingCreditWarningWebhook
      summary: Prepaid credit warning reached
      description: |
        Your prepaid account has reached the warning threshold. Please top up your account to avoid service interruption.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              unevaluatedProperties: false
              allOf:
                - $ref: '#/components/schemas/WebhookPayloadBase'
                - type: object
                  required:
                    - type
                  properties:
                    type:
                      type: string
                      const: v2.billing.credit.warning
                - $ref: '#/components/schemas/WebhookPayloadCredit'
      responses:
        2XX:
          description: OK
  v2.billing.credit.shutdown:
    post:
      operationId: billingCreditShutdownWebhook
      summary: Prepaid credit shutdown reached
      description: |
        Your prepaid account has reached the shutdown threshold. Your account is currently disabled. Please top up your account to re-enable it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              unevaluatedProperties: false
              allOf:
                - $ref: '#/components/schemas/WebhookPayloadBase'
                - type: object
                  required:
                    - type
                  properties:
                    type:
                      type: string
                      const: v2.billing.credit.shutdown
                - $ref: '#/components/schemas/WebhookPayloadCredit'
      responses:
        2XX:
          description: OK
  v2.call.inbound.started:
    post:
      operationId: callInboundStartedWebhook
      summary: Inbound call started
      description: |
        An inbound call has started. An inbound call is a call to a Callr hosted phone number.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              unevaluatedProperties: false
              allOf:
                - $ref: '#/components/schemas/WebhookPayloadBase'
                - type: object
                  required:
                    - type
                  properties:
                    type:
                      type: string
                      const: v2.call.inbound.started
                - type: object
                  required:
                    - payload
                  properties:
                    payload:
                      $ref: '#/components/schemas/CDR'
      responses:
        2XX:
          description: OK
  v2.call.inbound.ended:
    post:
      operationId: callInboundEndedWebhook
      summary: Inbound call ended
      description: |
        An inbound call has hung up
      requestBody:
        required: true
        content:
          application/json:
            schema:
              unevaluatedProperties: false
              allOf:
                - $ref: '#/components/schemas/WebhookPayloadBase'
                - type: object
                  required:
                    - type
                  properties:
                    type:
                      type: string
                      const: v2.call.inbound.ended
                - type: object
                  required:
                    - payload
                  properties:
                    payload:
                      $ref: '#/components/schemas/CDR'
      responses:
        2XX:
          description: OK
  v2.call.outbound.started:
    post:
      operationId: callOutboundStartedWebhook
      summary: Outbound call started
      description: |
        An outbound call has started. An outbound call is a call initiated from the Callr platform to an external phone number.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              unevaluatedProperties: false
              allOf:
                - $ref: '#/components/schemas/WebhookPayloadBase'
                - type: object
                  required:
                    - type
                  properties:
                    type:
                      type: string
                      const: v2.call.outbound.started
                - type: object
                  readOnly: true
                  required:
                    - payload
                  properties:
                    payload:
                      $ref: '#/components/schemas/CDR'
      responses:
        2XX:
          description: OK
  v2.call.outbound.ended:
    post:
      operationId: callOutboundEndedWebhook
      summary: Outbound call ended
      description: |
        An outbound call has hung up
      requestBody:
        required: true
        content:
          application/json:
            schema:
              unevaluatedProperties: false
              allOf:
                - $ref: '#/components/schemas/WebhookPayloadBase'
                - type: object
                  required:
                    - type
                  properties:
                    type:
                      type: string
                      const: v2.call.outbound.ended
                - type: object
                  required:
                    - payload
                  properties:
                    payload:
                      $ref: '#/components/schemas/CDR'
      responses:
        2XX:
          description: OK
  v2.number.assigned:
    post:
      operationId: numberAssignedWebhook
      summary: |
        Phone number assigned
      description: |
        A phone number was assigned to your account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              unevaluatedProperties: false
              allOf:
                - $ref: '#/components/schemas/WebhookPayloadBase'
                - type: object
                  required:
                    - type
                  properties:
                    type:
                      type: string
                      const: v2.number.assigned
                - type: object
                  required:
                    - payload
                  properties:
                    payload:
                      $ref: '#/components/schemas/NumberAssigned'
      responses:
        2XX:
          description: OK
  v2.number.unassigned:
    post:
      operationId: numberUnassignedWebhook
      summary: |
        Phone number unassigned
      description: |
        A phone number was unassigned from your account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              unevaluatedProperties: false
              allOf:
                - $ref: '#/components/schemas/WebhookPayloadBase'
                - type: object
                  required:
                    - type
                  properties:
                    type:
                      type: string
                      const: v2.number.unassigned
                - type: object
                  required:
                    - payload
                  properties:
                    payload:
                      $ref: '#/components/schemas/NumberAssigned'
      responses:
        2XX:
          description: OK
  v2.task.updated:
    post:
      operationId: taskStatusWebhook
      summary: |
        Task status updated
      requestBody:
        required: true
        content:
          application/json:
            schema:
              unevaluatedProperties: false
              allOf:
                - $ref: '#/components/schemas/WebhookPayloadBase'
                - type: object
                  required:
                    - type
                  properties:
                    type:
                      type: string
                      const: v2.task.updated
                - type: object
                  required:
                    - payload
                  properties:
                    payload:
                      $ref: '#/components/schemas/Task'
      responses:
        2XX:
          description: OK
  v2.audio-file.updated:
    post:
      operationId: audioFileStatusWebhook
      summary: |
        Audio File status updated
      requestBody:
        required: true
        content:
          application/json:
            schema:
              unevaluatedProperties: false
              allOf:
                - $ref: '#/components/schemas/WebhookPayloadBase'
                - type: object
                  required:
                    - type
                  properties:
                    type:
                      type: string
                      const: v2.audio-file.updated
                - type: object
                  required:
                    - payload
                  properties:
                    payload:
                      $ref: '#/components/schemas/AudioFile'
      responses:
        2XX:
          description: OK
  v2.recording.updated:
    post:
      operationId: recordingStatusWebhook
      summary: |
        Recording status updated
      requestBody:
        required: true
        content:
          application/json:
            schema:
              unevaluatedProperties: false
              allOf:
                - $ref: '#/components/schemas/WebhookPayloadBase'
                - type: object
                  required:
                    - type
                  properties:
                    type:
                      type: string
                      const: v2.recording.updated
                - type: object
                  required:
                    - payload
                  properties:
                    payload:
                      $ref: '#/components/schemas/Recording'
      responses:
        2XX:
          description: OK
  v2.sms.inbound.received:
    post:
      operationId: smsInboundReceivedWebhook
      summary: |
        Inbound SMS received
      requestBody:
        required: true
        content:
          application/json:
            schema:
              unevaluatedProperties: false
              allOf:
                - $ref: '#/components/schemas/WebhookPayloadBase'
                - type: object
                  required:
                    - type
                  properties:
                    type:
                      type: string
                      const: v2.sms.inbound.received
                - type: object
                  required:
                    - payload
                  properties:
                    payload:
                      $ref: '#/components/schemas/SMS'
      responses:
        2XX:
          description: OK
  v2.sms.outbound.updated:
    post:
      operationId: smsOutboundStatusWebhook
      summary: |
        Outbound SMS status updated
      requestBody:
        required: true
        content:
          application/json:
            schema:
              unevaluatedProperties: false
              allOf:
                - $ref: '#/components/schemas/WebhookPayloadBase'
                - type: object
                  required:
                    - type
                  properties:
                    type:
                      type: string
                      const: v2.sms.outbound.updated
                - type: object
                  required:
                    - payload
                  properties:
                    payload:
                      $ref: '#/components/schemas/SMS'
      responses:
        2XX:
          description: OK
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: |
        Send your Account SID as the username, and your API Key as the password. This methods allows you to authenticate with your main account but also your sub accounts. To authenticate with a sub account, use the sub account's SID as the username, and your API Key as the password.
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: |
        Send your API Key as the value of the x-api-key header. With this method, you can only authenticate with your main account.
  schemas:
    PingResponse:
      type: object
      required:
        - pong
        - time
      additionalProperties: false
      properties:
        pong:
          type: string
          enum:
            - pong
        time:
          type: string
          format: date-time
          description: Server time
          examples:
            - '2024-04-24T12:00:42.000Z'
    ErrorResponse:
      type: object
      required:
        - code
        - message
      additionalProperties: false
      properties:
        code:
          type: string
          description: Error code (short string identifier)
        message:
          type: string
          description: Description of the error in english
    SearchOffset:
      description: Offset index (zero-based)
      type: integer
      minimum: 0
      default: 0
    SearchResult:
      type: object
      required:
        - offset
        - total
        - hasMore
      properties:
        offset:
          $ref: '#/components/schemas/SearchOffset'
        total:
          type: integer
          examples:
            - 20
          minimum: 0
        hasMore:
          type: boolean
          description: Whether there are more results available
          examples:
            - false
    ActionBase:
      type: object
      required: []
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 64
          pattern: \p{L}
          examples:
            - Call Forwarding
            - AI Voicemail
            - AI Agent
        script:
          type: string
          minLength: 1
          maxLength: 32768
          examples:
            - |
              defaults:
                language: en-US

              branches:
                inbound-call:
                  actions:
                    - action: log@v1
                      params:
                        message: Hello inbound call

                inbound-sms:
                  actions:
                    - action: log@v1
                      params:
                        message: Hello inbound sms

                api-initiated:
                  actions:
                    - action: log@v1
                      params:
                        message: Hello from API
        format:
          type: string
          pattern: ^yaml$
          examples:
            - yaml
    SID:
      description: Short ID
      type: string
      examples:
        - callrsid
        - deadbeef
        - azerty00
      pattern: ^[a-z0-9]{8}$
      maxLength: 8
      minLength: 8
    PhoneNumber:
      description: |
        A phone number in ITU-T E.164 format https://en.wikipedia.org/wiki/E.164, prefixed by "+"
      type: string
      examples:
        - '+33199001234'
        - '+33639984242'
        - '+15551230000'
      pattern: ^\+[1-9][0-9]{5,32}$
    NumberClass:
      description: Number class. "gold" is for premium (rare) numbers, "classic" is for regular numbers.
      type: string
      enum:
        - gold
        - classic
      examples:
        - classic
    NumberType:
      description: Type of number
      type: string
      enum:
        - geographic
        - mobile
        - non-geographic
        - personal
        - platform
        - sharedrevenue
        - sms-only
        - special
        - tollfree
        - verified
      examples:
        - geographic
        - non-geographic
    Datetime:
      description: RFC 3339, section 5.6
      type: string
      format: date-time
      examples:
        - '2024-04-24T17:42:28Z'
        - '2024-04-24T17:42:28.000Z'
        - '2024-04-24T17:42:28.12345678+00:00'
    CountryCode:
      description: ISO 3166-1 alpha-2 country code
      type: string
      pattern: ^[A-Z]{2}$
      examples:
        - FR
        - US
    NumberAssigned:
      type: object
      required:
        - e164
        - class
        - type
        - assigned
        - country
      properties:
        e164:
          $ref: '#/components/schemas/PhoneNumber'
        class:
          $ref: '#/components/schemas/NumberClass'
        type:
          $ref: '#/components/schemas/NumberType'
        assigned:
          $ref: '#/components/schemas/Datetime'
        country:
          $ref: '#/components/schemas/CountryCode'
    Action:
      allOf:
        - $ref: '#/components/schemas/ActionBase'
        - type: object
          required:
            - sid
            - name
            - numbers
            - script
            - format
            - version
            - created
            - updated
          properties:
            sid:
              $ref: '#/components/schemas/SID'
            numbers:
              type: array
              items:
                $ref: '#/components/schemas/NumberAssigned'
            version:
              type: string
              examples:
                - '1.0'
            created:
              $ref: '#/components/schemas/Datetime'
            updated:
              $ref: '#/components/schemas/Datetime'
    ActionsSearchResult:
      allOf:
        - $ref: '#/components/schemas/SearchResult'
        - type: object
          description: Actions search result
          required:
            - hits
          properties:
            hits:
              type: array
              items:
                $ref: '#/components/schemas/Action'
      unevaluatedProperties: false
    ActionCreate:
      allOf:
        - $ref: '#/components/schemas/ActionBase'
        - type: object
          required:
            - name
            - script
    ActionsVariables:
      type: object
      maxProperties: 64
      additionalProperties: true
      description: |
        Key/value object defining variables. Keys must start with a `$` followed by a letter. Keys not matching the regex `^\$[a-zA-Z][a-zA-Z0-9_]{0,254}$` will be silently ignored. Values can be of any type.
      patternProperties:
        ^\$[a-zA-Z][a-zA-Z0-9_]{0,254}$:
          description: variable value of any type
      examples:
        - $customID: 42
          $target: '+15559820800'
          $mylist:
            - listItem1
            - listItem2
          $myobject:
            key1: value1
            key2: value2
    ActionsStartInput:
      type: object
      additionalProperties: false
      properties:
        variables:
          $ref: '#/components/schemas/ActionsVariables'
    ActionRunID:
      type: string
      minLength: 1
      maxLength: 64
      examples:
        - api:9MNAB2H6
        - inbound-call:240419830042
        - inbound-sms:240419830042
    ActionsStartOutput:
      type: object
      required:
        - runid
      additionalProperties: false
      properties:
        runid:
          $ref: '#/components/schemas/ActionRunID'
    ActionRunStatus:
      type: object
      readOnly: true
      additionalProperties: false
      required:
        - variables
      properties:
        variables:
          $ref: '#/components/schemas/ActionsVariables'
    AudioFileStatus:
      type: string
      description: Audio file status
      enum:
        - ready
        - processing
        - pending-content
        - pending-conversion
        - error
      x-enumNames:
        - AudioFileStatusReady
        - AudioFileStatusProcessing
        - AudioFileStatusPendingContent
        - AudioFileStatusPendingConversion
        - AudioFileStatusError
      examples:
        - ready
        - error
    AudioFileSource:
      type: string
      description: Audio file source
      enum:
        - phone-record
        - system
        - file-upload
      examples:
        - system
        - file-upload
    AudioFileName:
      type: string
      description: Audio file name
      minLength: 1
      maxLength: 64
      examples:
        - My Audio File
        - Welcome
        - PleaseWait
    MediaURL:
      type: string
      format: uri
      description: |
        A URL to media hosted by Callr. Unlike user-submitted endpoints, this value is generated by the API and its host varies by environment (it may not resolve to a public domain, e.g. in local development).
      examples:
        - https://media.callr.com/library/1214981-F54777F6.mp3
    AudioFile:
      description: Audio file
      type: object
      required:
        - sid
        - name
        - duration
        - source
        - readonly
        - status
        - created
        - updated
      additionalProperties: false
      properties:
        sid:
          $ref: '#/components/schemas/SID'
        name:
          $ref: '#/components/schemas/AudioFileName'
        duration:
          type: integer
          description: Duration in seconds
          examples:
            - 42
            - 8
        source:
          $ref: '#/components/schemas/AudioFileSource'
        url:
          $ref: '#/components/schemas/MediaURL'
        readonly:
          type: boolean
          description: System provided files cannot be modified
          examples:
            - true
            - false
        status:
          $ref: '#/components/schemas/AudioFileStatus'
        created:
          $ref: '#/components/schemas/Datetime'
        updated:
          $ref: '#/components/schemas/Datetime'
    AudioFilesSearchResult:
      allOf:
        - $ref: '#/components/schemas/SearchResult'
        - type: object
          description: Audio files search result
          required:
            - hits
          properties:
            hits:
              type: array
              items:
                $ref: '#/components/schemas/AudioFile'
      unevaluatedProperties: false
    AudioFileUpdate:
      description: Audio file update object
      type: object
      required: []
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/AudioFileName'
    AudioFilePhoneID:
      type: object
      required:
        - code
        - number
      properties:
        code:
          type: string
          description: The DTMF code to record yourself
          examples:
            - '123456'
        number:
          $ref: '#/components/schemas/PhoneNumber'
          description: The phone number to dial to record yourself
    Amount:
      description: Amount in cents
      type: string
      examples:
        - '5.50'
        - '1.00'
        - '432.44'
        - '0.0001'
      pattern: ^[0-9]+(\.[0-9]{2,6})?$
      minLength: 1
    CurrencyCode:
      type: string
      description: Currency code
      pattern: ^[A-Z]{3}$
      examples:
        - EUR
        - USD
      enum:
        - EUR
        - USD
    BillingCredit:
      description: Prepaid credit balance
      type: object
      required:
        - amount
        - currency
      additionalProperties: false
      properties:
        amount:
          $ref: '#/components/schemas/Amount'
          description: Credit balance **in cents**
        currency:
          $ref: '#/components/schemas/CurrencyCode'
    BillingDestination:
      description: Schema for representing a destination
      type: object
      required:
        - id
        - country
        - name
        - created
      additionalProperties: false
      properties:
        id:
          type: integer
          description: ID of the destination
          minimum: 1
        country:
          $ref: '#/components/schemas/CountryCode'
        name:
          type: string
          description: Destination name
          examples:
            - France - Geographic
            - France - Mobile
        created:
          $ref: '#/components/schemas/Datetime'
    CallID:
      description: Call ID
      format: int64
      type: integer
      minimum: 1
      examples:
        - 240711945874
        - 210548952067
    Direction:
      type: string
      description: |
        The direction. Inbound is a call or an SMS received by the Callr platform. Outbound is a call or an SMS initiated by the Callr platform.
      enum:
        - inbound
        - outbound
      examples:
        - inbound
        - outbound
    TaskID:
      description: Task ID
      type: string
      examples:
        - sampleTaskID1234567890abcdef0000
      pattern: ^[a-zA-Z0-9]{32,256}$
      maxLength: 256
      minLength: 32
    EndUserBase:
      type: object
      properties:
        name:
          type: string
          maxLength: 32
          minLength: 1
          examples:
            - French Corp
            - ACME Corp USA
        address:
          type: object
          required:
            - country
          additionalProperties: false
          properties:
            country:
              $ref: '#/components/schemas/CountryCode'
            city:
              type: string
              maxLength: 255
              examples:
                - Paris
                - London
                - New York
        comment:
          type: string
          maxLength: 255
          examples:
            - French Subsidiary
            - USA HQ
    EndUser:
      allOf:
        - $ref: '#/components/schemas/EndUserBase'
        - type: object
          required:
            - sid
            - type
            - created
            - updated
            - name
            - address
          properties:
            sid:
              $ref: '#/components/schemas/SID'
              readOnly: true
            type:
              description: |
                The type of end user. It can be either **self** (your company) or **third-party**. Any end user you create is considered as third-party.
              type: string
              enum:
                - self
                - third-party
              readOnly: true
              examples:
                - third-party
            created:
              $ref: '#/components/schemas/Datetime'
              readOnly: true
            updated:
              $ref: '#/components/schemas/Datetime'
              readOnly: true
            deletable:
              type: boolean
              description: |
                Whether the end user can be deleted or not. Self end user cannot be deleted. Third party end users can be deleted if they are not associated with any phone number.
              readOnly: true
              examples:
                - true
    EndUserSearchResult:
      allOf:
        - $ref: '#/components/schemas/SearchResult'
        - type: object
          description: End user search result
          required:
            - hits
          properties:
            hits:
              type: array
              items:
                $ref: '#/components/schemas/EndUser'
      unevaluatedProperties: false
    EndUserCreate:
      allOf:
        - $ref: '#/components/schemas/EndUserBase'
        - type: object
          required:
            - name
            - address
      unevaluatedProperties: false
    EndUserUpdate:
      allOf:
        - $ref: '#/components/schemas/EndUserBase'
      unevaluatedProperties: false
    ScenarioAssigned:
      type: object
      readOnly: true
      description: Scenario assigned to number
      required:
        - sid
        - name
        - type
      additionalProperties: false
      properties:
        sid:
          $ref: '#/components/schemas/SID'
        name:
          type: string
          examples:
            - My Call Flow
            - AI Voicemail
            - Call Forwarding
        type:
          type: object
          required:
            - name
            - version
          additionalProperties: false
          properties:
            name:
              type: string
              examples:
                - Actions
            version:
              type: string
              examples:
                - '1.0'
    NumberPricing:
      description: Number pricing schema
      type: object
      required:
        - increment
        - minduration
        - minute
        - mrc
        - nrc
        - setup
      additionalProperties: false
      properties:
        increment:
          type: integer
        minduration:
          type: integer
        minute:
          $ref: '#/components/schemas/Amount'
        mrc:
          $ref: '#/components/schemas/Amount'
        nrc:
          $ref: '#/components/schemas/Amount'
        setup:
          $ref: '#/components/schemas/Amount'
    EndUserAssigned:
      allOf:
        - $ref: '#/components/schemas/EndUser'
        - type: object
          required:
            - freeze
            - compliance
          properties:
            freeze:
              type: object
              required:
                - frozen
              additionalProperties: false
              properties:
                unfreeze:
                  $ref: '#/components/schemas/Datetime'
                frozen:
                  type: boolean
                  examples:
                    - true
                    - false
            compliance:
              type: object
              required:
                - status
                - compliant
              additionalProperties: false
              properties:
                status:
                  type: string
                  enum:
                    - no-rules-required
                    - country-not-allowed
                    - missing-documents
                    - pending
                    - approved
                  examples:
                    - no-rules-required
                    - approved
                compliant:
                  type: boolean
                  examples:
                    - true
      unevaluatedProperties: false
    Number:
      allOf:
        - $ref: '#/components/schemas/NumberAssigned'
        - type: object
          required:
            - compliance
            - contract
            - pricing
            - enduser
          properties:
            scenario:
              $ref: '#/components/schemas/ScenarioAssigned'
            compliance:
              type: object
              required:
                - state
              additionalProperties: false
              properties:
                state:
                  type: string
                  enum:
                    - invalid
                    - active
                    - warning
                    - disabled
                blockedAfter:
                  $ref: '#/components/schemas/Datetime'
            contract:
              type: object
              required:
                - ends
                - renew
              properties:
                ends:
                  $ref: '#/components/schemas/Datetime'
                renew:
                  type: boolean
              additionalProperties: false
            pricing:
              $ref: '#/components/schemas/NumberPricing'
            enduser:
              $ref: '#/components/schemas/EndUserAssigned'
      unevaluatedProperties: false
    NumberSearchResult:
      allOf:
        - $ref: '#/components/schemas/SearchResult'
        - type: object
          description: Numbers search result
          required:
            - hits
          properties:
            hits:
              type: array
              items:
                $ref: '#/components/schemas/Number'
      unevaluatedProperties: false
    NumberUpdate:
      type: object
      required: []
      additionalProperties: false
      properties:
        scenario:
          $ref: '#/components/schemas/SID'
          description: The scenario to attach to
        enduser:
          $ref: '#/components/schemas/SID'
          description: The end user to assign to
    PaymentType:
      description: Either prepaid or postpaid
      type: string
      enum:
        - postpaid
        - prepaid
      examples:
        - prepaid
        - postpaid
    NumberStoreContract:
      description: Phone number subscription contract
      type: object
      required:
        - paymentType
        - durationInMonths
        - ends
      additionalProperties: false
      properties:
        paymentType:
          $ref: '#/components/schemas/PaymentType'
        durationInMonths:
          description: Contract duration in month
          type: integer
          minimum: 1
        ends:
          $ref: '#/components/schemas/Datetime'
    NumberStore:
      type: object
      additionalProperties: false
      required:
        - number
        - pricing
      properties:
        number:
          $ref: '#/components/schemas/PhoneNumber'
        pricing:
          $ref: '#/components/schemas/NumberPricing'
    NumberStoreReservation:
      description: Phone number store reservation
      type: object
      readOnly: true
      required:
        - token
        - expires
        - contract
        - items
      additionalProperties: false
      properties:
        token:
          description: Reservation token
          type: string
          minLength: 40
        expires:
          description: Token expiration date
          $ref: '#/components/schemas/Datetime'
        contract:
          $ref: '#/components/schemas/NumberStoreContract'
        items:
          description: Numbers reserved
          type: array
          items:
            $ref: '#/components/schemas/NumberStore'
    NumberStoreError:
      description: Phone number store in error
      type: object
      required:
        - message
        - number
      additionalProperties: false
      properties:
        message:
          description: Error message
          type: string
        number:
          $ref: '#/components/schemas/PhoneNumber'
    NumberStoreBuyResult:
      description: Buy status
      type: object
      required:
        - contract
        - errors
        - items
      additionalProperties: false
      properties:
        contract:
          $ref: '#/components/schemas/NumberStoreContract'
        errors:
          description: Phone numbers reserved but not bought
          type: array
          items:
            $ref: '#/components/schemas/NumberStoreError'
        items:
          description: Phone numbers bought
          type: array
          items:
            $ref: '#/components/schemas/NumberStore'
    NumberAvailable:
      description: Phone number availability in the store
      type: object
      required:
        - classic
        - gold
      additionalProperties: false
      properties:
        classic:
          description: The quantity of **classic** numbers available
          type: integer
          minimum: 0
          examples:
            - 100
            - 200
        gold:
          description: The quantity of **gold** numbers available
          type: integer
          minimum: 0
          examples:
            - 10
            - 20
    CountryStore:
      description: A country in the number store
      type: object
      readOnly: true
      required:
        - available
        - country
        - label
      additionalProperties: false
      properties:
        available:
          $ref: '#/components/schemas/NumberAvailable'
        country:
          $ref: '#/components/schemas/CountryCode'
        label:
          description: The country name in english
          type: string
          examples:
            - France
            - United States
    NumberStoreType:
      type: object
      readOnly: true
      required:
        - available
        - type
        - label
      additionalProperties: false
      properties:
        available:
          $ref: '#/components/schemas/NumberAvailable'
        type:
          $ref: '#/components/schemas/NumberType'
        label:
          type: string
          examples:
            - Geographic
            - Non Geographic
    NumberAreaCode:
      type: object
      readOnly: true
      required:
        - available
        - country
        - prefix
        - area
        - localPrefix
        - type
      additionalProperties: false
      properties:
        available:
          $ref: '#/components/schemas/NumberAvailable'
        country:
          $ref: '#/components/schemas/CountryCode'
        prefix:
          description: International prefix
          type: string
          examples:
            - '+331'
            - '+1646'
        localPrefix:
          description: Local prefix
          type: string
          examples:
            - '01'
            - '646'
        area:
          description: Name of the area
          type: string
          examples:
            - Paris
            - New York
        type:
          $ref: '#/components/schemas/NumberType'
    RecordingType:
      type: string
      description: Recording type
      enum:
        - call
        - recording
        - voicemail
      examples:
        - call
        - recording
        - voicemail
    CallerID:
      description: Caller ID
      type: object
      required:
        - restricted
      additionalProperties: false
      properties:
        name:
          type: string
          description: Caller ID Name
        number:
          $ref: '#/components/schemas/PhoneNumber'
          description: Caller ID Number
        restricted:
          type: boolean
          description: Whether the Caller ID is restricted
    Language:
      type: string
      description: BCP 47 language tag
      pattern: ^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]{2,8})*$
      examples:
        - en-US
        - es-ES
        - fr-FR
    RecordingOptions:
      description: Recording options
      type: object
      required:
        - ner
        - pii
        - feeds
        - language
        - sentiment
        - transcription
      additionalProperties: false
      properties:
        ner:
          type: boolean
          description: Whether to enable named entity recognition
          examples:
            - true
        pii:
          type: boolean
          description: Whether to enable personally identifiable information detection
          examples:
            - true
        feeds:
          type: string
          description: Feed to enable
          enum:
            - leg_a
            - leg_b
            - all
          examples:
            - all
        language:
          $ref: '#/components/schemas/Language'
          description: Language to use for transcription
        sentiment:
          type: boolean
          description: Whether to enable sentiment analysis
          examples:
            - true
        transcription:
          type: boolean
          description: Whether to enable transcription
          examples:
            - true
    RecordingTextAnalysisEntity:
      type: object
      required:
        - text
        - offset
        - category
        - confidence
      additionalProperties: false
      properties:
        text:
          type: string
        offset:
          type: integer
        category:
          type: string
        confidence:
          type: number
          format: double
    RecordingTranscriptionWord:
      type: object
      required:
        - word
        - offset
        - duration
      additionalProperties: false
      properties:
        word:
          type: string
          description: Word recognized in the audio
          examples:
            - hello
            - world
        offset:
          type: number
          format: double
          description: Start time of the word in seconds
          examples:
            - 0
            - 0.42
        duration:
          type: number
          format: double
          description: Duration of the word in seconds
          examples:
            - 0
            - 0.42
    RecordingTranscriptionPhrase:
      type: object
      required:
        - offset
        - display
        - confidence
        - words
      additionalProperties: false
      properties:
        offset:
          type: number
          format: double
          description: Start time of the phrase in seconds
          minimum: 0
          examples:
            - 0
            - 10.42
        display:
          type: string
          description: Display representation of the transcribed text
          examples:
            - Hello, world!
            - Goodbye, world!
        confidence:
          type: number
          format: double
          description: Confidence score for the transcript
          minimum: 0
          maximum: 1
          examples:
            - 0.98
            - 0.8
        words:
          type: array
          items:
            $ref: '#/components/schemas/RecordingTranscriptionWord'
    RecordingTranscriptionFeedData:
      type: object
      required:
        - display
        - language
        - lexical
        - phrases
      additionalProperties: false
      properties:
        display:
          type: string
          description: |
            The display form of the recognized text. Added punctuation and capitalization are included.
          examples:
            - Hello, world!
            - Goodbye, world!
        language:
          $ref: '#/components/schemas/Language'
        lexical:
          type: string
          description: Lexical representation of the transcribed text
          examples:
            - hello world
            - goodbye world
        phrases:
          type: array
          items:
            $ref: '#/components/schemas/RecordingTranscriptionPhrase'
    RecordingTranscriptionSentiment:
      type: object
      required:
        - sentiment
        - confidenceScores
      properties:
        sentiment:
          type: string
          description: Sentiment analysis
          examples:
            - neutral
            - negative
            - positive
        confidenceScores:
          type: object
          description: Confidence scores for each sentiment
          required:
            - neutral
            - negative
            - positive
          additionalProperties: false
          properties:
            neutral:
              type: number
              format: double
              minimum: 0
              maximum: 1
              description: Confidence score for neutral sentiment
              examples:
                - 0.98
                - 0.77
            negative:
              type: number
              format: double
              minimum: 0
              maximum: 1
              description: Confidence score for negative sentiment
              examples:
                - 0.98
                - 0.77
            positive:
              type: number
              format: double
              minimum: 0
              maximum: 1
              description: Confidence score for positive sentiment
              examples:
                - 0.98
                - 0.77
    RecordingTranscriptionFeed:
      type: object
      required:
        - data
        - feed
        - sentiment
      additionalProperties: false
      properties:
        ner:
          type: array
          description: Named Entity Recognized (NER)
          items:
            $ref: '#/components/schemas/RecordingTextAnalysisEntity'
        pii:
          type: array
          description: Personally Identified Informations (PII)
          items:
            $ref: '#/components/schemas/RecordingTextAnalysisEntity'
        data:
          $ref: '#/components/schemas/RecordingTranscriptionFeedData'
        feed:
          type: string
          description: Feed name
          examples:
            - leg_a
            - leg_b
        sentiment:
          $ref: '#/components/schemas/RecordingTranscriptionSentiment'
    RecordingTranscription:
      type: object
      description: |
        The transcription of the recording.
      required:
        - feeds
      additionalProperties: false
      properties:
        feeds:
          type: array
          items:
            $ref: '#/components/schemas/RecordingTranscriptionFeed'
        version:
          type: string
          description: |
            The version of the transcription. This is used to determine the format of the transcription. It is not used for versioning the transcription itself.
          examples:
            - '2.0'
            - '1.0'
    Recording:
      description: Recording
      type: object
      required:
        - sid
        - type
        - callid
        - scenario
        - created
        - caller
        - callee
        - duration
        - read
        - status
        - size
      additionalProperties: false
      properties:
        sid:
          $ref: '#/components/schemas/SID'
        type:
          $ref: '#/components/schemas/RecordingType'
        callee:
          $ref: '#/components/schemas/PhoneNumber'
          description: Callee phone number
        scenario:
          type: object
          additionalProperties: false
          properties:
            sid:
              $ref: '#/components/schemas/SID'
            name:
              type: string
              description: Scenario name
              examples:
                - My Call Flow
                - AI Voicemail
        callid:
          $ref: '#/components/schemas/CallID'
        created:
          $ref: '#/components/schemas/Datetime'
        readAt:
          $ref: '#/components/schemas/Datetime'
        duration:
          type: integer
          description: Call duration in seconds
          minimum: 0
          examples:
            - 5
        caller:
          $ref: '#/components/schemas/CallerID'
          description: Caller
        read:
          type: boolean
          description: Read status
          examples:
            - true
        status:
          type: string
          description: Recording status
          enum:
            - ready
            - processing
            - pending
            - error
            - recording
          examples:
            - ready
            - error
        url:
          $ref: '#/components/schemas/MediaURL'
          description: Recording URL, available when status is ready
        size:
          type: integer
          description: Storage used in bytes
          minimum: 0
          examples:
            - 123456
        options:
          $ref: '#/components/schemas/RecordingOptions'
        transcription:
          $ref: '#/components/schemas/RecordingTranscription'
    RecordingsSearchResult:
      allOf:
        - $ref: '#/components/schemas/SearchResult'
        - type: object
          description: Recordings search result
          required:
            - hits
          properties:
            hits:
              type: array
              items:
                $ref: '#/components/schemas/Recording'
      unevaluatedProperties: false
    RecordingUpdate:
      description: Recording update object
      type: object
      additionalProperties: false
      properties:
        read:
          type: boolean
          description: Read status
          examples:
            - true
    SMSSender:
      description: |
        The SMS sender. If empty, a value will be automatically set depending on the destination. Otherwise, the sender must be either a dedicated shortcode, or an alphanumeric sender (with at least one character - 11 chars maximum). Custom SMS senders must be approved by our team and downstream carriers. You can request a custom sender on https://app.callr.com.
      type: string
      examples:
        - SMS
        - MyCompany
        - '+15551230000'
        - '+33639984242'
      oneOf:
        - type: string
          pattern: ^[ a-zA-Z0-9_-]*$
          maxLength: 11
          minLength: 0
        - $ref: '#/components/schemas/PhoneNumber'
    SMSTrafficType:
      description: |
        Traffic type of an SMS message. Carriers require this to be set to either `marketing` or `alerting`.
      type: string
      enum:
        - marketing
        - alerting
      examples:
        - marketing
    SMSStatus:
      description: |
        The status of the SMS.

        `created` = The SMS has been created.
        `error` = The SMS has an error.
        `expired` = The SMS has expired.
        `failed` = The SMS has failed.
        `pending` = The SMS is waiting to be sent on our side.
        `delivered` = The SMS has been delivered to the recipient.
        `remote-queued` = The SMS is queued on the remote side.
        `sent` = The SMS has been sent.
      type: string
      enum:
        - created
        - error
        - expired
        - failed
        - pending
        - delivered
        - remote-queued
        - sent
      examples:
        - sent
        - delivered
    SMSBody:
      description: SMS body
      type: object
      additionalProperties: false
      properties:
        text:
          type: string
          examples:
            - Hello world!
            - Bonjour !
          maxLength: 3200
          minLength: 1
      required:
        - text
    SMSEncoding:
      description: |
        By default, we automatically detect the encoding based on the characters used in the message. If you want to force the encoding, you can use this field. The SMS body will be processed according to the encoding specified. Depending on the encoding, messages may be split into parts of 153 (GSM 03.38) or 67 (UNICODE) characters. Please note that some countries only support GSM encoding.
      type: string
      enum:
        - gsm
        - unicode
      examples:
        - gsm
    SMSStatusHistory:
      description: The status history of the message
      type: object
      required:
        - before
        - after
        - at
      additionalProperties: false
      properties:
        after:
          $ref: '#/components/schemas/SMSStatus'
        before:
          $ref: '#/components/schemas/SMSStatus'
        at:
          $ref: '#/components/schemas/Datetime'
    SMS:
      description: SMS
      type: object
      readOnly: true
      required:
        - direction
        - sid
        - from
        - to
        - body
        - trafficType
        - status
        - created
        - updated
        - parts
        - encoding
        - cost
        - paymentType
      additionalProperties: false
      properties:
        direction:
          $ref: '#/components/schemas/Direction'
        sid:
          $ref: '#/components/schemas/SID'
        from:
          $ref: '#/components/schemas/SMSSender'
        to:
          $ref: '#/components/schemas/PhoneNumber'
        body:
          $ref: '#/components/schemas/SMSBody'
        trafficType:
          $ref: '#/components/schemas/SMSTrafficType'
        status:
          $ref: '#/components/schemas/SMSStatus'
        error:
          type: string
          description: An error message, when applicable
        created:
          $ref: '#/components/schemas/Datetime'
        delivered:
          $ref: '#/components/schemas/Datetime'
        updated:
          $ref: '#/components/schemas/Datetime'
        sent:
          $ref: '#/components/schemas/Datetime'
        parts:
          description: The parts of the message
          type: integer
          examples:
            - 10
          minimum: 1
          maximum: 20
        network:
          description: ITU-T E.212 MCC MNC network
          type: string
          examples:
            - '20801'
            - '310005'
        encoding:
          $ref: '#/components/schemas/SMSEncoding'
        cost:
          $ref: '#/components/schemas/Amount'
        paymentType:
          $ref: '#/components/schemas/PaymentType'
        statusHistory:
          type: array
          items:
            $ref: '#/components/schemas/SMSStatusHistory'
    SMSSearchResult:
      allOf:
        - $ref: '#/components/schemas/SearchResult'
        - type: object
          required:
            - hits
          properties:
            hits:
              type: array
              items:
                $ref: '#/components/schemas/SMS'
      unevaluatedProperties: false
    TaskStatus:
      type: string
      enum:
        - pending
        - running
        - canceled
        - done
      x-enumNames:
        - TaskStatusPending
        - TaskStatusRunning
        - TaskStatusCanceled
        - TaskStatusDone
      examples:
        - pending
        - running
        - canceled
        - done
    Task:
      description: Task
      type: object
      required:
        - id
        - status
        - percent
      additionalProperties: false
      properties:
        id:
          $ref: '#/components/schemas/TaskID'
        status:
          $ref: '#/components/schemas/TaskStatus'
        percent:
          type: number
          minimum: 0
          maximum: 100
          examples:
            - 42
            - 0.1
        ended:
          $ref: '#/components/schemas/Datetime'
        result:
          description: The result can be of any type, depending on the task
          x-go-type: json.RawMessage
        error:
          type: string
    WebhookType:
      description: |-
        - `v2.billing.credit.topup` = Your account has been credited with a new amount.
        - `v2.billing.credit.warning` = Your prepaid balance has reached its warning level.
        - `v2.billing.credit.shutdown` = Your prepaid balance has reached its shutdown level. Your account is suspended.
        - `v2.call.inbound.started` = An inbound call just started.
        - `v2.call.inbound.ended` = An inbound call just hung up.
        - `v2.call.outbound.started` = An outbound call just started.
        - `v2.call.outbound.ended` = An outbound call just hung up.
        - `v2.number.assigned` = A phone number was assigned to your account.
        - `v2.number.unassigned` = A phone number was unassigned from your account.
        - `v2.task.updated` = A task has been updated.
        - `v2.audio-file.updated` = An audio file has been updated.
        - `v2.recording.updated` = A recording has been updated.
        - `v2.sms.inbound.received` = An inbound SMS has been received.
        - `v2.sms.outbound.updated` = An outbound SMS has an updated status.
      type: string
      enum:
        - v2.billing.credit.topup
        - v2.billing.credit.warning
        - v2.billing.credit.shutdown
        - v2.call.inbound.started
        - v2.call.inbound.ended
        - v2.call.outbound.started
        - v2.call.outbound.ended
        - v2.number.assigned
        - v2.number.unassigned
        - v2.task.updated
        - v2.audio-file.updated
        - v2.recording.updated
        - v2.sms.inbound.received
        - v2.sms.outbound.updated
    WebhookStatus:
      description: Webhook status
      type: string
      enum:
        - disabled
        - disabled-admin
        - disabled-system
        - enabled
      x-enumNames:
        - WebhookStatusDisabled
        - WebhookStatusDisabledAdmin
        - WebhookStatusDisabledSystem
        - WebhookStatusEnabled
      examples:
        - enabled
        - disabled
    URI:
      type: string
      pattern: ^https?:\/\/(?:[a-zA-Z0-9-]+\.)+[a-zA-Z]{2,}(?:\/.*)?$
      format: uri
      examples:
        - https://example.com
        - https://www.example.com/path
    WebhookOptions:
      description: Webhook options
      type: object
      required:
        - hmac
      additionalProperties: false
      properties:
        hmac:
          type: object
          additionalProperties: false
          required:
            - secret
            - algorithm
          properties:
            secret:
              type: string
              description: The secret key used to generate the HMAC signature
              minLength: 8
              maxLength: 1024
            algorithm:
              type: string
              description: The HMAC algorithm used to generate the signature
              enum:
                - sha256
                - sha512
              examples:
                - sha512
    Webhook:
      description: Webhook
      type: object
      readOnly: true
      required:
        - sid
        - type
        - endpoint
        - status
        - failed
        - created
        - updated
      additionalProperties: false
      properties:
        sid:
          $ref: '#/components/schemas/SID'
        type:
          $ref: '#/components/schemas/WebhookType'
        endpoint:
          $ref: '#/components/schemas/URI'
        status:
          $ref: '#/components/schemas/WebhookStatus'
        options:
          $ref: '#/components/schemas/WebhookOptions'
        failed:
          type: integer
          description: The number of times your endpoint did not respond to a webhook
          examples:
            - 0
            - 42
        lastfailed:
          $ref: '#/components/schemas/Datetime'
          description: The last time your endpoint failed to respond to a webhook
        created:
          $ref: '#/components/schemas/Datetime'
        updated:
          $ref: '#/components/schemas/Datetime'
    WebhookSearchResult:
      allOf:
        - $ref: '#/components/schemas/SearchResult'
        - type: object
          description: Webhooks search result
          required:
            - hits
          properties:
            hits:
              type: array
              items:
                $ref: '#/components/schemas/Webhook'
      unevaluatedProperties: false
    WebhookCreate:
      type: object
      required:
        - endpoint
      additionalProperties: false
      properties:
        endpoint:
          $ref: '#/components/schemas/URI'
        options:
          $ref: '#/components/schemas/WebhookOptions'
    WebhookStatusUpdate:
      description: Webhook status (set by user)
      type: string
      enum:
        - disabled
        - enabled
    WebhookUpdate:
      description: Webhook update
      type: object
      required:
        - status
      additionalProperties: false
      properties:
        status:
          $ref: '#/components/schemas/WebhookStatusUpdate'
    WebhookPayloadBase:
      type: object
      readOnly: true
      properties:
        id:
          type: string
          description: Unique identifier for the event. Use this for idempotency checks.
          examples:
            - a03317440280451052hUD7yPiwWrzgGB
            - 5f4dcc3b5aa765d61d8327deb882cf99
        at:
          $ref: '#/components/schemas/Datetime'
          description: Timestamp of the event
        sid:
          $ref: '#/components/schemas/SID'
          description: Unique identifier for the webhook
        type:
          $ref: '#/components/schemas/WebhookType'
        try:
          type: integer
          description: Number of attempts made to deliver the webhook
          minimum: 0
          maximum: 10
          examples:
            - 0
      required:
        - id
        - at
        - sid
        - type
        - try
    WebhookLogStatus:
      description: The status of the request
      type: string
      enum:
        - pending
        - running
        - done
        - error
      x-enumNames:
        - WebhookLogStatusPending
        - WebhookLogStatusRunning
        - WebhookLogStatusDone
        - WebhookLogStatusError
    WebhookLog:
      allOf:
        - $ref: '#/components/schemas/WebhookPayloadBase'
        - type: object
          description: Webhook log object
          readOnly: true
          required:
            - endpoint
            - status
            - httpCode
            - duration
            - payload
          properties:
            endpoint:
              $ref: '#/components/schemas/URI'
            status:
              $ref: '#/components/schemas/WebhookLogStatus'
            httpCode:
              description: |
                The HTTP status code sent by the endpoint. 0 if the request failed before a response was received (connection error, timeout).
              type: integer
              minimum: 0
              examples:
                - 200
                - 0
            duration:
              description: The total duration of the HTTP request in seconds
              type: number
              format: double
            error:
              description: The error message if the request failed
              type: string
            payload:
              description: The payload sent
              x-go-type: json.RawMessage
      unevaluatedProperties: false
    WebhookLogsSearchResult:
      allOf:
        - $ref: '#/components/schemas/SearchResult'
        - type: object
          required:
            - hits
          properties:
            hits:
              type: array
              items:
                $ref: '#/components/schemas/WebhookLog'
      unevaluatedProperties: false
    WebhookPayloadCredit:
      type: object
      readOnly: true
      required:
        - payload
      properties:
        payload:
          description: Payload of the webhook
          type: object
          additionalProperties: false
          required:
            - balance
            - currency
            - amount
            - shutdown
            - warning
          properties:
            balance:
              $ref: '#/components/schemas/Amount'
            currency:
              $ref: '#/components/schemas/CurrencyCode'
            amount:
              $ref: '#/components/schemas/Amount'
              description: Last amount that triggered the webhook
            shutdown:
              $ref: '#/components/schemas/Amount'
            warning:
              $ref: '#/components/schemas/Amount'
    CDR:
      type: object
      required:
        - direction
        - callid
        - callerName
        - callerNumber
        - callerRestricted
        - callee
        - started
        - billingDestinationLabel
        - billingPaymentType
        - scenarioSid
        - scenarioName
        - scenarioTypeName
        - scenarioTypeVersion
      additionalProperties: false
      properties:
        direction:
          $ref: '#/components/schemas/Direction'
        callid:
          $ref: '#/components/schemas/CallID'
        bridged:
          $ref: '#/components/schemas/CallID'
          description: |
            If the call leg was bridged to another leg, its Call ID will be set here.
        callerName:
          type: string
          description: Caller ID Name
          examples:
            - John Doe
            - Sarah Pelle
            - Sarah Croche
            - ''
        callerNumber:
          $ref: '#/components/schemas/PhoneNumber'
          description: Caller ID Number
        callerRestricted:
          type: boolean
          description: Whether the Caller ID is restricted
          examples:
            - false
            - true
        callee:
          $ref: '#/components/schemas/PhoneNumber'
        started:
          $ref: '#/components/schemas/Datetime'
        answered:
          $ref: '#/components/schemas/Datetime'
        ended:
          $ref: '#/components/schemas/Datetime'
        status:
          type: string
          enum:
            - dialing
            - ringing
            - answered
            - failed
            - busy
            - unallocated
            - canceled
          examples:
            - answered
            - busy
        hangupSource:
          type: string
          enum:
            - caller
            - callee
            - system
        hangupCause:
          description: Q.850 cause code
          type: integer
          minimum: 0
          maximum: 127
          examples:
            - 16
            - 17
        hangupTech:
          type: string
          description: Technology specific hangup cause
          examples:
            - sip:200
            - sip:486
        durationTotal:
          type: integer
          minimum: 0
          examples:
            - 42
        durationAnswered:
          type: integer
          minimum: 0
          examples:
            - 40
        durationBilled:
          type: integer
          minimum: 0
          examples:
            - 60
        billingDestinationLabel:
          type: string
          examples:
            - France - Geographic
            - France - Mobile
        billingDestinationID:
          type: integer
          minimum: 0
        billingDebit:
          $ref: '#/components/schemas/Amount'
        billingCredit:
          $ref: '#/components/schemas/Amount'
        billingPaymentType:
          $ref: '#/components/schemas/PaymentType'
        scenarioSid:
          $ref: '#/components/schemas/SID'
        scenarioName:
          type: string
          examples:
            - My Call Flow
            - AI Voicemail
            - Call Forwarding
        scenarioTypeName:
          type: string
          examples:
            - Actions
        scenarioTypeVersion:
          type: string
          examples:
            - '1.0'
  responses:
    400BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    401Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    403Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    405MethodNotAllowed:
      description: Method Not Allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    429TooManyRequests:
      description: Too Many Requests (rate limit exceeded)
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    500InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    404NotFound:
      description: Resource Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    SearchOrder:
      in: query
      name: order
      description: Sort order (ascending or descending)
      schema:
        type: string
        default: desc
        enum:
          - asc
          - desc
        x-enumNames:
          - Ascending
          - Descending
    SearchOffset:
      in: query
      name: offset
      description: Search offset index (zero-based)
      schema:
        $ref: '#/components/schemas/SearchOffset'
    SearchLimit:
      in: query
      name: limit
      description: Number of items to return
      schema:
        description: Limit search results
        type: integer
        examples:
          - 20
        minimum: 1
        maximum: 100
        default: 10
    SIDPath:
      in: path
      name: sid
      required: true
      description: Resource SID (8 lowercase alphanumeric characters)
      schema:
        $ref: '#/components/schemas/SID'