# Announce a call

## OpenAPI Specification

```yaml
openapi: 3.0.1
info:
  title: ''
  description: ''
  version: 1.0.0
paths:
  /api/bcid/v1/calls:
    post:
      summary: Announce a call
      deprecated: false
      description: >-
        Call this from the originating dialler at dial time. This is an HTTP
        request. It is not a SIP header.


        Auth is `X-BCID-Publish-Token`, not the API key. Get the token from the
        dashboard. It is shown once. Do not put the token in a SIP header. Do
        not send it to the terminating switch.


        The business pays 2 credits for a signed announcement. `from` must be an
        approved number you own. `to` binds the announcement to this callee,
        then CallerAPI drops it. The announcement is valid for 90 seconds.


        A number still in review returns 403. Not enough credits returns 402. A
        deployment that cannot sign returns 503.
      operationId: announceCall
      tags:
        - Business Caller ID/REST
      parameters:
        - name: X-BCID-Publish-Token
          in: header
          description: Publish token from the dashboard. Shown once. Not the API key.
          required: true
          example: YOUR_PUBLISH_TOKEN
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - from
                - to
              properties:
                from:
                  type: string
                  description: >-
                    The business number as it will appear to the callee, in
                    E.164.
                  example: '+18883578668'
                to:
                  type: string
                  description: >-
                    The called number, in E.164. Used only to bind the
                    announcement.
                  example: '+14155550123'
      responses:
        '200':
          description: >-
            The announcement is stored. The business paid 2 credits. The
            terminating switch can verify this call until expires_at.
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - data
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  data:
                    type: object
                    required:
                      - expires_at
                      - valid_for_seconds
                      - credits_charged
                    properties:
                      expires_at:
                        type: string
                        format: date-time
                      valid_for_seconds:
                        type: integer
                        description: Always 90.
                      credits_charged:
                        type: integer
                        description: >-
                          Credits charged to the business for this announcement.
                          Always 2.
          headers: {}
          x-apidog-name: Announcement stored
        '400':
          description: Missing or invalid from or to, or from cannot originate a call.
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - message
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  message:
                    type: string
          headers: {}
          x-apidog-name: Missing or invalid from or to
        '401':
          description: Missing or invalid publish token.
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - message
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  message:
                    type: string
          headers: {}
          x-apidog-name: Missing or invalid publish token
        '402':
          description: The business does not have enough credits for this announcement.
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - message
                  - credits_needed
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  message:
                    type: string
                  credits_needed:
                    type: integer
                    description: Always 2.
          headers: {}
          x-apidog-name: Insufficient credits
        '403':
          description: No approved Business Caller ID entry you own matches that number.
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - message
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  message:
                    type: string
          headers: {}
          x-apidog-name: Number not approved or not yours
        '503':
          description: Call verification is not available on this deployment.
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - message
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  message:
                    type: string
          headers: {}
          x-apidog-name: Announcement is not available
      security:
        - CallerAPI Key: []
          x-apidog:
            schemeGroups:
              - id: 7Wgpz7XqJ5wdLyzsKr91e
                schemeIds:
                  - CallerAPI Key
            required: true
            use:
              id: 7Wgpz7XqJ5wdLyzsKr91e
      x-apidog-folder: Business Caller ID/REST
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/1027392/apis/api-43957286-run
components:
  schemas: {}
  securitySchemes:
    CallerAPI Key:
      type: apikey
      in: header
      name: x-auth
    ApiKeyAuth:
      type: apikey
      in: header
      name: X-Auth
      description: CallerAPI API key (UUID).
servers:
  - url: https://api.callerapi.com
    description: Prod Env
security:
  - CallerAPI Key: []
    x-apidog:
      schemeGroups:
        - id: 7Wgpz7XqJ5wdLyzsKr91e
          schemeIds:
            - CallerAPI Key
      required: true
      use:
        id: 7Wgpz7XqJ5wdLyzsKr91e

```