openapi: 3.0.1
info:
  title: Global API V2
  description: >
    Bandwidth's global API is an application programming interface for
    Bandwidth's global network.


    ## Versions


    |API Version|Description|Documentation|

    |:---:|:---:|:---|

    |`v1`|Our current API, which includes number ordering, compliance,
    configuration and inventory management to support your Voice and SMS
    communications.| [Click
    here](https://dev.bandwidth.com/apis/legacy-apis/global/)|

    |`v2`|Our CDRs (Call Detail Records) API.|Currently viewing|

    |`v3`|Our Porting API in Limited Availability|[Click
    here](https://dev.bandwidth.com/apis/legacy-apis/global/v3/)|

    |`beta`|Early access to APIs under development including Number
    Whitelisting.|[Click
    here](https://dev.bandwidth.com/apis/legacy-apis/global/beta/)|


    ## Global Emergency Address and Endpoint Provisioning


    Please refer to the [Unified Emergency Services Provisioning
    API](https://dev.bandwidth.com/apis/emergency-provisioning/) guide to
    automate the provisioning process for endpoints and emergency addresses on
    the Global Portal.


    ## Access


    Authentication for Bandwidth's global API is done with API keys. Please
    ensure:


    - Your account is activated for API access. You can do so on our [Global
    Portal](https://app.voxbone.com/home). If you have trouble, reach out to
    your account manager or raise a support ticket.

    - You've setup an API key. You can generate your API key under **Settings >
    API**.


    ## Environments


    There are currently two environments for our global APIs:


    | Environment | Base URL | Description |

    | --- | --- | --- |

    | Production | https://api.voxbone.com | Live production network. |

    | Sandbox | https://api.sandbox.voxbone.com | Intended for simulating
    ordering and address verification. You can test ordering without being
    charged, service activation and more. Any API calls performed through our
    Sandbox API can be viewed via our [Sandbox
    Portal](https://sandbox.voxbone.com/sandbox-v3/). |


    ## Security & Rate Limiting

     For protecting both your apps and our systems, a __20 requests per second by client IP__ is performed on your API calls. If you send more requests, your requests may be rejected by an `HTTP 509 Bandwidth Limit Exceeded` or `HTTP 429 Too Many Requests` in the response.
  contact:
    name: Bandwidth
  termsOfService: https://www.bandwidth.com/legal/terms-of-use-bandwidthcom-web-sites/
  version: '1.0'
servers:
  - url: https://api.voxbone.com/v2
tags:
  - name: CDRs
    description: >
      With each CDR being provided in real-time, you can integrate the data into
      your internal platform, using call quality metrics to identify call
      experience issues before your customers or end-users do. You can also use
      our API to perform instant billing or reconciliation.
paths:
  /cdr/calls:
    get:
      tags:
        - CDRs
      summary: List CDRs with filters
      description: List CDRs with filters
      operationId: searchCdrsExternalUsingGET
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/countryCodeA3'
        - $ref: '#/components/parameters/e164'
        - $ref: '#/components/parameters/eventType'
        - $ref: '#/components/parameters/callType'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/anonymized'
        - $ref: '#/components/parameters/direction'
        - $ref: '#/components/parameters/originationCountryCodeA3'
        - $ref: '#/components/parameters/destinationCountryCodeA3'
      responses:
        '200':
          $ref: '#/components/responses/listCallsResponse'
        '400':
          $ref: '#/components/responses/badRequestErrorResponse'
        '402':
          $ref: '#/components/responses/paymentRequiredResponse'
        '403':
          $ref: '#/components/responses/forbiddenErrorResponse'
        '405':
          $ref: '#/components/responses/notAllowedErrorResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
      security:
        - apiKey:
            - yourKey
    x-summary: Retrieve CDRs in real-time.
components:
  schemas:
    externalVoiceResource:
      title: ExternalVoiceResource
      type: object
      properties:
        id:
          type: string
          description: UUID for this record.
          example: ADJF4B7S2P4N95FEDG5ANH8G34
        callForwarded:
          type: boolean
          description: Whether the call has been forwarded.
          example: false
        callType:
          type: string
          description: The grouping for the type of DID.
          example: VOXDID
        capacityGroupId:
          type: integer
          description: ID of the capacity group to which the DID is mapped.
          format: int32
          example: 23
        capacityGroupName:
          type: string
          description: Name of the capacity group to which the DID is mapped.
          example: Bandwidth UK
        countDidCalls:
          type: integer
          description: Number of calls that were happening at the same time to this DID.
          format: int32
          example: 242
        cpc:
          type: string
          description: Calling Party Category.
          enum:
            - UNSUPPORTED
            - ORDINARY
            - CELLULAR
            - PAYPHONE
            - UNKNOWN
          example: ORDINARY
        currency:
          type: string
          description: Currency at which you will be charged.
          example: EUR
        destinationCountry:
          type: string
          description: Country of the DID to which the call has been placed.
          example: GBR
        destinationNumber:
          type: string
          description: DID to which the call has been placed.
          example: '442039668000'
        dialStatus:
          type: string
          description: Whether or not the call was answered by you.
          example: ANSWER
        direction:
          type: string
          description: Direction of the call either INBOUND or OUTBOUND.
          example: OUTBOUND
        duration:
          type: integer
          description: Length of the call.
          format: int64
          example: 256
        e164:
          type: string
          description: The DID in its E164 format (e.g. “+16469185038”).
          example: '442039668001'
        end:
          type: string
          description: End date and time of the call.
          example: 2020-03-04T12:04:58.000Z
        endStatus:
          type: string
          description: A description of how the call ended.
          example: NORMAL
        ip:
          type: string
          description: Your IP address.
          example: 195.88.119.98
        uri:
          type: string
          description: ID of your Uniform Resource Identifier.
          example: vox@sipvox.voxbone.com
        numberType:
          type: string
          description: >-
            GEOGRAPHIC - Numbers with local area codes (e.g 020 for London, or
            202 for Washington DC). They're attached to specific regions.
            NATIONAL - Numbers outside local area codes, covering the entire
            country. MOBILE - Mobile numbers are not attached to a specific
            geography, although those within specific administrations might have
            prefixes in common. TOLL-FREE/SHARED - Allow the cost of calling to
            be absorbed by the call recipient instead of the caller. SPECIAL -
            Numbers with a per minute cost associated with them.
          example: GEOGRAPHIC
        onNet:
          type: boolean
          description: Origin and destination are both within the Bandwidth network.
          example: false
        originCountry:
          type: string
          description: Country of the DID that initiated the call.
          example: GBR
        originalNumber:
          type: string
          description: Original number that was dialed.
          example: '442039668000'
        originationNumber:
          type: string
          description: DID that initiated the call.
          example: '442039668001'
        pop:
          type: string
          description: Location of the POP used for this call.
          example: DE
        ppe:
          type: string
          description: Price per connection of the call.
          example: '200'
        ppm:
          type: string
          description: Price per minute of the call.
          example: '50'
        ppid:
          type: string
          description: >-
            Contains the caller id information for the call on the INVITE SIP
            packet.
          example: '442039668000'
        result:
          type: string
          description: The status of the call once it has been connected to you.
          example: SUCCESS
        servicePlan:
          type: string
          description: An identifier of which service plan the call fell under.
          example: USA 48 - National
        serviceType:
          type: string
          description: The type of service for this DID, VOICE, SMS or FAX.
          example: VOICE
        sipResponseCode:
          type: integer
          description: >-
            A three-digit response of defined codes that detail the status of
            the request.
          example: 200
        start:
          type: string
          description: Start date and time of the call.
          example: 2020-03-04T12:00:38.000Z
        totalCost:
          type: string
          description: Total cost of the call incurred.
          example: '460'
        zoneId:
          type: integer
          description: ID of the Zone that was used to route this call.
          format: int32
          example: 247
        zoneName:
          type: string
          description: Name of the Zone that was used to route this call.
          example: Zone A
        zeroRated:
          type: boolean
          description: >-
            If TRUE this call was free (origin and destination are both within
            the Bandwidth network).
          example: false
        attestationIndicator:
          type: string
          description: STIR/SHAKEN attestation.
          enum:
            - A
            - B
            - C
          example: A
        quality:
          $ref: '#/components/schemas/Quality'
      description: An individual CDR (call data record).
    Link:
      type: object
      properties:
        rel:
          type: string
          example: self
        href:
          type: string
          example: https://api.voxbone.com/cdrs/voice
        hreflang:
          type: string
        media:
          type: string
        deprecation:
          type: string
        templated:
          type: boolean
        title:
          type: string
        type:
          type: string
    data:
      type: array
      description: >-
        An array which contains a collection of CDRs (call data record) in an
        individual object.
      items:
        $ref: '#/components/schemas/externalVoiceResource'
    externalCdrResourceHolder:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/data'
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        pagination:
          type: object
          properties:
            limit:
              type: integer
              description: A limit on the number of records to be returned.
              format: int32
              example: 10000
            offset:
              type: integer
              description: >-
                Indicates if the DID has been anonymised due to GDPR
                regulations.
              format: int32
              example: 20
            total:
              type: integer
              description: Total number of records.
              format: int64
              example: 9000
          description: >-
            An object which contains pagination information related to the
            response.
        status:
          type: string
          description: Status of the HTTP response from the API.
          example: success
          enum:
            - success
            - fail
            - error
    Errors:
      type: object
      properties:
        code:
          type: string
          description: >-
            An application error code which can be used to resolve your error
            from Bandwidth's documentation.
          example: API-0207
        field:
          type: string
          description: The field which the error received relates to.
          example: from
        message:
          type: string
          description: A human-readable message providing more details about the error.
          example: Required Date parameter 'from' is not present.
    Quality:
      type: object
      properties:
        carrier:
          $ref: '#/components/schemas/QualityAttributes'
        customer:
          $ref: '#/components/schemas/QualityAttributes'
      description: >-
        Detailed call quality metrics split by Bandwidth (carrier) and customer
        termination point (customer).
    QualityAttributes:
      type: object
      properties:
        avgMos:
          type: string
          description: >-
            The average Mean Opinion Score between 1-5 used to predict the call
            quality. The MOS score will depend on Codec.
          example: '440'
        codec:
          type: string
          description: The delivery codec used for this call.
          example: G711µ
        jitter:
          type: string
          description: Variation in the delay of received packets measured in microseconds.
          example: '0.175'
        packetLoss:
          type: string
          description: >-
            A percentage for the number of packets that failed to reach their
            destination.
          example: '0.1'
        maxMos:
          type: string
          description: The maximum MOS score achieved on this call.
          example: '440'
        minMos:
          type: string
          description: The minimum MOS score determined on this call.
          example: '420'
        rtt:
          type: string
          description: The Round Trip Time or Post Dial Delay measured in milliseconds.
          example: '1'
    externalApiResponseErrorMessage:
      type: object
      properties:
        status:
          type: string
          description: Status of the HTTP response from the API.
          example: fail
          enum:
            - success
            - fail
            - error
        errors:
          type: array
          description: A collection of errors with detailed information.
          items:
            $ref: '#/components/schemas/Errors'
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
    forbiddenErrorResponseSchema:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
          example: 2022-05-19T09:25:20.991+0000
        status:
          type: number
          example: 403
        error:
          type: string
          example: Forbidden
        message:
          type: string
          example: Access Denied
        path:
          type: string
          example: /cdrs/calls
    internalServerErrorResponseSchema:
      type: object
      properties:
        globalMessages:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                example: ERROR
              code:
                type: string
                example: ERR-0999
              message:
                type: string
                example: >-
                  A system error occurred. Retry again later or contact Voxbone
                  support
  parameters:
    from:
      name: from
      in: query
      description: Start of period where CDRs will be retrieved from.
      required: true
      schema:
        type: string
        format: date-time
      example: 2020-03-04T12:00:00.000Z
    to:
      name: to
      in: query
      description: End of period where CDRs will be retrieved until.
      required: true
      schema:
        type: string
        format: date-time
      example: 2020-03-05T12:00:00.000Z
    id:
      name: id
      in: query
      description: UUID for this record.
      schema:
        type: string
      example: TTJE4M8N3P4N95FEDG3ANH8F98
    countryCodeA3:
      name: countryCodeA3
      in: query
      description: >-
        Indicates the country code of the DID in its ISO 3166-1 alpha-3 format
        (e.g. 'GBR' for United Kingdom, 'USA' for United States of America,
        'BEL' for Belgium, etc.).
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
          enum:
            - AFG
            - ALB
            - DZA
            - ASM
            - AND
            - AGO
            - AIA
            - ATA
            - ATG
            - ARG
            - ARM
            - ABW
            - AUT
            - AUS
            - AZE
            - BHS
            - BHR
            - BGD
            - BRB
            - BLR
            - BEL
            - BLZ
            - BEN
            - BMU
            - BTN
            - BOL
            - BIH
            - BWA
            - BRA
            - BGR
            - BFA
            - BDI
            - KHM
            - CMR
            - CAN
            - CPV
            - CYM
            - CAF
            - TCD
            - CHL
            - CHN
            - CXR
            - COL
            - COM
            - COD
            - COG
            - COK
            - CRI
            - CIV
            - HRV
            - CUB
            - CYP
            - CZE
            - DNK
            - DJI
            - DMA
            - DOM
            - ECU
            - EGY
            - SLV
            - GNQ
            - ERI
            - EST
            - ETH
            - FRO
            - FJI
            - FIN
            - FRA
            - GUF
            - PYF
            - GAB
            - GMB
            - GEO
            - DEU
            - GHA
            - GIB
            - GRC
            - GRL
            - GRD
            - GLP
            - GUM
            - GTM
            - GIN
            - GNB
            - GUY
            - HTI
            - HND
            - HKG
            - HUN
            - ISL
            - IND
            - IDN
            - IRN
            - IRQ
            - IRL
            - ISR
            - ITA
            - JAM
            - JPN
            - JOR
            - KAZ
            - KEN
            - KIR
            - PRK
            - KOR
            - KWT
            - KGZ
            - LAO
            - LVA
            - LBN
            - LSO
            - LBR
            - LBY
            - LIE
            - LTU
            - LUX
            - MAC
            - MKD
            - MDG
            - MWI
            - MYS
            - MDV
            - MLI
            - MLT
            - MHL
            - MTQ
            - MRT
            - MUS
            - MEX
            - MDA
            - MCO
            - MNG
            - MSR
            - MAR
            - MOZ
            - MMR
            - NAM
            - NRU
            - NPL
            - NLD
            - ANT
            - NCL
            - NZL
            - NIC
            - NER
            - NGA
            - NIU
            - NFK
            - MNP
            - NOR
            - OMN
            - PAK
            - PLW
            - PAN
            - PNG
            - PRY
            - PER
            - PHL
            - POL
            - PRT
            - PRI
            - QAT
            - REU
            - ROU
            - RUS
            - RWA
            - KNA
            - LCA
            - VCT
            - WSM
            - SMR
            - SAU
            - SEN
            - SYC
            - SLE
            - SGP
            - SVK
            - SVN
            - SLB
            - SOM
            - ZAF
            - ESP
            - LKA
            - SHN
            - SPM
            - SDN
            - SUR
            - SWZ
            - SWE
            - CHE
            - SYR
            - TWN
            - TJK
            - TZA
            - THA
            - TGO
            - TON
            - TTO
            - TUN
            - TUR
            - TKM
            - TCA
            - TUV
            - UGA
            - UKR
            - ARE
            - GBR
            - USA
            - UMI
            - URY
            - UZB
            - VUT
            - VAT
            - VEN
            - VNM
            - VGB
            - VIR
            - WLF
            - YEM
            - ZMB
            - ZWE
            - SXM
            - CUW
            - BES
            - WLD
            - SRB
            - MNE
            - UNK
            - SSD
    e164:
      name: e164
      in: query
      description: >-
        The DID in its E164 format (e.g. “+16469185038”) with the ability to
        provide multiple E164s.
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
    eventType:
      name: eventType
      in: query
      description: The type of CDR event.
      schema:
        type: string
        enum:
          - IN_VOICE_END
          - OUT_VOICE_END
      example: IN_VOICE_END
    callType:
      name: callType
      in: query
      description: The grouping for the type of DID.
      schema:
        type: string
        enum:
          - VOXDID
          - VOXPREMIUM
          - VOX800
      example: VOXDID
    offset:
      name: offset
      in: query
      description: >-
        Starting position in the dataset of a particular record where we
        retrieve a subset of records.
      schema:
        type: integer
        format: int32
        default: 0
      example: 20
    limit:
      name: limit
      in: query
      description: A limit on the number of records to be returned.
      schema:
        type: integer
        format: int32
        default: 20
    anonymized:
      name: anonymized
      in: query
      description: >-
        Mask the the last 3 digits of the destination number for OUTBOUND calls
        due to GDPR regulations.
      schema:
        type: boolean
      example: true
    direction:
      name: direction
      in: query
      description: Direction of the call.
      schema:
        type: string
        enum:
          - INBOUND
          - OUTBOUND
      example: INBOUND
    originationCountryCodeA3:
      name: originationCountryCodeA3
      in: query
      description: >
        Indicates the country code of origination country in its ISO 3166-1
        alpha-3 format (e.g. 'GBR' for United Kingdom, 'USA' for United States
        of America, 'BEL' for Belgium, etc.).


        Note: This filter is only available when direction is OUTBOUND.
      schema:
        type: array
        items:
          type: string
    destinationCountryCodeA3:
      name: destinationCountryCodeA3
      in: query
      description: >
        Indicates the country code of the destination country in its ISO 3166-1
        alpha-3 format (e.g. 'GBR' for United Kingdom, 'USA' for United States
        of America, 'BEL' for Belgium, etc.).


        Note: This filter is only available when direction is OUTBOUND.
      schema:
        type: array
        items:
          type: string
  responses:
    listCallsResponse:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/externalCdrResourceHolder'
    badRequestErrorResponse:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/externalApiResponseErrorMessage'
    forbiddenErrorResponse:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/forbiddenErrorResponseSchema'
          examples:
            forbiddenErrorExample:
              value:
                timestamp: 2022-05-19T09:25:20.991+0000
                status: 403
                error: Forbidden
                message: Access Denied
                path: /cdrs/calls
    notAllowedErrorResponse:
      description: Method Not Allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/externalApiResponseErrorMessage'
          examples:
            notAllowedErrorExample:
              value:
                status: fail
                errors:
                  - message: The method POST is not supported for this operation.
                    code: API-020
                links:
                  - rel: self
                    href: https://api.voxbone.com/cdrs/voice
    internalServerErrorResponse:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/internalServerErrorResponseSchema'
          examples:
            internalServerErrorExample:
              value:
                globalMessages:
                  - type: ERROR
                    code: ERR-0999
                    message: >-
                      A system error occurred. Retry again later or contact
                      Voxbone support
    paymentRequiredResponse:
      description: Payment Required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/externalApiResponseErrorMessage'
          examples:
            notAllowedErrorExample:
              value:
                status: fail
                errors:
                  - message: >-
                      Sorry you need to upgrade your CDR data retention to a
                      paid tier to get access to our API.
                    code: CDR-1015
                links:
                  - rel: self
                    href: https://api.voxbone.com/cdrs/voice
  securitySchemes:
    apiKey:
      type: apiKey
      description: >
        Authentication to Bandwidth's global API is handled via key based
        authentication.  You can manage your API key on our [Global
        Portal](https://www.bandwidth.com/login/) under **Settings > API**.


        For our CDR API, please use the apikey from your main Voxbone account.
        We will be enabling sub-account API access to CDRs in a future release.
      name: apikey
      in: header
security:
  - KeyBasedAuthentication: []
