openapi: 3.1.0
info:
  title: Global API V3
  version: 3.0.0
  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.|[Click
    here](https://dev.bandwidth.com/apis/legacy-apis/global/v2/)|

    |`v3`|Our Porting API in Limited Availability|Currently viewing|

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

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


    Bandwidth understands that number porting is a powerful tool that enables
    you to bring all your existing voice and text services under one umbrella.
    By porting-in your phone numbers to Bandwidth, you mitigate the disruption
    that comes from changing numbers.


    With our new 🚀 Number Porting API in Limited Availability 🚀, we are making
    the number porting process as smooth as possible! This allows you to check
    all existing porting orders for your account using available filters. For
    example, you can check the number or current status of your orders. 


    ## 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.


    ## Base URL 


    `https://api.voxbone.com/v3`
  contact:
    email: support@bandwidth.com
  termsOfService: https://www.bandwidth.com/legal/terms-of-use-bandwidthcom-web-sites/
servers:
  - url: https://api.voxbone.com/v3
paths:
  /porting/validator:
    post:
      summary: Check number portability.
      description: >-
        Check if a set of numbers is portable to Bandwidth. Bandwidth internally
        detects the number type, area code, and country code, and you can
        retrieve porting pricing fees and submission requirements.
      operationId: portabilityCheck
      requestBody:
        $ref: '#/components/requestBodies/portabilityCheckRequest'
      responses:
        '200':
          $ref: '#/components/responses/portabilityCheckSuccessResponse'
        '400':
          $ref: '#/components/responses/badRequestErrorResponse'
        '401':
          $ref: '#/components/responses/unauthorizedErrorResponse'
        '403':
          $ref: '#/components/responses/forbiddenErrorResponse'
        '405':
          $ref: '#/components/responses/notAllowedErrorResponse'
        '429':
          $ref: '#/components/responses/tooManyRequestsErrorResponse'
        '500':
          $ref: '#/components/responses/internalErrorResponse'
      tags:
        - Portability Checker
  /porting/portInOrders:
    post:
      summary: Create a draft port-in order.
      description: >-
        Allows you to create a porting order in a pending state without
        documents. These documents must be uploaded for this porting order to be
        processed successfully.


        All porting orders are created in a pending state and will be
        automatically cancelled after 30 days.
      operationId: createPortInOrder
      requestBody:
        $ref: '#/components/requestBodies/portInOrderCreationRequest'
      responses:
        '201':
          $ref: '#/components/responses/createdPortInOrderSuccessResponse'
        '400':
          $ref: '#/components/responses/badRequestErrorResponse'
        '401':
          $ref: '#/components/responses/unauthorizedErrorResponse'
        '403':
          $ref: '#/components/responses/forbiddenErrorResponse'
        '405':
          $ref: '#/components/responses/notAllowedErrorResponse'
        '429':
          $ref: '#/components/responses/tooManyRequestsErrorResponse'
        '500':
          $ref: '#/components/responses/internalErrorResponse'
      tags:
        - Port-In Orders
    patch:
      summary: Update the status of a port-in order.
      description: Allows you to update the status of a port-in order.
      operationId: updateStatusPortInOrder
      requestBody:
        $ref: '#/components/requestBodies/portInOrderRequest'
      responses:
        '200':
          $ref: '#/components/responses/returnPortInOrderSuccessResponse'
        '400':
          $ref: '#/components/responses/badRequestErrorResponse'
        '401':
          $ref: '#/components/responses/unauthorizedErrorResponse'
        '403':
          $ref: '#/components/responses/forbiddenErrorResponse'
        '404':
          $ref: '#/components/responses/notFoundErrorResponse'
        '405':
          $ref: '#/components/responses/notAllowedErrorResponse'
        '409':
          $ref: '#/components/responses/conflictErrorResponse'
        '429':
          $ref: '#/components/responses/tooManyRequestsErrorResponse'
        '500':
          $ref: '#/components/responses/internalErrorResponse'
      tags:
        - Port-In Orders
  /porting/{portInOrderId}/documents:
    parameters:
      - $ref: '#/components/parameters/portInOrderId'
    post:
      summary: Upload documents to a draft port-in order.
      description: >-
        You are required to upload all the relevant documents for your existing
        port-in order to be successful depending on the number you are trying to
        port and which country the number belongs to. You can see the required
        documents by checking a number's portability requirements.


        The endpoint can only support 1 file per document type, and up to 20Mb. 
      operationId: uploadPortInDocuments
      requestBody:
        $ref: '#/components/requestBodies/documentUploadRequest'
      responses:
        '201':
          $ref: '#/components/responses/documentUploadSuccessResponse'
        '400':
          $ref: '#/components/responses/badRequestErrorResponse'
        '401':
          $ref: '#/components/responses/unauthorizedErrorResponse'
        '403':
          $ref: '#/components/responses/forbiddenErrorResponse'
        '404':
          $ref: '#/components/responses/notFoundErrorResponse'
        '405':
          $ref: '#/components/responses/notAllowedErrorResponse'
        '429':
          $ref: '#/components/responses/tooManyRequestsErrorResponse'
        '500':
          $ref: '#/components/responses/internalErrorResponse'
      tags:
        - Port-In Order Document
components:
  schemas:
    portInOrder:
      description: Port-in order details for a number or a set of numbers.
      type: object
      properties:
        portInOrderId:
          type: integer
          description: ID automatically generated when you create a port-in order.
          example: 293895
        supportRef:
          type: string
          description: >-
            Reference of a port order - to use when you contact our support or
            our porting teams. Eg: PRT25168668606830
          example: PRT293895686064690
        supportTicket:
          $ref: '#/components/schemas/supportTicket'
        numbersToPort:
          type: array
          minItems: 1
          maxItems: 499
          description: Array of numbers in E.164 format.
          items:
            $ref: '#/components/schemas/phoneNumberDetails'
        customerReference:
          type: string
          minLength: 1
          maxLength: 32
          description: >-
            Parameter that can be used for your own reference, e.g. to uniquely
            identify one of your customers.
          example: ABC-12345
        currentProviderName:
          type: string
          minLength: 1
          description: >-
            The losing carrier who's currently the operator on the number to be
            ported in.
          example: Verizon
        numbersOwner:
          $ref: '#/components/schemas/numbersOwner'
        preferredPortInDate:
          type: string
          minLength: 1
          format: date
          description: >-
            Specific date you would prefer the port-into be completed, in RFC
            3339 format.
          example: '2022-03-10'
        plannedDate:
          type: string
          minLength: 1
          format: date
          description: >-
            Date when the port is planned, in RFC 3339 format. This date is only
            present when the port is confirmed.
          example: '2022-03-10'
        createdTimestamp:
          type: string
          format: date-time
          description: Creation date of the port-in order, in RFC 3339 format.
          example: '2022-01-10T17:32:28Z'
        lastUpdateTimestamp:
          type: string
          format: date-time
          description: Last update date of the port-in order, in RFC 3339 format.
          example: '2022-01-15T17:32:28Z'
        submittedTimestamp:
          type: string
          format: date-time
          description: >-
            Date representing when the order was submitted - only present when
            relevant, in RFC 3339 format.
          example: '2022-02-10T17:32:28Z'
        status:
          $ref: '#/components/schemas/portInOrderStatusTypeEnum'
        documents:
          type: array
          description: >-
            Required documents for a port-in order. This object is not present
            when you have just created a port-in order.
          items:
            $ref: '#/components/schemas/document'
        fees:
          $ref: '#/components/schemas/fees'
      required:
        - numbersToPort
        - currentProviderName
        - numbersOwner
    numbersOwner:
      description: Owner of the numbers.
      type: object
      examples:
        - numberUsageType: BUSINESS
          complementaryAddressInformation: In attention to Mr. Smith
          buildingNumber: '489'
          streetName: Rue Vanderkindere
          city: Brussels
          countryCodeA3: BEL
          postalCode: '1050'
          companyName: Voxbone
          companyVatNumber: BE0478928788
      properties:
        numberUsageType:
          $ref: '#/components/schemas/phoneNumberUsageTypeEnum'
        complementaryAddressInformation:
          type: string
          description: Is used to indicate "In attention to someone."
          example: Chez J. Jones
        floor:
          type: number
          description: Floor number of the end user's address.
          example: 35
        buildingIdentifier:
          type: string
          description: Building number for the end user's address. E.g. Can put 54 or 54A.
          example: 54A
        buildingName:
          type: string
          description: Building name for the end user's address.
          example: Flora House
        streetName:
          type: string
          description: Street name for the end user's address.
          example: Folgate Street
        streetIdentifier:
          type: string
          description: Street code for the end user's address. E.g. addresses in Japan
          example: 12A
        postalCode:
          type: string
          description: Postal code for the end user's address.
          example: E1 6BX
        municipalityIdentifier:
          type: string
          description: >-
            Municipality code for the end user's address. E.g. 50026 for Pisa in
            Italia.
          example: '50026'
        city:
          type: string
          minLength: 1
          description: City name for the end user's address.
          example: Pisa
        state:
          type: string
          description: State of the end user's address.
          example: Tuscany
        countryCodeA3:
          type: string
          pattern: ^[A-Z]{3}$
          description: ISO 3166-1 standard 3-letter country code.
          example: ITA
        title:
          $ref: '#/components/schemas/salutationTypeEnum'
        firstName:
          type: string
          minLength: 1
          description: First name of personal end user or company legal representative.
          example: Henry
        middleName:
          type: string
          minLength: 1
          description: >-
            Middle name of the personal end user or company legal
            representative.
          example: J.
        lastName:
          type: string
          minLength: 1
          description: Surname of personal end user or company legal representative.
          example: Jones
        dateOfBirth:
          type: string
          formmat: date
          minLength: 1
          description: >-
            Date of birth of personal end user or company legal representative,
            in RFC 3339 format.
          example: '1980-01-10'
        companyName:
          type: string
          minLength: 1
          description: Registered company name. Only present for business numberUsageType.
          example: Acme Corporation
        companyVatNumber:
          type: string
          minLength: 1
          description: Registered VAT number - only present for business numberUsageType.
          example: '10001'
        companyRegistrationNumber:
          type: string
          minLength: 1
          description: Registration number - only present for business numberUsageType.
          example: E14587
        mailBox:
          $ref: '#/components/schemas/mailBox'
      required:
        - numberUsageType
        - city
        - countryCodeA3
        - title
    mailBox:
      description: Virtual or physical mailbox of the owner of the number.
      type: object
      properties:
        buildingIdentifier:
          type: string
          description: Building number for the end user's mailbox. E.g. Can put 54 or 54A.
          example: '45'
        buildingName:
          type: string
          description: Building name for the end user's mailbox.
          example: Buildng A
        complementaryAddressInformation:
          type: string
          description: Is used to indicate "In attention to someone."
          example: Central park
        streetName:
          type: string
          description: Street name for the end user's mailbox.
          example: High street
        streetIdentifier:
          type: string
          description: Street code for the end user's mailbox. E.g. addresses in Japan
          example: R24
        postalCode:
          type: string
          description: Postal code for the end user's mailbox.
          example: E14 3GE
        municipalityIdentifier:
          type: string
          description: >-
            Municipality code for the end user's mailbox. E.g. 50026 for Pisa in
            Italia.
          example: '1145'
        city:
          type: string
          description: City name for the end user's mailbox.
          minLength: 1
          example: London
        state:
          type: string
          description: State of the end user's mailbox.
          example: Greater London
        countryCodeA3:
          type: string
          description: ISO 3166-1 standard 3-letter country code.
          minLength: 3
          maxLength: 3
          example: GBR
    phoneNumberDetails:
      description: Telephone numbers to port and related porting details.
      type: object
      properties:
        phoneNumber:
          type: string
          minLenth: 1
          maxLenth: 15
          pattern: ^\+?[1-9]\d{1,14}$
          description: >-
            Phone number in E.164 format that the portability check response is
            executed against. E.g: +19995550123, +33123456789.
          example: '+3228090001'
        phoneNumberType:
          $ref: '#/components/schemas/phoneNumberTypeEnum'
        countryCodeA3:
          $ref: '#/components/schemas/countryCodeA3'
        countryCallingCode:
          type: string
          description: Country calling code. E.g. 44 for UK
          example: '33'
        areaCode:
          type: string
          description: Phone area code. Can be empty for mobile phone numbers.
          example: '3'
        leadTime:
          type: number
          description: >-
            Amount of days it takes to complete a order in a happy flow from the
            moment of submission.
          example: 10
        internalMigration:
          type: boolean
          description: >-
            Indicates if the number is already in our network and we only need
            to move the number to your account.
        portable:
          type: boolean
          description: Indicates if the number is portable.
        notPortableReason:
          $ref: '#/components/schemas/error'
    fees:
      description: >-
        Fees that you have to pay for a number or a set of numbers. The currency
        will depend on your configuration.
      type: object
      examples:
        - portFees: 1
          cancellationFees: 2.3
          phoneNumberMonthlyFees: 5.7
      properties:
        portFees:
          type: number
          description: Fees for porting-in a number or a set of numbers.
          example: 3.5
        cancellationFees:
          type: number
          description: Cancellation fees for a submitted number or a set of numbers.
          example: 1.5
        phoneNumberMonthlyFees:
          type: number
          description: Monthly recurring charge for owning a number or a set of numbers.
          example: 0.16
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          description: Currency of port-in fees, in ISO-4217 format.
          example: EUR
      required:
        - portFees
        - cancellationFees
        - phoneNumberMonthlyFees
    link:
      description: >-
        All actions that you can do for a port-in order, document, support
        ticket, or a comment in a support ticket.
      type: object
      examples:
        - rel: CANCEL
          href: https://api.voxbone.com/v3/porting/251593
          type: DELETE
      properties:
        rel:
          $ref: '#/components/schemas/relTypeEnum'
          minLength: 1
        href:
          type: string
          minLength: 1
          format: uri
          description: Url to perform the action.
          example: http://api.voxbone.com/v3/porting/292021/documents/560731
        type:
          $ref: '#/components/schemas/linkTypeEnum'
      required:
        - rel
        - href
        - type
    document:
      description: Required documents for porting-in a number or a set of numbers.
      type: object
      examples:
        - type: LOA
          description: Letter of authority
          status: PENDING_VALIDATION
          documentId: 255005
      properties:
        documentId:
          type: integer
          description: Generated ID for an uploaded document.
          example: 560731
        type:
          $ref: '#/components/schemas/documentTypeEnum'
        description:
          type: string
          minLength: 1
          description: Description of a document.
          example: Last invoice
        status:
          $ref: '#/components/schemas/documentStatusTypeEnum'
        link:
          $ref: '#/components/schemas/link'
      required:
        - type
    comment:
      type: object
      examples:
        - id: R6776898
          dateCreated: '2021-11-20'
          description: >-
            Hi there, The cancellation request for your port has been
            successfully processed.
      description: Comments from porting team.
      properties:
        id:
          type: string
          description: Id of the comment.
          example: '5607334564'
        dateCreated:
          type: string
          description: Created date of the comment.
          format: date-time
          example: '2022-02-10T17:32:28Z'
        description:
          type: string
          description: Description of the comment.
          example: >-
            Last invoice document is not readable - please upload a new one for
            continuing the porting process.
      required:
        - id
        - dateCreated
        - description
    supportTicket:
      type: object
      examples:
        - link:
            rel: SELF
            href: https://support.voxbone.com/hc/en-us/requests/295782
            type: GET
          comments:
            - id: R6776898
              dateCreated: '2021-11-20'
              description: >-
                Hi there, The cancellation request for your port has been
                successfully processed.
      description: Support ticket associated to the port-in order.
      properties:
        link:
          $ref: '#/components/schemas/link'
        comment:
          $ref: '#/components/schemas/comment'
    requirement:
      type: object
      description: >-
        Required information and documents that you have to provide in order to
        port your numbers.
      properties:
        countryCodeA3:
          $ref: '#/components/schemas/countryCodeA3'
        phoneNumberType:
          $ref: '#/components/schemas/phoneNumberTypeEnum'
        business:
          $ref: '#/components/schemas/businessRequirement'
        personal:
          $ref: '#/components/schemas/personalRequirement'
    businessRequirement:
      description: >-
        All required documents and end user's information that you have to
        provide for porting-in a number.
      type: object
      properties:
        documents:
          type: array
          uniqueItems: true
          minItems: 1
          description: Required documents.
          items:
            $ref: '#/components/schemas/documentRequirement'
    personalRequirement:
      description: >-
        All requirements (documents and end user's information) customers have
        to provide for porting-in a number.
      type: object
      properties:
        documents:
          type: array
          uniqueItems: true
          minItems: 1
          description: Required documents.
          items:
            $ref: '#/components/schemas/documentRequirement'
    documentRequirement:
      description: Documents that you have to provide for porting-in a number.
      type: object
      properties:
        type:
          $ref: '#/components/schemas/documentTypeEnum'
        description:
          type: string
          minLength: 1
          description: Description of documents.
          example: LOA
        supportedFileTypes:
          type: array
          description: Supported file extensions.
          items:
            type: string
            example: .pdf
            enum:
              - .pdf
              - .xls
              - .xlsx
              - .jpg
              - .jpeg
      required:
        - type
        - description
        - supportedFileTypes
    error:
      description: Generic error.
      type: object
      examples:
        - source:
            field: numberToPort
          description: 'Invalid phone number: jnk'
          code: XXX-XXXX
      properties:
        description:
          type: string
          minLength: 1
          description: Description of the issue.
          example: Missing mandatory parameters.
        code:
          type: string
          minLength: 1
          description: Error code.
          example: PRT-7001
        source:
          type: object
          description: Contains references to the source of the error.
          properties:
            field:
              type: string
              minLength: 1
              description: Missing field or field having the issue.
              example: documentType
      required:
        - description
    pagination:
      type: object
      description: Pagination of port-in orders.
      properties:
        links:
          description: >-
            Represents going to the “next” page. This parameter will be absent
            if there isn't any next pagination.
          type: array
          items:
            $ref: '#/components/schemas/link'
    salutationTypeEnum:
      type: string
      enum:
        - MR
        - MS
        - COMPANY
      description: >-
        Salutation of the end user or company legal representative. Use
        "COMPANY" if the numbers that you want to port belong to a company.
      example: MR
    documentTypeEnum:
      type: string
      enum:
        - ALLO
        - CAN
        - COB
        - COURT
        - CSR
        - DIREC
        - FORM
        - INCORP
        - LEG_ID
        - LOA
        - OFF_SGN
        - POA
        - TAX
      description: >
        Types of documents.

        **The table below defines types of documents.**


        | Type of document      | Description  |

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

        | ALLO        | A local allocation letter / Bakom Ownership Letter /
        BNetZa Allocation Certificate. | 

        | CAN         | A cancellation notice. | 

        | COB         | Last invoice. |

        | COURT       | Copy of Court Registration. |

        | CSR         | A customer service record. |

        | DIREC       | Copy of Certificate of Directors and Secretary of the
        company. | 

        | FORM        | A local regulated porting form. | 

        | INCORP      | Copy of Certificate of Incorporation / Company
        Registration Certificate. | 

        | LEG_ID      | Copy of legal representative's photo ID. |

        | LOA         | A letter of authority. |

        | OFF_SGN     | Official proof of signature. |

        | POA         | Copy of power of attorney. |

        | TAX         | Copy of the registration at the tax office. |
      example: LOA
    phoneNumberTypeEnum:
      type: string
      enum:
        - NATIONAL
        - GEOGRAPHIC
        - MOBILE
        - SHARED_COST
        - TOLL_FREE
        - SPECIAL
      description: >
        This is the list of supported phone number types:


        - National numbers: is a phone number designated to be reachable from
        the entire country at the same price anywhere in the country as a local
        phone call.

        - Geographic number: is a fixed-line telephone numbers beginning with a
        geographically assigned area code.

        - Mobile number: a telephone number which is registered to a mobile
        phone/mobile network.

        - Shared cost number: is a premium number in the UK, Australia, Germany,
        Switzerland, France, Portugal and the Netherlands, often used by
        businesses and other institutions.

        - Toll-free number: is a telephone number that is billed for all
        arriving calls. For the calling party, a call to a toll-free number from
        a landline is free of charge.

        - Special number: is a telephone number that can be used by a business
        as contact numbers for a number of reasons, including improving the
        callers experience through the use of network intelligent routing of
        calls (call recording, calls being automatically delivered to the
        nearest office, etc,), sharing the cost paid by the caller.
      example: GEOGRAPHIC
    phoneNumberUsageTypeEnum:
      type: string
      description: List of supported usage types.
      example: BUSINESS
      enum:
        - PERSONAL
        - BUSINESS
    linkTypeEnum:
      type: string
      enum:
        - GET
        - DELETE
        - PATCH
      description: Type of link.
      example: GET
    relTypeEnum:
      type: string
      enum:
        - SELF
        - LAST
        - FIRST
        - PREV
        - NEXT
        - SUPPORT
        - CANCEL
        - DOWNLOAD
      description: Reference of the action.
      example: SELF
    portInOrderStatusTypeEnum:
      type: string
      enum:
        - DRAFT
        - SUBMITTED
        - MISSING_DATA
        - PENDING_CARRIER_APPROVAL
        - ACCEPTED_BY_CARRIER
        - READY_FOR_CONFIGURATION
        - COMPLETED
        - REJECTED
        - PROCESSING_CANCELLATION
        - CANCELED
      description: >
        Possible statuses of a port-in order


        | Status                    | Description  |

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

        | DRAFT                     | Your port-in order has been created, but
        not yet submitted. You can change the content of the order or delete it
        anytime. |

        | SUBMITTED                 | Your port-in order has been submitted, and
        our LNP team will take care of it shortly. If you need to change your
        order, you will need  to request a cancellation or ask our LNP team to
        return your order. |

        | MISSING_DATA              | Your port-in order has been returned by
        our LNP team  because the order doesn't contain the required information
        ( you may be missing data or the document). Your order needs to be
        amended and resubmitted. |

        | PENDING_CARRIER_APPROVAL  | Your port-in order has been transmitted to
        our carrier. |

        | ACCEPTED_BY_CARRIER       | Good news! Your port-in has been accepted
        by our carrier. |

        | READY_FOR_CONFIGURATION   | Your numbers are ready for configuration.
        You can now assign your configuration profile to your order. |

        | COMPLETED                 | Your port-in order is complete. |

        | REJECTED                  | Your port-in order has been rejected by
        our LNP team/carrier. Please contact our LNP team for further details. |

        | PROCESSING_CANCELLATION   | You are requesting the cancellation of
        your order. Our LNP team will get back to you shortly|

        | CANCELED                  | Your port-in order has been canceled. |
      example: DRAFT
    portInOrderRequestStatusTypeEnum:
      type: string
      enum:
        - SUBMITTED
        - PROCESSING_CANCELLATION
      description: >
        Possible statuses of a port-in order


        | Status                    | Description  |

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

        | SUBMITTED                 | Your port-in order has been submitted, and
        our LNP team will take care of it shortly. If you need to change your
        order, you will need  to request a cancellation or ask our LNP team to
        return your order. |

        | PROCESSING_CANCELLATION   | You are requesting the cancellation of
        your order. Our LNP team will get back to you shortly|
      example: SUBMITTED
    documentStatusTypeEnum:
      type: string
      enum:
        - PENDING_VALIDATION
        - VALID
        - INVALID
      description: >-
        Status of a document - any new uploaded document will be marked as
        PENDING_VALIDATION and will need to be validated by our porting team.
      example: PENDING_VALIDATION
    countryCodeA3:
      type: string
      minLength: 3
      maxLength: 3
      description: ISO 3166-1 standard 3-letter country code.
      example: ITA
  responses:
    createdPortInOrderSuccessResponse:
      description: Created
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  portIn:
                    $ref: '#/components/schemas/portInOrder'
              links:
                type: array
                items:
                  $ref: '#/components/schemas/link'
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/error'
          examples:
            createOrderSuccessResponse:
              $ref: '#/components/examples/createOrderSuccessResponse'
            requestCancellationSuccessResponse:
              $ref: >-
                #/components/examples/requestCancellationPortInOrderSuccessResponse
            submitOrderSuccessResponse:
              $ref: '#/components/examples/submitPortInOrderSucessResponse'
    returnPortInOrderSuccessResponse:
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  portIn:
                    $ref: '#/components/schemas/portInOrder'
              links:
                type: array
                items:
                  $ref: '#/components/schemas/link'
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/error'
          examples:
            createOrderSuccessResponse:
              $ref: '#/components/examples/createOrderSuccessResponse'
            requestCancellationSuccessResponse:
              $ref: >-
                #/components/examples/requestCancellationPortInOrderSuccessResponse
            submitOrderSuccessResponse:
              $ref: '#/components/examples/submitPortInOrderSucessResponse'
    portInOrderArraySuccessResponse:
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                pagination:
                  $ref: '#/components/schemas/pagination'
                properties:
                  portIns:
                    type: array
                    description: All port-in orders.
                    items:
                      $ref: '#/components/schemas/portInOrder'
                  totalElements:
                    type: integer
                    description: Number of port-in orders in total.
                  totalPages:
                    type: integer
                    description: Number of pages in total.
              links:
                type: array
                items:
                  $ref: '#/components/schemas/link'
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/error'
    documentUploadSuccessResponse:
      description: Created
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  documents:
                    type: array
                    description: Array of documents.
                    items:
                      $ref: '#/components/schemas/document'
              links:
                type: array
                items:
                  $ref: '#/components/schemas/link'
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/error'
          examples:
            uploadDocumentSuccessResponse:
              $ref: '#/components/examples/uploadDocumentsSuccessResponse'
    documentDownloadSuccessResponse:
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  document:
                    $ref: '#/components/schemas/document'
              links:
                type: array
                description: >-
                  Indicates all actions you can do with this port-in order based
                  on its status.
                items:
                  $ref: '#/components/schemas/link'
          examples: {}
    portabilityCheckSuccessResponse:
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  requirements:
                    type: array
                    description: >-
                      All required information and documents needed to port the
                      requested numbers.
                    items:
                      $ref: '#/components/schemas/requirement'
                  numbersToPort:
                    type: array
                    description: >-
                      The list of phone numbers included in the portability
                      request.
                    items:
                      $ref: '#/components/schemas/phoneNumberDetails'
          examples:
            checkPortabilitySuccessResponse:
              $ref: '#/components/examples/checkPortabilitySuccessResponse'
    badRequestErrorResponse:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/error'
              links:
                type: array
                items:
                  $ref: '#/components/schemas/link'
          examples:
            genericError400Example:
              value:
                data: {}
                errors:
                  - code: PRT-0499
                    description: 'The maximum size is: 500'
                    source:
                      field: numberToPort
                links: []
    unauthorizedErrorResponse:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/error'
              links:
                type: array
                items:
                  $ref: '#/components/schemas/link'
              status:
                type: string
    forbiddenErrorResponse:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              properties:
                timestamp:
                  type: string
                  format: date-time
                status:
                  type: number
                error:
                  type: string
                message:
                  type: string
                path:
                  type: string
          examples:
            genericError403Example:
              value:
                timestamp: 2022-05-19T09:25:20.991+0000
                status: 403
                error: Forbidden
                message: Access Denied
                path: /external/ports/validation
    notFoundErrorResponse:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/error'
              links:
                type: array
                items:
                  $ref: '#/components/schemas/link'
              status:
                type: string
    conflictErrorResponse:
      description: Conflict
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/error'
              links:
                type: array
                items:
                  $ref: '#/components/schemas/link'
          examples:
            genericError409Example:
              value:
                data: {}
                errors:
                  - description: >-
                      You can only submit port-in orders that are in DRAFT or
                      MISSING_DATA status. Please reach out to our customer
                      support team if you need help.
                    code: PRT-7720
                links: []
    notAllowedErrorResponse:
      description: Method Not Allowed
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/error'
              links:
                type: array
                items:
                  $ref: '#/components/schemas/link'
          examples:
            genericError405Example:
              value:
                data: {}
                errors:
                  - description: This operation is not allowed.
                    code: NOT_ALLOWED
                links: []
    tooManyRequestsErrorResponse:
      description: Too Many Requests
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/error'
              links:
                type: array
                items:
                  $ref: '#/components/schemas/link'
          examples:
            genericError429Example:
              value:
                data: {}
                errors:
                  - description: Too many requests.
                    code: TOO_MANY_REQUEST
                links: []
    internalErrorResponse:
      description: Internal Server Error
      content:
        application/json:
          schema:
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/error'
  requestBodies:
    portInOrderRequest:
      content:
        application/json:
          schema:
            description: Data model for request body.
            type: object
            properties:
              status:
                $ref: '#/components/schemas/portInOrderRequestStatusTypeEnum'
              numbersOwner:
                $ref: '#/components/schemas/numbersOwner'
              currentProviderName:
                type: string
                minLength: 1
                description: >-
                  The losing carrier who's currently the operator on the number
                  to be ported in.
                example: BT
              preferredPortInDate:
                type: string
                minLength: 1
                format: date
                description: >-
                  Date that you prefer to have numbers become available in
                  Bandwidth, must be in RFC 3339 format.
                example: '2022-03-10'
              phoneNumbers:
                type: array
                description: Array of telephone numbers in E.164 format.
                items:
                  type: string
                  example: '["+32498914698","+3228090001"]'
          examples:
            requestCancellationRequest:
              $ref: '#/components/examples/requestCancellationPortInOrderRequest'
            submitOrderRequest:
              $ref: '#/components/examples/submitPortInOrderRequest'
      description: General port-in order request.
    documentUploadRequest:
      content:
        multipart/form-data:
          schema:
            type: object
            properties:
              documentType:
                $ref: '#/components/schemas/documentTypeEnum'
              documentContent:
                type: string
                format: binary
    portInOrderCreationRequest:
      content:
        application/json:
          schema:
            description: Request body.
            type: object
            properties:
              numbersOwner:
                $ref: '#/components/schemas/numbersOwner'
              preferredPortInDate:
                type: string
                minLength: 1
                format: date
                description: >-
                  Date that you prefer to have numbers become available in
                  Bandwidth, must be in RFC 3339 format.
                example: '2022-03-10'
              customerReference:
                type: string
                minLength: 1
                maxLength: 32
                description: >-
                  Parameter that can be used for your own reference, e.g. to
                  uniquely identify one of your customers.
                example: ABC-123
              currentProviderName:
                type: string
                minLength: 1
                description: >-
                  The losing carrier who's currently the operator on the number
                  to be ported in.
                example: BT
              phoneNumbers:
                type: array
                description: Array of telephone numbers in E.164 format.
                items:
                  type: string
                  example: '["+32498914698","+3228090001"]'
            required:
              - numbersOwner
              - currentProviderName
              - phoneNumbers
          examples:
            createOrderRequest:
              $ref: '#/components/examples/createOrderRequest'
    portabilityCheckRequest:
      content:
        application/json:
          schema:
            type: object
            properties:
              phoneNumbers:
                type: array
                description: Array of telephone numbers in E.164 format.
                items:
                  type: string
                  minLength: 1
                  maxLength: 500
                  example: '+33123456789'
            required:
              - phoneNumbers
          examples:
            checkPortabilityRequest:
              $ref: '#/components/examples/checkPortabilityRequest'
  examples:
    checkPortabilityRequest:
      summary: Check portability request.
      value:
        phoneNumbers:
          - '+32498914698'
          - '+3228090001'
    checkPortabilitySuccessResponse:
      summary: Check portability success response.
      value:
        data:
          requirements:
            - countryCodeA3: FRA
              phoneNumberType: GEOGRAPHIC
              business:
                documents:
                  - type: COB
                    description: Last Invoice
                    supportedFileTypes:
                      - .pdf
              personal:
                documents:
                  - type: LOA
                    description: LOA
                    supportedFileTypes:
                      - .pdf
          numbersToPort:
            - phoneNumber: '+3228090001'
              phoneNumberType: GEOGRAPHIC
              countryCodeA3: BEL
              countryCallingCode: '32'
              areaCode: '3'
              leadTime: 10
              internalMigration: true
              portable: true
            - phoneNumber: '+3228090002'
              phoneNumberType: GEOGRAPHIC
              countryCodeA3: BEL
              countryCallingCode: '32'
              areaCode: '3'
              leadTime: 10
              internalMigration: true
              portable: false
              notPortableReason:
                source:
                  field: numberToPort
                description: 'Invalid phone number: jnk'
                code: XXX-XXXX
    createOrderRequest:
      summary: Create a draft port-in order request
      value:
        currentProviderName: BT
        phoneNumbers:
          - '+3228090000'
          - '+3228090001'
        preferredPortInDate: '2021-11-19'
        customerReference: P345679078
        numbersOwner:
          buildingIdentifier: '489'
          city: Brussels
          companyName: Voxbone
          countryCodeA3: BEL
          numberUsageType: BUSINESS
          postalCode: '1050'
          streetName: Rue Vanderkindere
          companyVatNumber: BE0478928788
          title: COMPANY
    createOrderSuccessResponse:
      value:
        data:
          portIn:
            portInOrderId: 293895
            supportRef: PRT293895686064690
            supportTicket:
              link:
                rel: SELF
                href: https://support.voxbone.com/hc/en-us/requests/295782
                type: GET
            numbersToPort:
              - phoneNumber: '+3228090001'
                phoneNumberType: GEOGRAPHIC
                countryCodeA3: BEL
                countryCallingCode: '32'
                areaCode: '3'
                leadTime: 10
                internalMigration: true
                portable: true
            customerReference: ABC-12345
            currentProviderName: Verizon
            numbersOwner:
              numberUsageType: BUSINESS
              complementaryAddressInformation: In attention to Mr. Smith
              buildingIdentifier: '489'
              streetName: Rue Vanderkindere
              city: Brussels
              countryCodeA3: BEL
              postalCode: '1050'
              companyName: Voxbone
              companyVatNumber: BE0478928788
              title: COMPANY
            preferredPortInDate: '2022-03-10'
            createdTimestamp: '2022-01-10T17:32:28Z'
            lastUpdateTimestamp: '2022-01-15T17:32:28Z'
            submittedTimestamp: '2022-02-10T17:32:28Z'
            status: DRAFT
            fees:
              portFees: 1
              cancellationFees: 2.3
              phoneNumberMonthlyFees: 5.7
              currency: EUR
        links:
          - rel: SELF
            href: https://api.voxbone.com/v3/porting/251593
            type: GET
          - rel: CANCEL
            href: https://api.voxbone.com/v3/porting/251593
            type: DELETE
          - rel: SUPPORT
            href: https://support.voxbone.com/hc/en-us/requests/295782
            type: GET
        errors: []
    returnOrderSuccessResponse:
      value:
        data:
          portIn:
            portInOrderId: 293895
            supportRef: PRT293895686064690
            supportTicket:
              link:
                rel: SELF
                href: https://support.voxbone.com/hc/en-us/requests/295782
                type: GET
            numbersToPort:
              - phoneNumber: '+3228090001'
                phoneNumberType: GEOGRAPHIC
                countryCodeA3: BEL
                countryCallingCode: '32'
                areaCode: '3'
                leadTime: 10
                internalMigration: true
                portable: true
            customerReference: ABC-12345
            currentProviderName: Verizon
            numbersOwner:
              numberUsageType: BUSINESS
              complementaryAddressInformation: In attention to Mr. Smith
              buildingNumber: '489'
              streetName: Rue Vanderkindere
              city: Brussels
              countryCodeA3: BEL
              postalCode: '1050'
              companyName: Voxbone
              companyVatNumber: BE0478928788
              title: COMPANY
            preferredPortInDate: '2022-03-10'
            createdTimestamp: '2022-01-10T17:32:28Z'
            lastUpdateTimestamp: '2022-01-15T17:32:28Z'
            submittedTimestamp: '2022-02-10T17:32:28Z'
            status: DRAFT
            fees:
              portFees: 1
              cancellationFees: 2.3
              phoneNumberMonthlyFees: 5.7
              currency: EUR
        links:
          - rel: SELF
            href: https://api.voxbone.com/v3/porting/251593
            type: GET
          - rel: CANCEL
            href: https://api.voxbone.com/v3/porting/251593
            type: DELETE
          - rel: SUPPORT
            href: https://support.voxbone.com/hc/en-us/requests/295782
            type: GET
        errors: []
    requestCancellationPortInOrderRequest:
      value:
        status: PROCESSING_CANCELLATION
    requestCancellationPortInOrderSuccessResponse:
      value:
        data:
          portIn:
            portInOrderId: 293895
            currentProviderName: Verizon
            numbersToPort:
              - phoneNumber: '+3228090001'
                phoneNumberType: GEOGRAPHIC
                countryCodeA3: BEL
                countryCallingCode: '32'
                areaCode: '3'
                leadTime: 10
                internalMigration: true
                portable: true
            numbersOwner:
              numberUsageType: BUSINESS
              complementaryAddressInformation: In attention to Mr. Smith
              buildingNumber: '489'
              streetName: Rue Vanderkindere
              city: Brussels
              countryCodeA3: BEL
              postalCode: '1050'
              companyName: Voxbone
              companyVatNumber: BE0478928788
              title: COMPANY
            customerReference: ABC-12345
            supportRef: PRT293895686064690
            supportTicket:
              link:
                rel: SELF
                href: https://support.voxbone.com/hc/en-us/requests/295782
                type: GET
            status: PROCESSING_CANCELLATION
            preferredPortInDate: '2022-03-10'
            createdTimestamp: '2022-01-10T17:32:28Z'
            lastUpdateTimestamp: '2022-01-15T17:32:28Z'
            submittedTimestamp: '2022-02-10T17:32:28Z'
            documents:
              - type: LOA
                description: Letter of authority
                status: PENDING_VALIDATION
                documentId: 255005
            fees:
              portFees: 1
              cancellationFees: 2.3
              phoneNumberMonthlyFees: 5.7
              currency: EUR
        links:
          - rel: CANCEL
            href: https://api.voxbone.com/v3/porting/251593
            type: PATCH
          - rel: SUPPORT
            href: https://support.voxbone.com/hc/en-us/requests/295782
            type: GET
    submitPortInOrderRequest:
      value:
        status: SUBMITTED
    submitPortInOrderSucessResponse:
      value:
        data:
          portIn:
            portInOrderId: 293895
            currentProviderName: Verizon
            numbersToPort:
              - phoneNumber: '+3228090001'
                phoneNumberType: GEOGRAPHIC
                countryCodeA3: BEL
                countryCallingCode: '32'
                areaCode: '3'
                leadTime: 10
                internalMigration: true
                portable: true
                notPortableReason:
                  source:
                    field: numberToPort
                  description: 'Invalid phone number: jnk'
                  code: XXX-XXXX
            numbersOwner:
              numberUsageType: BUSINESS
              complementaryAddressInformation: In attention to Mr. Smith
              buildingNumber: '489'
              streetName: Rue Vanderkindere
              city: Brussels
              countryCodeA3: BEL
              postalCode: '1050'
              companyName: Voxbone
              companyVatNumber: BE0478928788
              title: COMPANY
            customerReference: ABC-12345
            supportRef: PRT293895686064690
            supportTicket:
              link:
                rel: SELF
                href: https://support.voxbone.com/hc/en-us/requests/295782
                type: GET
            status: SUBMITTED
            preferredPortInDate: '2022-03-10'
            createdTimestamp: '2022-01-10T17:32:28Z'
            lastUpdateTimestamp: '2022-01-15T17:32:28Z'
            submittedTimestamp: '2022-02-10T17:32:28Z'
            documents:
              - type: LOA
                description: Letter of authority
                status: PENDING_VALIDATION
                documentId: 255005
            fees:
              portFees: 1
              cancellationFees: 2.3
              phoneNumberMonthlyFees: 5.7
              currency: EUR
        links:
          - rel: CANCEL
            href: https://api.voxbone.com/v3/porting/251593
            type: PATCH
          - rel: SUPPORT
            href: https://support.voxbone.com/hc/en-us/requests/295782
            type: GET
    uploadDocumentsSuccessResponse:
      description: Success response for document upload endpoint
      value:
        data:
          documents:
            - type: LOA
              description: LOA
              status: PENDING_VALIDATION
              documentId: 552180
              link:
                rel: SELF
                href: http://api.voxbone.com/v3/porting/287415/documents/552180
                type: GET
            - type: COB
              description: Last Invoice
              status: PENDING_VALIDATION
              documentId: 552183
              link:
                rel: SELF
                href: http://api.voxbone.com/v3/porting/287415/documents/552183
                type: GET
  parameters:
    portInOrderId:
      name: portInOrderId
      description: Id of a port-in order.
      in: path
      required: true
      schema:
        type: integer
        example: 123567
    documentId:
      name: documentId
      description: Id of a document.
      in: path
      required: true
      schema:
        type: integer
        example: 457766088
    status:
      name: status
      description: Status of a port order. E.g. DRAFT, SUBMITTED, etc.
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/portInOrderStatusTypeEnum'
    phoneNumber:
      name: phoneNumber
      description: The number you are porting.
      in: query
      required: false
      schema:
        type: string
    phoneNumberType:
      name: phoneNumberType
      description: The type of phone number. E.g. NATIONAL, TOLL-FREE.
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/phoneNumberTypeEnum'
    countryCodeA3:
      name: countryCodeA3
      description: ISO 3166-1 standard 3-letter country code.
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/countryCodeA3'
    currentProviderName:
      name: currentProviderName
      description: >-
        The losing carrier who's currently the operator on the number to be
        ported in.
      in: query
      required: false
      schema:
        type: string
    customerReference:
      name: customerReference
      description: >-
        Parameter that can be used for your own reference, e.g. to uniquely
        identify one of your customers.
      in: query
      required: false
      schema:
        type: string
    supportRef:
      name: supportRef
      description: Reference of the support ticket associated to the port-in order.
      in: query
      required: false
      schema:
        type: string
    createdTimestamp:
      name: createdTimestamp
      description: >-
        Date in YYYY-MM-DD format representing when the initial port-in order
        was created.
      in: query
      required: false
      schema:
        type: string
    expectedPortCompleteDate:
      name: expectedPortCompleteDate
      description: >-
        Estimated completion date in YYYY-MM-DD format, calculated by adding
        lead time to date of submission. Only present once the order has been
        SUBMITTED.'
      in: query
      required: false
      schema:
        type: string
    preferredPortInDate:
      name: preferredPortInDate
      description: Date in YYYY-MM-DD format you requested for the port to be completed.
      in: query
      required: false
      schema:
        type: string
    submittedTimestamp:
      name: submittedTimestamp
      description: >-
        Date in YYYY-MM-DD format at the time when the order was submitted -
        only present when relevant.
      in: query
      required: false
      schema:
        type: string
    offset:
      name: offset
      description: Parameter specifies at what record to begin the resultset.
      in: query
      required: false
      schema:
        type: string
    limit:
      name: limit
      description: Parameter specifies how many results to retrieve.
      in: query
      required: false
      schema:
        type: string
  securitySchemes:
    KeyBasedAuthentication:
      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**.
      name: apikey
      in: header
security:
  - KeyBasedAuthentication: []
tags:
  - name: Portability Checker
  - name: Port-In Orders
  - name: Port-In Order Document
