openapi: 3.1.0
info:
  title: Messaging Transfers
  description: >-
    *These APIs are not available to all customers. They will be made available
    in January 2026. Please check with your Account Manager or Customer Support
    Manager if you have questions or want to start using them.*


    These APIs are used to manage requests to transfer messaging for a given
    phone number from one account to another. These requests can originate
    externally from third-party providers or internally from other Bandwidth
    accounts. Webhooks are 

    used to notify when a request is made to take messaging from a number. A
    subsequent API call is used to approve or deny the request. See the 

    [Messaging Transfer Confirmation API
    Guide](/docs/messaging/messagingTransfer) for details on how to use these
    APIs.


    The webhook subscription endpoints defined here are deprecated. Please use
    the [Bandwidth Subscriptions
    API](/apis/account-management-apis/subscriptions) to be notified of new
    messaging transfer requests. 
  contact:
    name: Bandwidth
    url: https://support.bandwidth.com
    email: support@bandwidth.com
  version: 1.0.0
  termsOfService: https://www.bandwidth.com/legal/terms-of-use-bandwidthcom-web-sites/
servers:
  - url: https://api.bandwidth.com/api/v2
    description: Production
security:
  - Basic: []
  - Bearer: []
tags:
  - name: Messaging Transfers
    description: Endpoints for confirming or denying messaging transfers
  - name: Webhooks
    description: Webhook callbacks notifying of messaging enablement requests
  - name: Webhook Subscriptions
    description: >-
      Endpoints for managing webhook subscriptions for requests to take
      messaging. These endpoints are deprecated; please use the [Bandwidth
      Subscriptions API](/apis/account-management-apis/subscriptions).
paths:
  /accounts/{accountId}/messagingPortouts/webhooks/subscriptions:
    get:
      description: >
        Provides a list of webhook subscriptions that are registered to receive
        status updates for the 

        messaging portout approvals submitted under this account (password will
        not be returned through this API; if `basicAuthentication` is defined, 

        the `password` property of that object will be null).
      operationId: listMessagingPortoutsWebhookSubscriptions
      deprecated: true
      parameters:
        - $ref: '#/components/parameters/accountIdPathParam'
      responses:
        '200':
          $ref: '#/components/responses/webhookSubscriptionsListResponse'
        '400':
          $ref: '#/components/responses/errorResponse400'
        '401':
          $ref: '#/components/responses/errorResponse401'
        '403':
          $ref: '#/components/responses/errorResponse403'
        '404':
          $ref: '#/components/responses/errorResponse404'
        '405':
          $ref: '#/components/responses/errorResponse405'
        '429':
          $ref: '#/components/responses/errorResponse429'
        '500':
          $ref: '#/components/responses/errorResponse500'
        '503':
          $ref: '#/components/responses/errorResponse503'
      summary: List all the webhook subscriptions registered for this account
      tags:
        - Webhook Subscriptions
    post:
      callbacks:
        messagingPortoutCallback:
          $ref: '#/components/callbacks/messagingPortoutRequestCallback'
      description: >
        Create a new webhook subscription (this webhook will be called for every
        update on every submission). 

        In addition to a `callbackUrl`, this subscription can provide optional
        HTTP basic authentication credentials (a username and a password). 

        The returned subscription object will contain an ID that can be used to
        modify or delete the subscription at a later time.
      operationId: createMessagingPortoutsWebhookSubscription
      deprecated: true
      parameters:
        - $ref: '#/components/parameters/accountIdPathParam'
      requestBody:
        $ref: '#/components/requestBodies/messagingPortoutWebhookSubscriptionRequest'
      responses:
        '201':
          $ref: '#/components/responses/webhookSubscriptionResponse'
        '400':
          $ref: '#/components/responses/errorResponse400'
        '401':
          $ref: '#/components/responses/errorResponse401'
        '403':
          $ref: '#/components/responses/errorResponse403'
        '405':
          $ref: '#/components/responses/errorResponse405'
        '429':
          $ref: '#/components/responses/errorResponse429'
        '500':
          $ref: '#/components/responses/errorResponse500'
        '503':
          $ref: '#/components/responses/errorResponse503'
      summary: Create a new webhook subscription
      tags:
        - Webhook Subscriptions
  /accounts/{accountId}/messagingPortouts/webhooks/subscriptions/{id}:
    delete:
      description: Delete a webhook subscription by ID.
      operationId: deleteMessagingPortoutsWebhookSubscription
      deprecated: true
      parameters:
        - $ref: '#/components/parameters/accountIdPathParam'
        - $ref: '#/components/parameters/webhookSubscriptionIdPathParam'
      responses:
        '204':
          $ref: '#/components/responses/noBodyResponse'
        '400':
          $ref: '#/components/responses/errorResponse400'
        '401':
          $ref: '#/components/responses/errorResponse401'
        '403':
          $ref: '#/components/responses/errorResponse403'
        '404':
          $ref: '#/components/responses/errorResponse404'
        '405':
          $ref: '#/components/responses/errorResponse405'
        '429':
          $ref: '#/components/responses/errorResponse429'
        '500':
          $ref: '#/components/responses/errorResponse500'
        '503':
          $ref: '#/components/responses/errorResponse503'
      summary: Delete a webhook subscription
      tags:
        - Webhook Subscriptions
    put:
      description: >-
        Update an existing webhook subscription (`callbackUrl` and
        `basicAuthentication` can be updated).
      operationId: updateMessagingPortoutsWebhookSubscription
      deprecated: true
      parameters:
        - $ref: '#/components/parameters/accountIdPathParam'
        - $ref: '#/components/parameters/webhookSubscriptionIdPathParam'
      requestBody:
        $ref: '#/components/requestBodies/messagingPortoutWebhookSubscriptionRequest'
      responses:
        '202':
          $ref: '#/components/responses/acceptedResponse'
        '400':
          $ref: '#/components/responses/errorResponse400'
        '401':
          $ref: '#/components/responses/errorResponse401'
        '403':
          $ref: '#/components/responses/errorResponse403'
        '404':
          $ref: '#/components/responses/errorResponse404'
        '405':
          $ref: '#/components/responses/errorResponse405'
        '429':
          $ref: '#/components/responses/errorResponse429'
        '500':
          $ref: '#/components/responses/errorResponse500'
        '503':
          $ref: '#/components/responses/errorResponse503'
      summary: Update an existing webhook subscription
      tags:
        - Webhook Subscriptions
  /accounts/{accountId}/messagingPortouts/{requestId}:
    put:
      description: >-
        This PUT request can be used to approve or deny a messaging transfer
        request.

        This endpoint is deprecated, and the [PATCH
        request](#tag/Messaging-Transfer-Confirmation/operation/updateMessagingTransfer)
        is suggested for an improved experience.
      operationId: approveOrdenyMessagingPortoutRequest
      deprecated: true
      parameters:
        - $ref: '#/components/parameters/accountIdPathParam'
        - $ref: '#/components/parameters/requestIdPathParam'
      requestBody:
        $ref: '#/components/requestBodies/messagingPortOutUpdateRequest'
      responses:
        '202':
          $ref: '#/components/responses/acceptedResponse'
        '400':
          $ref: '#/components/responses/errorResponse400'
        '401':
          $ref: '#/components/responses/errorResponse401'
        '403':
          $ref: '#/components/responses/errorResponse403'
        '404':
          $ref: '#/components/responses/errorResponse404'
        '405':
          $ref: '#/components/responses/errorResponse405'
        '429':
          $ref: '#/components/responses/errorResponse429'
        '500':
          $ref: '#/components/responses/errorResponse500'
        '503':
          $ref: '#/components/responses/errorResponse503'
      summary: Approve or Deny Messaging Transfer Request
      tags:
        - Messaging Transfers
  /accounts/{accountId}/messaging/transfer-requests/{requestId}:
    get:
      description: Returns the details for a messaging transfer request.
      operationId: getMessagingTransfer
      parameters:
        - $ref: '#/components/parameters/accountIdPathParam'
        - $ref: '#/components/parameters/requestIdPathParam'
      responses:
        '200':
          $ref: '#/components/responses/getMessagingTransferResponse'
        '400':
          $ref: '#/components/responses/errorResponse400'
        '401':
          $ref: '#/components/responses/errorResponse401'
        '403':
          $ref: '#/components/responses/errorResponse403'
        '404':
          $ref: '#/components/responses/errorResponse404'
        '405':
          $ref: '#/components/responses/errorResponse405'
        '429':
          $ref: '#/components/responses/errorResponse429'
        '500':
          $ref: '#/components/responses/errorResponse500'
        '503':
          $ref: '#/components/responses/errorResponse503'
      summary: Get Messaging Transfer Request
      tags:
        - Messaging Transfers
    patch:
      description: This request can be used to approve or deny a messaging transfer.
      operationId: updateMessagingTransfer
      parameters:
        - $ref: '#/components/parameters/accountIdPathParam'
        - $ref: '#/components/parameters/requestIdPathParam'
      requestBody:
        $ref: '#/components/requestBodies/answerMessagingTransferRequest'
      responses:
        '200':
          $ref: '#/components/responses/getMessagingTransferResponse'
        '400':
          $ref: '#/components/responses/errorResponse400'
        '401':
          $ref: '#/components/responses/errorResponse401'
        '403':
          $ref: '#/components/responses/errorResponse403'
        '404':
          $ref: '#/components/responses/errorResponse404'
        '405':
          $ref: '#/components/responses/errorResponse405'
        '429':
          $ref: '#/components/responses/errorResponse429'
        '500':
          $ref: '#/components/responses/errorResponse500'
        '503':
          $ref: '#/components/responses/errorResponse503'
      summary: Approve or Deny Messaging Transfer Request
      tags:
        - Messaging Transfers
  /accounts/{accountId}/messaging/transfer-requests:
    get:
      description: >-
        Get all external and Bandwidth-to-Bandwidth Messaging Transfer requests
        for this account. This is a paginated API that can be sorted and
        filtered by a number of the fields in the request. For example, it
        accepts a telephone number to filter requests that have been made for
        that number.
      operationId: getMessagingTransfers
      parameters:
        - $ref: '#/components/parameters/accountIdPathParam'
        - $ref: '#/components/parameters/phoneNumberParam'
        - $ref: '#/components/parameters/offsetParam'
        - $ref: '#/components/parameters/limitParam'
        - $ref: '#/components/parameters/statusParam'
        - $ref: '#/components/parameters/sourceParam'
      responses:
        '200':
          $ref: '#/components/responses/getMessagingTransfersResponse'
        '400':
          $ref: '#/components/responses/errorResponse400'
        '401':
          $ref: '#/components/responses/errorResponse401'
        '403':
          $ref: '#/components/responses/errorResponse403'
        '404':
          $ref: '#/components/responses/errorResponse404'
        '405':
          $ref: '#/components/responses/errorResponse405'
        '429':
          $ref: '#/components/responses/errorResponse429'
        '500':
          $ref: '#/components/responses/errorResponse500'
        '503':
          $ref: '#/components/responses/errorResponse503'
      summary: Get Messaging Transfer Requests
      tags:
        - Messaging Transfers
webhooks:
  messagingPortoutRequestWebhook:
    post:
      description: POST request Bandwidth sends to notify of a text enablement request.
      parameters:
        - description: >-
            64-character lowercase hexadecimal HMAC calculated with a shared
            secret key, the canonicalized request body, and SHA256. It is only
            included when a shared secret key is set through webhook
            subscription.
          example: ca7b9e9816c90d336f5dca529e733354b81535c7af027b81878ac98afb2dbaa2
          in: header
          name: x-bandwidth-signature-hmac-sha256
          schema:
            type: string
      requestBody:
        $ref: '#/components/requestBodies/messagingPortoutCustomerCallbackRequest'
      responses:
        '204':
          description: No content
        '400':
          $ref: '#/components/responses/errorResponse400'
        '401':
          $ref: '#/components/responses/errorResponse401'
        '403':
          $ref: '#/components/responses/errorResponse403'
        '404':
          $ref: '#/components/responses/errorResponse404'
        '405':
          $ref: '#/components/responses/errorResponse405'
        '500':
          $ref: '#/components/responses/errorResponse500'
        '503':
          $ref: '#/components/responses/errorResponse503'
      summary: Messaging Transfer Request Webhook
      tags:
        - Webhooks
components:
  callbacks:
    messagingPortoutRequestCallback:
      your_url.com/webhookService:
        post:
          description: >-
            Unique webhook URL provided by customers to which Bandwidth sends a
            POST request to notify customer regarding the request.
          operationId: messagingPortoutRequestCallback
          parameters:
            - description: >-
                64-character lowercase hexadecimal HMAC calculated with a shared
                secret key, the canonicalized request body, and SHA256. It is
                only included when a shared secret key is set through webhook
                subscription.
              example: ca7b9e9816c90d336f5dca529e733354b81535c7af027b81878ac98afb2dbaa2
              in: header
              name: x-bandwidth-signature-hmac-sha256
              schema:
                type: string
          requestBody:
            $ref: '#/components/requestBodies/messagingPortoutCustomerCallbackRequest'
          responses:
            '204':
              description: No content
            '400':
              $ref: '#/components/responses/errorResponse400'
            '401':
              $ref: '#/components/responses/errorResponse401'
            '403':
              $ref: '#/components/responses/errorResponse403'
            '404':
              $ref: '#/components/responses/errorResponse404'
            '405':
              $ref: '#/components/responses/errorResponse405'
            '500':
              $ref: '#/components/responses/errorResponse500'
            '503':
              $ref: '#/components/responses/errorResponse503'
          summary: POST to customer's webhook URL about the text enablement request
  examples:
    approveMessagingPortoutRequest:
      description: Approve Request
      value:
        approval: 'YES'
    answerApproveMessagingTransferRequest:
      description: Approve Request
      value:
        status: APPROVED
    answerApproveMessagingTransferRequestWithComment:
      description: Approve Request
      value:
        status: APPROVED
        comment: Approved comment
    denyMessagingPortoutRequest:
      description: Deny Request
      value:
        approval: 'NO'
        comment: Some comment
    answerDenyMessagingTransferRequest:
      description: Deny Request
      value:
        status: DENIED
        comment: Some comment
    bandwidthAccountToAccountRequest:
      description: Bandwidth Account to Account Request
      value:
        data:
          requestId: 6CDrbcvWVKtM4RY2Ta41SX
          phoneNumber: '+19194445555'
          oldNnid: '789456'
          newNnid: '963852'
          overwritingCarrier: bandwidth
          activationDate: '2023-05-15T13:56:39.965Z'
          status: APPROVED
          source: BANDWIDTH
        links:
          - href: >-
              /api/v2/accounts/9900010/messaging/transfer-requests/6CDrbcvWVKtM4RY2Ta41SX
            rel: self
            method: GET
        errors: []
    outOfBandwidthRequest:
      description: Out of Bandwidth (External) Request
      value:
        data:
          requestId: 6CDrbcvWVKtM4RY2Ta41SB
          phoneNumber: '+19194445554'
          oldNnid: '789456'
          newNnid: '963852'
          overwritingCarrier: random_external_partner
          activationDate: '2023-05-15T13:56:39.965Z'
          status: APPROVED
          source: EXTERNAL
        links:
          - href: >-
              /api/v2/accounts/9900010/messaging/transfer-requests/6CDrbcvWVKtM4RY2Ta41SX
            rel: self
            method: GET
        errors: []
  schemas:
    enumStatus:
      type: string
      description: The current status of the messaging request
      enum:
        - APPROVED
        - DENIED
        - REQUESTED
        - FORWARDED_TO_CUSTOMER
    sourceStatus:
      type: string
      description: The source of the messaging request
      enum:
        - EXTERNAL
        - BANDWIDTH
    sort:
      type: string
      enum:
        - ASC
        - DESC
    messagingTransferResponse:
      type: object
      properties:
        requestId:
          $ref: '#/components/schemas/requestId'
        phoneNumber:
          $ref: '#/components/schemas/phoneNumber'
        oldNnid:
          description: The current NetNumber ID assigned to the phone number
          example: '789456'
          type: string
        newNnid:
          description: >-
            The NetNumber ID to be assigned to the phone number if the request
            is approved
          example: '963852'
          type: string
        overwritingCarrier:
          description: >-
            The name of the carrier requesting to take messaging from the phone
            number
          example: NewCarrierName
          type: string
        activationDate:
          description: The date and time the overwrite was requested
          example: '2023-05-15T13:56:39.965Z'
          format: date-time
          type: string
        status:
          $ref: '#/components/schemas/enumStatus'
        source:
          $ref: '#/components/schemas/sourceStatus'
        comment:
          description: The comment supplied during the approval process
          type: string
          example: Random comment
    getMessagingTransferResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/messagingTransferResponse'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/errorEntry'
          description: >-
            The errors array will be empty for successful responses to this
            request.
          examples:
            - []
        links:
          items:
            $ref: '#/components/schemas/apiResponseLink'
          readOnly: true
          type: array
    getMessagingTransfersResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/messagingTransferResponse'
        page:
          $ref: '#/components/schemas/responsePage'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/errorEntry'
          description: The errors array will always be empty for this response.
          examples:
            - []
        links:
          items:
            $ref: '#/components/schemas/apiResponseLink'
          readOnly: true
          type: array
          example:
            - href: /api/v2/accounts/9900010/messaging/transfer-requests?offset=0
              rel: first
              method: GET
            - href: /api/v2/accounts/9900010/messaging/transfer-requests?offset=10
              rel: last
              method: GET
            - href: /api/v2/accounts/9900010/messaging/transfer-requests?offset=3
              rel: next
              method: GET
            - href: /api/v2/accounts/9900010/messaging/transfer-requests?offset=1
              rel: prev
              method: GET
    apiResponseErrorEntry:
      type: object
      properties:
        type:
          type: string
          description: >-
            A short, human-readable description of the type of error (e.g. "bad
            request").
          examples:
            - bad request
        description:
          type: string
          description: A full description of the error (e.g. "name cannot be blank").
          examples:
            - accountId is required
        source:
          type: object
          additionalProperties:
            type: string
          description: >
            A map from the type of source to a value for that type. The
            supported keys are: 1) POINTER (the value is a RFC6901 JSON pointer
            to a field in the request body); 2) PARAMETER (the value is a query
            parameter name); and 3) PATH (the value is a parameter name in the
            URI of the request). There will only be one entry in the source
            property, as each error is recorded separately in the errors array.
          examples:
            - 'POINTER: /accountId'
    apiResponseLink:
      description: Link to a resource
      properties:
        href:
          type: string
          readOnly: true
          examples:
            - >-
              /api/v2/accounts/9900010/messaging/transfer-requests/asd231das3ASDQW
        rel:
          type: string
          readOnly: true
          examples:
            - self
        method:
          type: string
          readOnly: true
          examples:
            - GET
    responsePage:
      description: Information about the current page
      properties:
        pageSize:
          type: integer
          format: int32
          readOnly: true
          examples:
            - 25
        totalElements:
          type: integer
          format: int32
          readOnly: true
          examples:
            - 434
        totalPages:
          type: integer
          format: int32
          readOnly: true
          examples:
            - 18
        pageNumber:
          type: integer
          format: int32
          readOnly: true
          examples:
            - 3
    errorEntry:
      type: object
      properties:
        type:
          type: string
          description: >-
            A short, human-readable description of the type of error (e.g. "bad
            request").
          examples:
            - bad request
        description:
          type: string
          description: A full description of the error (e.g. "name cannot be blank").
          examples:
            - accountId is required
        source:
          type: object
          additionalProperties:
            type: string
          description: >
            A map from the type of source to a value for that type. The
            supported keys are: 1) POINTER (the value is a RFC6901 JSON pointer
            to a field in the request body); 2) PARAMETER (the value is a query
            parameter name); and 3) PATH (the value is a parameter name in the
            URI of the request). There will only be one entry in the source
            property, as each error is recorded separately in the errors array.
          examples:
            - 'POINTER: /accountId'
    errorResponse400:
      properties:
        data:
          type: object
          nullable: true
          example: null
        links:
          type: array
          items:
            $ref: '#/components/schemas/apiResponseLink'
          examples:
            - []
          readOnly: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/errorEntry'
    errorResponse401:
      properties:
        data:
          type: object
          nullable: true
          example: null
        links:
          type: array
          items:
            $ref: '#/components/schemas/apiResponseLink'
          examples:
            - []
          readOnly: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/errorEntry'
    errorResponse403:
      properties:
        data:
          type: object
          nullable: true
          example: null
        links:
          type: array
          items:
            $ref: '#/components/schemas/apiResponseLink'
          examples:
            - []
          readOnly: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/errorEntry'
    errorResponse404:
      properties:
        data:
          type: object
          nullable: true
          example: null
        links:
          type: array
          items:
            $ref: '#/components/schemas/apiResponseLink'
          examples:
            - []
          readOnly: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/errorEntry'
    errorResponse405:
      properties:
        data:
          type: object
          nullable: true
          example: null
        links:
          type: array
          items:
            $ref: '#/components/schemas/apiResponseLink'
          examples:
            - []
          readOnly: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/errorEntry'
    errorResponse409:
      properties:
        data:
          type: object
          nullable: true
          example: null
        links:
          type: array
          items:
            $ref: '#/components/schemas/apiResponseLink'
          examples:
            - []
          readOnly: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/errorEntry'
    errorResponse500:
      properties:
        data:
          type: object
          nullable: true
          example: null
        links:
          type: array
          items:
            $ref: '#/components/schemas/apiResponseLink'
          examples:
            - []
          readOnly: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/errorEntry'
    errorResponse429:
      properties:
        data:
          type: object
          nullable: true
          example: null
        links:
          type: array
          items:
            $ref: '#/components/schemas/apiResponseLink'
          examples:
            - []
          readOnly: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/errorEntry'
    errorResponse503:
      properties:
        data:
          type: object
          nullable: true
          example: null
        links:
          type: array
          items:
            $ref: '#/components/schemas/apiResponseLink'
          examples:
            - []
          readOnly: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/errorEntry'
    errorResponseBody:
      description: A generic error object.
      properties:
        type:
          example: Error Type
          type: string
        description:
          example: Error Message
          type: string
        errors:
          description: >-
            Each key of this errors object refers to a field of the submitted
            object (using dot notation for nested objects), with the field being
            a key to an array of one or more errors for that field.
          example:
            field: error message
          type: object
      type: object
    thirdPartyOriginatedCallback:
      properties:
        requestId:
          $ref: '#/components/schemas/requestId'
        phoneNumber:
          $ref: '#/components/schemas/phoneNumber'
        notificationType:
          enum:
            - PORTOUT_REQUEST
          type: string
        oldNnid:
          description: The current NetNumber ID assigned to the phone number
          example: '789456'
          type: string
        newNnid:
          description: >-
            The NetNumber ID to be assigned to the phone number if the request
            is approved
          example: '963852'
          type: string
        overwriterCarrier:
          description: >-
            The name of the carrier requesting to take messaging from the phone
            number
          example: NewCarrierName
          type: string
        activation:
          description: The date and time the overwrite was requested
          example: '2023-05-15T13:56:39.965Z'
          format: date-time
          type: string
      required:
        - requestId
        - phoneNumber
        - notificationType
        - oldNnid
        - newNnid
        - overwriterCarrier
        - activation
      type: object
    messagingPortoutRequest:
      description: Messaging Enablement Request
      properties:
        comment:
          description: Optional comment
          maximum: 255
          type: string
        approval:
          description: Yes or No approval value
          enum:
            - 'YES'
            - 'NO'
          type: string
    answerMessagingTransferRequest:
      description: Messaging Enablement Request
      properties:
        comment:
          description: Optional comment
          maximum: 255
          type: string
        status:
          description: New request status
          type: string
          enum:
            - APPROVED
            - DENIED
    messagingPortoutWebhookSubscription:
      description: >-
        Information about a webhook that Bandwidth should send upon the
        completion of event customer has subscribed to.
      properties:
        accountId:
          example: '1234567'
          type: string
        basicAuthentication:
          description: >-
            Basic authentication credentials are not required, but if present,
            both username and password must be provided.
          properties:
            password:
              maxLength: 200
              type: string
            username:
              maxLength: 100
              type: string
          required:
            - username
            - password
          type: object
        callbackUrl:
          $ref: '#/components/schemas/webhookUrl'
        createdDate:
          example: '2023-05-15T13:56:39.965Z'
          format: date-time
          type: string
        id:
          example: 7hICGStfAfeGxEq3N0lQwO
          type: string
        modifiedDate:
          example: '2023-05-15T13:56:39.965Z'
          format: date-time
          type: string
        sharedSecretKey:
          $ref: '#/components/schemas/sharedSecretKey'
        webhookType:
          description: Type of webhook subscription.
          enum:
            - PORTOUT_REQUEST
          example: PORTOUT_REQUEST
          type: string
      required:
        - callbackUrl
      type: object
    messagingPortoutWebhookSubscriptionsListBody:
      description: >-
        A list of all webhook subscriptions registered for this account ID for
        Messaging Transfer Confirmation.
      properties:
        data:
          items:
            $ref: '#/components/schemas/messagingPortoutWebhookSubscription'
          type: array
        errors:
          type: array
          items:
            $ref: '#/components/schemas/apiResponseErrorEntry'
          description: The errors array will always be empty for this response.
          examples:
            - []
        links:
          items:
            $ref: '#/components/schemas/apiResponseLink'
          readOnly: true
          type: array
      required:
        - data
      type: object
    bandwidthOriginatedCallback:
      properties:
        requestId:
          $ref: '#/components/schemas/requestId'
        phoneNumber:
          $ref: '#/components/schemas/phoneNumber'
        notificationType:
          enum:
            - PORTOUT_REQUEST
          type: string
        oldNnid:
          description: The current NetNumber ID assigned to the phone number
          example: '789456'
          type: string
        newNnid:
          description: >-
            The NetNumber ID to be assigned to the phone number if the request
            is approved
          example: '963852'
          type: string
        overwriterCarrier:
          description: >-
            The name of the carrier requesting to take messaging from the phone
            number
          example: NewCarrierName
          type: string
        activation:
          description: The date and time the overwrite was requested
          example: '2023-05-15T13:56:39.965Z'
          format: date-time
          type: string
      required:
        - requestId
        - phoneNumber
        - notificationType
        - oldNnid
        - newNnid
        - overwriterCarrier
        - activation
      type: object
    requestId:
      description: The unique ID assigned to the request
      examples:
        - '33636456'
        - 14DloM8hrxtD6Z7oOpPDv8
      type: string
    phoneNumber:
      description: Telephone Number in E.164 format.
      example: '+19194445555'
      type: string
    sharedSecretKey:
      description: >-
        An ASCII string submitted by the user as a shared secret key for
        generating an HMAC header for callbacks.
      example: This is my $3cret
      maxLength: 64
      minLength: 16
      nullable: true
      pattern: ^[ -~]{16,64}$
      type: string
      writeOnly: true
    webhookUrl:
      description: >-
        Callback URL to receive status updates from Bandwidth. When a webhook
        subscription is registered with Bandwidth under a given account ID, it
        will be used to send status updates for all requests submitted under
        that account ID.
      example: https://www.example.com/path/to/resource
      format: uri
      maxLength: 2000
      minLength: 0
      nullable: true
      pattern: >-
        ^$|(https?:\/\/)?(www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,253}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#()?&//=]*)
      type: string
  parameters:
    accountIdPathParam:
      description: User's account ID.
      example: '1234567'
      in: path
      name: accountId
      required: true
      schema:
        type: string
    phoneNumberPathParam:
      description: Telephone Number in E.164 format.
      example: '+19194445555'
      in: path
      name: phoneNumber
      required: true
      schema:
        type: string
    requestIdPathParam:
      description: Messaging transfer request ID supplied in the original webhook
      in: path
      name: requestId
      required: true
      schema:
        examples:
          - '33636456'
          - 14DloM8hrxtD6Z7oOpPDv8
        type: string
    webhookSubscriptionIdPathParam:
      description: Webhook subscription ID
      example: 7bt57JcsVYJrN9K1OcV1Nu
      in: path
      name: id
      required: true
      schema:
        type: string
    limitParam:
      name: limit
      in: query
      description: Limit (page size) for pagination
      required: false
      schema:
        type: number
        default: 50
        maximum: 250
        examples:
          - limit: 10
    offsetParam:
      name: offset
      in: query
      description: Offset for pagination (from zero, the first returned record)
      required: false
      schema:
        type: number
        default: 0
        examples:
          - offset: 25
    phoneNumberParam:
      name: phoneNumber
      in: query
      description: Filtering and sorting parameter for `phoneNumber`.
      style: deepObject
      explode: true
      required: false
      schema:
        title: String Query Parameter
        description: Schema for string query parameter
        properties:
          eq:
            type: string
          sort:
            $ref: '#/components/schemas/sort'
        examples:
          - eq: '+19194445555'
          - sort: DESC
    statusParam:
      name: status
      in: query
      description: Filtering and sorting parameter for `status`.
      style: deepObject
      explode: true
      required: false
      schema:
        title: String Query Parameter
        description: Schema for string query parameter
        properties:
          eq:
            $ref: '#/components/schemas/enumStatus'
          sort:
            $ref: '#/components/schemas/sort'
        examples:
          - eq: REQUESTED
          - sort: DESC
    sourceParam:
      name: source
      in: query
      description: Filtering and sorting parameter for `source`.
      style: deepObject
      explode: true
      required: false
      schema:
        title: String Query Parameter
        description: Schema for string query parameter
        properties:
          eq:
            $red: '#/components/schemas/sourceStatus'
        examples:
          - eq: EXTERNAL
  requestBodies:
    messagingPortoutCustomerCallbackRequest:
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/thirdPartyOriginatedCallback'
              - $ref: '#/components/schemas/bandwidthOriginatedCallback'
      description: >-
        Callback request to notify customer of overwrite request, status of the
        response sent to the vendor, and overwritten notification
      required: true
    messagingPortoutWebhookSubscriptionRequest:
      content:
        application/json:
          schema:
            properties:
              basicAuthentication:
                properties:
                  password:
                    maxLength: 200
                    type: string
                  username:
                    maxLength: 100
                    type: string
                required:
                  - username
                  - password
                type: object
              callbackUrl:
                $ref: '#/components/schemas/webhookUrl'
              sharedSecretKey:
                $ref: '#/components/schemas/sharedSecretKey'
              webhookType:
                enum:
                  - PORTOUT_REQUEST
                  - PORTOUT_RESPONSE_SUBMITTED
                  - MESSAGING_OVERWRITTEN
                example: PORTOUT_REQUEST
                type: string
            required:
              - callbackUrl
              - webhookType
            type: object
      description: >-
        Information about a webhook that Bandwidth should send upon the
        completion of event customer is trying to subscribe to.
      required: true
    messagingPortOutUpdateRequest:
      content:
        application/json:
          examples:
            approvePortoutRequest:
              $ref: '#/components/examples/approveMessagingPortoutRequest'
              summary: Approve Request
            denyPortoutRequest:
              $ref: '#/components/examples/denyMessagingPortoutRequest'
              summary: Deny Request
          schema:
            $ref: '#/components/schemas/messagingPortoutRequest'
    answerMessagingTransferRequest:
      content:
        application/json:
          examples:
            approveTransferPortoutRequest:
              $ref: '#/components/examples/answerApproveMessagingTransferRequest'
              summary: Approve Request
            approveTransferRequestWithComment:
              $ref: >-
                #/components/examples/answerApproveMessagingTransferRequestWithComment
              summary: Approve Request with comment
            denyTransferRequest:
              $ref: '#/components/examples/answerDenyMessagingTransferRequest'
              summary: Deny Request
          schema:
            $ref: '#/components/schemas/answerMessagingTransferRequest'
  responses:
    getMessagingTransferResponse:
      content:
        application/json:
          examples:
            bandwidthAccountToAccountRequest:
              $ref: '#/components/examples/bandwidthAccountToAccountRequest'
              summary: Transfer from one Bandwidth account to another
            outOfBandwidthRequest:
              $ref: '#/components/examples/outOfBandwidthRequest'
              summary: Transfer from Bandwidth to a third-party provider
          schema:
            $ref: '#/components/schemas/getMessagingTransferResponse'
      description: OK
    getMessagingTransfersResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/getMessagingTransfersResponse'
      description: OK
    errorResponse400:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse400'
      description: Bad Request
    errorResponse401:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse401'
      description: Unauthorized
    errorResponse403:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse403'
      description: Forbidden
    errorResponse404:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse404'
      description: Not Found
    errorResponse405:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse405'
      description: Method Not Allowed
    errorResponse409:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse409'
      description: Conflict
    errorResponse429:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse429'
      description: Too Many Requests
    errorResponse500:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse500'
      description: Internal Server Error
    errorResponse503:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse503'
      description: Service Unavailable
    webhookSubscriptionResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/messagingPortoutWebhookSubscription'
      description: Created
    webhookSubscriptionsListResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/messagingPortoutWebhookSubscriptionsListBody'
      description: OK
    acceptedResponse:
      description: Accepted
    noBodyResponse:
      description: No Content
  securitySchemes:
    Basic:
      type: http
      scheme: basic
      description: >-
        Basic authentication is a simple authentication scheme built into the
        HTTP protocol. To use it, send your HTTP requests with an
        `Authorization` header that contains the word `Basic` followed by a
        space and a Base64-encoded string `username:password`.


        - Example: `Authorization: Basic ZGVtbZpwQDU1dzByZA==`
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer authentication (also called token authentication) is an HTTP
        authentication scheme that involves security tokens called bearer
        tokens. The name “Bearer authentication” can be understood as “give
        access to the bearer of this token.” The client must send this token in
        the `Authorization` header when making requests to protected resources.


        - Example: `Authorization: Bearer <token>`


        Where `<token>` should be replaced with the token string without angle
        brackets.


        For more information, see the following guide:
        [Credentials](https://dev.bandwidth.com/docs/credentials)
