bandwidth-sdk 13.1.4 → 14.1.0

data/bandwidth.yml

@@ -19,6 +19,7 @@ tags:
   - name: Transcriptions
   - name: MFA
   - name: Phone Number Lookup
+  - name: Toll-Free Verification
 paths:
   /users/{accountId}/media:
     get:
@@ -230,8 +231,6 @@ paths:
         '500':
           $ref: '#/components/responses/messagingInternalServerError'
       callbacks:
-        inboundCallback:
-          $ref: '#/components/callbacks/inboundCallback'
         statusCallback:
           $ref: '#/components/callbacks/statusCallback'
     servers: *ref_0
@@ -1330,8 +1329,287 @@ paths:
         '500':
           $ref: '#/components/responses/tnLookupInternalServerError'
     servers: *ref_3
+  /accounts/{accountId}/tollFreeVerification:
+    post:
+      tags:
+        - Toll-Free Verification
+      summary: Request Toll-Free Verification
+      description: Submit a request for verification of a toll-free phone number.
+      operationId: requestTollFreeVerification
+      parameters:
+        - $ref: '#/components/parameters/accountId'
+      requestBody:
+        $ref: '#/components/requestBodies/requestTollFreeVerificationRequest'
+      responses:
+        '202':
+          description: Accepted
+        '400':
+          $ref: '#/components/responses/tfvPostBadRequestResponse'
+        '401':
+          $ref: '#/components/responses/tfvUnauthorizedResponse'
+        '403':
+          $ref: '#/components/responses/tfvForbiddenResponse'
+        '405':
+          $ref: '#/components/responses/tfvNotAllowedResponse'
+        '429':
+          $ref: '#/components/responses/tfvTooManyRequestsResponse'
+        '500':
+          $ref: '#/components/responses/tfvServerErrorResponse'
+        '503':
+          $ref: '#/components/responses/tfvServiceUnavailableResponse'
+      callbacks:
+        tfVerificationStatus:
+          $ref: '#/components/callbacks/tfVerificationStatus'
+    servers: &ref_4
+      - url: https://api.bandwidth.com/api/v2
+        description: Production
+  /accounts/{accountId}/phoneNumbers/{phoneNumber}/tollFreeVerification:
+    get:
+      tags:
+        - Toll-Free Verification
+      summary: Get Toll-Free Verification Status
+      description: >-
+        Gets the verification status for a phone number that is provisioned to
+        your account.
+
+        Submission information will be appended to the response if it is
+        available.
+      operationId: getTollFreeVerificationStatus
+      parameters:
+        - $ref: '#/components/parameters/accountId'
+        - $ref: '#/components/parameters/tfPhoneNumberPathParam'
+      responses:
+        '200':
+          $ref: '#/components/responses/getTollFreeVerificationStatusResponse'
+        '400':
+          $ref: '#/components/responses/tfvBadRequestResponse'
+        '401':
+          $ref: '#/components/responses/tfvUnauthorizedResponse'
+        '403':
+          $ref: '#/components/responses/tfvForbiddenResponse'
+        '404':
+          $ref: '#/components/responses/tfvNotFoundResponse'
+        '405':
+          $ref: '#/components/responses/tfvNotAllowedResponse'
+        '429':
+          $ref: '#/components/responses/tfvTooManyRequestsResponse'
+        '500':
+          $ref: '#/components/responses/tfvServerErrorResponse'
+        '503':
+          $ref: '#/components/responses/tfvServiceUnavailableResponse'
+    put:
+      tags:
+        - Toll-Free Verification
+      summary: Update Toll-Free Verification Request
+      description: >-
+        Updates a toll-free verification request.
+
+        Submissions are only eligible for resubmission for 7 days within being
+        processed and if resubmission is allowed (resubmitAllowed field is
+        true).
+      operationId: updateTollFreeVerificationRequest
+      parameters:
+        - $ref: '#/components/parameters/accountId'
+        - $ref: '#/components/parameters/tfPhoneNumberPathParam'
+      requestBody:
+        $ref: '#/components/requestBodies/updateTollFreeVerificationRequestRequest'
+      responses:
+        '202':
+          description: Accepted
+        '400':
+          $ref: '#/components/responses/tfvPostBadRequestResponse'
+        '401':
+          $ref: '#/components/responses/tfvUnauthorizedResponse'
+        '403':
+          $ref: '#/components/responses/tfvForbiddenResponse'
+        '405':
+          $ref: '#/components/responses/tfvNotAllowedResponse'
+        '429':
+          $ref: '#/components/responses/tfvTooManyRequestsResponse'
+        '500':
+          $ref: '#/components/responses/tfvServerErrorResponse'
+        '503':
+          $ref: '#/components/responses/tfvServiceUnavailableResponse'
+      callbacks:
+        tfVerificationStatus:
+          $ref: '#/components/callbacks/tfVerificationStatus'
+    servers: *ref_4
+  /accounts/{accountId}/tollFreeVerification/webhooks/subscriptions:
+    get:
+      tags:
+        - Toll-Free Verification
+      summary: List Webhook Subscriptions
+      description: >-
+        Lists all webhook subscriptions that are registered to receive status
+        updates for the toll-free verification requests 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: listWebhookSubscriptions
+      parameters:
+        - $ref: '#/components/parameters/accountId'
+      responses:
+        '200':
+          $ref: '#/components/responses/listWebhookSubscriptionsResponse'
+        '400':
+          $ref: '#/components/responses/tfvPostBadRequestResponse'
+        '401':
+          $ref: '#/components/responses/tfvUnauthorizedResponse'
+        '403':
+          $ref: '#/components/responses/tfvForbiddenResponse'
+        '405':
+          $ref: '#/components/responses/tfvNotAllowedResponse'
+        '429':
+          $ref: '#/components/responses/tfvTooManyRequestsResponse'
+        '500':
+          $ref: '#/components/responses/tfvServerErrorResponse'
+        '503':
+          $ref: '#/components/responses/tfvServiceUnavailableResponse'
+    post:
+      tags:
+        - Toll-Free Verification
+      summary: Create Webhook Subscription
+      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: createWebhookSubscription
+      parameters:
+        - $ref: '#/components/parameters/accountId'
+      requestBody:
+        $ref: '#/components/requestBodies/webhookSubscriptionRequest'
+      responses:
+        '201':
+          $ref: '#/components/responses/createWebhookSubscriptionResponse'
+        '400':
+          $ref: '#/components/responses/tfvBadRequestResponse'
+        '401':
+          $ref: '#/components/responses/tfvUnauthorizedResponse'
+        '403':
+          $ref: '#/components/responses/tfvForbiddenResponse'
+        '404':
+          $ref: '#/components/responses/tfvNotFoundResponse'
+        '405':
+          $ref: '#/components/responses/tfvNotAllowedResponse'
+        '429':
+          $ref: '#/components/responses/tfvTooManyRequestsResponse'
+        '500':
+          $ref: '#/components/responses/tfvServerErrorResponse'
+        '503':
+          $ref: '#/components/responses/tfvServiceUnavailableResponse'
+    servers: *ref_4
+  /accounts/{accountId}/tollFreeVerification/webhooks/subscriptions/{id}:
+    delete:
+      tags:
+        - Toll-Free Verification
+      summary: Delete Webhook Subscription
+      description: Delete a webhook subscription by ID.
+      operationId: deleteWebhookSubscription
+      parameters:
+        - $ref: '#/components/parameters/accountId'
+        - $ref: '#/components/parameters/webhookSubscriptionIdPathParam'
+      responses:
+        '204':
+          description: No Content
+        '400':
+          $ref: '#/components/responses/tfvBadRequestResponse'
+        '401':
+          $ref: '#/components/responses/tfvUnauthorizedResponse'
+        '403':
+          $ref: '#/components/responses/tfvForbiddenResponse'
+        '404':
+          $ref: '#/components/responses/tfvNotFoundResponse'
+        '405':
+          $ref: '#/components/responses/tfvNotAllowedResponse'
+        '429':
+          $ref: '#/components/responses/tfvTooManyRequestsResponse'
+        '500':
+          $ref: '#/components/responses/tfvServerErrorResponse'
+        '503':
+          $ref: '#/components/responses/tfvServiceUnavailableResponse'
+    put:
+      tags:
+        - Toll-Free Verification
+      summary: Update Webhook Subscription
+      description: >-
+        Update an existing webhook subscription (`callbackUrl` and
+        `basicAuthentication` can be updated).
+      operationId: updateWebhookSubscription
+      parameters:
+        - $ref: '#/components/parameters/accountId'
+        - $ref: '#/components/parameters/webhookSubscriptionIdPathParam'
+      requestBody:
+        $ref: '#/components/requestBodies/webhookSubscriptionRequest'
+      responses:
+        '200':
+          $ref: '#/components/responses/updateWebhookSubscriptionResponse'
+        '400':
+          $ref: '#/components/responses/tfvBadRequestResponse'
+        '401':
+          $ref: '#/components/responses/tfvUnauthorizedResponse'
+        '403':
+          $ref: '#/components/responses/tfvForbiddenResponse'
+        '404':
+          $ref: '#/components/responses/tfvNotFoundResponse'
+        '405':
+          $ref: '#/components/responses/tfvNotAllowedResponse'
+        '429':
+          $ref: '#/components/responses/tfvTooManyRequestsResponse'
+        '500':
+          $ref: '#/components/responses/tfvServerErrorResponse'
+        '503':
+          $ref: '#/components/responses/tfvServiceUnavailableResponse'
+    servers: *ref_4
+  /tollFreeVerification/useCases:
+    get:
+      tags:
+        - Toll-Free Verification
+      summary: List Toll-Free Use Cases
+      description: Lists valid toll-free use cases.
+      operationId: listTollFreeUseCases
+      responses:
+        '200':
+          $ref: '#/components/responses/listTollFreeUseCasesResponse'
+        '400':
+          $ref: '#/components/responses/tfvBadRequestResponse'
+        '401':
+          $ref: '#/components/responses/tfvUnauthorizedResponse'
+        '403':
+          $ref: '#/components/responses/tfvForbiddenResponse'
+        '404':
+          $ref: '#/components/responses/tfvNotFoundResponse'
+        '405':
+          $ref: '#/components/responses/tfvNotAllowedResponse'
+        '429':
+          $ref: '#/components/responses/tfvTooManyRequestsResponse'
+        '500':
+          $ref: '#/components/responses/tfvServerErrorResponse'
+        '503':
+          $ref: '#/components/responses/tfvServiceUnavailableResponse'
+    servers: *ref_4
 components:
   schemas:
+    callbackTypeEnum:
+      type: string
+      enum:
+        - message-received
+        - message-sending
+        - message-delivered
+        - message-failed
+      description: >
+        Indicates the type of the callback:
+
+        - `message-received` for inbound callbacks.
+
+        - One of `message-sending`, `message-delivered`, `message-failed` for
+        status callbacks.
+      example: message-delivered
     priorityEnum:
       type: string
       description: |-
@@ -1574,7 +1852,7 @@ components:
           type: string
           format: date-time
           description: The datetime stamp of the message in ISO 8601
-          example: 2022-09-14T18:20:16.000Z
+          example: 2024-12-02T20:15:57.278Z
         segmentCount:
           type: integer
           description: >-
@@ -1695,33 +1973,38 @@ components:
 
             Not supported on MMS.
           example: '2021-02-01T11:29:18-05:00'
-    inboundMessageCallback:
-      description: Inbound Message Callback
+    messageCallback:
+      description: Message Callback Schema
       type: object
       properties:
         time:
           type: string
           format: date-time
-          example: 2016-09-14T18:20:16.000Z
+          example: 2024-12-02T20:15:57.278Z
         type:
-          type: string
-          example: message-received
+          $ref: '#/components/schemas/callbackTypeEnum'
         to:
           type: string
           example: '+15552223333'
         description:
           type: string
-          example: Incoming message received
+          description: A detailed description of the event described by the callback.
+          example: rejected-unallocated-from-number
         message:
-          $ref: '#/components/schemas/inboundMessageCallbackMessage'
+          $ref: '#/components/schemas/messageCallbackMessage'
+        errorCode:
+          type: integer
+          description: Optional error code, applicable only when type is `message-failed`.
+          nullable: true
+          example: 4405
       required:
         - time
         - type
         - to
         - description
         - message
-    inboundMessageCallbackMessage:
-      description: Inbound Message Callback Message Schema
+    messageCallbackMessage:
+      description: Message payload schema within a MessageCallback
       type: object
       properties:
         id:
@@ -1736,7 +2019,7 @@ components:
         time:
           type: string
           format: date-time
-          example: 2016-09-14T18:20:16.000Z
+          example: 2024-12-02T20:15:57.666Z
         segmentCount:
           type: integer
           example: 1
@@ -1760,6 +2043,8 @@ components:
           example: custom string
         media:
           type: array
+          description: Optional media, applicable only for mms
+          nullable: true
           items:
             type: string
             format: uri
@@ -1778,389 +2063,133 @@ components:
         - to
         - from
         - text
-    messageSendingCallback:
+    callbackMethodEnum:
+      type: string
+      nullable: true
+      default: POST
+      enum:
+        - GET
+        - POST
+      description: >-
+        The HTTP method to use to deliver the callback. GET or POST. Default
+        value is POST.
+      example: POST
+    redirectMethodEnum:
+      type: string
+      nullable: true
+      default: POST
+      enum:
+        - GET
+        - POST
+      description: >-
+        The HTTP method to use for the request to `redirectUrl`. GET
+
+        or POST. Default value is POST.<br><br>Not allowed if `state` is
+        `completed`.
+      example: POST
+    recordingStateEnum:
+      type: string
+      enum:
+        - paused
+        - recording
+      description: |-
+        The recording state. Possible values:
+
+        `paused` to pause an active recording
+
+        `recording` to resume a paused recording
+      example: paused
+    callDirectionEnum:
+      type: string
+      enum:
+        - inbound
+        - outbound
+      description: The direction of the call.
+      example: inbound
+    fileFormatEnum:
+      type: string
+      enum:
+        - mp3
+        - wav
+      description: The format that the recording is stored in.
+      example: wav
+    callStateEnum:
+      nullable: true
+      type: string
+      default: active
+      enum:
+        - active
+        - completed
+      description: >-
+        The call state. Possible values:<br>`active` to redirect the
+
+        call (default)<br>`completed` to hang up the call if it is answered,
+        cancel
+
+        it if it is an unanswered outbound call, or reject it if it an
+        unanswered
+
+        inbound call
+      example: completed
+    conferenceStateEnum:
+      nullable: true
+      type: string
+      default: active
+      enum:
+        - active
+        - completed
+      description: >-
+        Setting the conference state to `completed` ends the conference and
+        ejects all members.
+      example: completed
+    machineDetectionModeEnum:
+      type: string
+      default: async
+      enum:
+        - sync
+        - async
+      description: >-
+        The machine detection mode. If set to 'async', the detection
+
+        result will be sent in a 'machineDetectionComplete' callback. If set to
+
+        'sync', the 'answer' callback will wait for the machine detection to
+        complete
+
+        and will include its result.
+      example: async
+    callTranscriptionDetectedLanguageEnum:
+      type: string
+      enum:
+        - en-US
+        - es-US
+        - fr-FR
+      description: The detected language for this transcription.
+      example: en-US
+    callTranscriptionTrackEnum:
+      type: string
+      enum:
+        - inbound
+        - outbound
+      description: Which `track` this transcription is derived from.
+      example: inbound
+    createCall:
       type: object
-      description: Message Sending Callback
+      required:
+        - answerUrl
+        - applicationId
+        - from
+        - to
       properties:
-        time:
-          type: string
-          format: date-time
-          example: 2016-09-14T18:20:16.000Z
-        type:
-          type: string
-          example: message-sending
         to:
           type: string
-          example: '+15552223333'
-        description:
-          type: string
-          example: Message is sending to carrier
-        message:
-          $ref: '#/components/schemas/messageSendingCallbackMessage'
-      required:
-        - time
-        - type
-        - to
-        - description
-        - message
-    messageSendingCallbackMessage:
-      description: Message Sending Callback Message Schema
-      type: object
-      properties:
-        id:
-          type: string
-          example: 1661365814859loidf7mcwd4qacn7
-        owner:
-          type: string
-          example: '+15553332222'
-        applicationId:
-          type: string
-          example: 93de2206-9669-4e07-948d-329f4b722ee2
-        time:
-          type: string
-          format: date-time
-          example: 2016-09-14T18:20:16.000Z
-        segmentCount:
-          type: integer
-          example: 1
-        direction:
-          $ref: '#/components/schemas/messageDirectionEnum'
-        to:
-          uniqueItems: true
-          type: array
-          items:
-            type: string
-          example:
-            - '+15552223333'
-        from:
-          type: string
-          example: '+15553332222'
-        text:
-          type: string
-          example: Hello world
-        tag:
-          type: string
-          example: custom string
-        media:
-          type: array
-          items:
-            type: string
-            format: uri
-          example:
-            - https://dev.bandwidth.com/images/bandwidth-logo.png
-            - https://dev.bandwidth.com/images/github_logo.png
-        priority:
-          $ref: '#/components/schemas/priorityEnum'
-      required:
-        - id
-        - owner
-        - applicationId
-        - time
-        - segmentCount
-        - direction
-        - to
-        - from
-        - text
-        - media
-    messageDeliveredCallback:
-      description: Message Delivered Callback
-      type: object
-      properties:
-        time:
-          type: string
-          format: date-time
-          example: 2016-09-14T18:20:16.000Z
-        type:
-          type: string
-          example: message-delivered
-        to:
-          type: string
-          example: '+15552223333'
-        description:
-          type: string
-          example: Message delivered to carrier.
-        message:
-          $ref: '#/components/schemas/messageDeliveredCallbackMessage'
-      required:
-        - time
-        - type
-        - to
-        - description
-        - message
-    messageDeliveredCallbackMessage:
-      description: Message Delivered Callback Message Schema
-      type: object
-      properties:
-        id:
-          type: string
-          example: 1661365814859loidf7mcwd4qacn7
-        owner:
-          type: string
-          example: '+15553332222'
-        applicationId:
-          type: string
-          example: 93de2206-9669-4e07-948d-329f4b722ee2
-        time:
-          type: string
-          format: date-time
-          example: 2016-09-14T18:20:16.000Z
-        segmentCount:
-          type: integer
-          example: 1
-        direction:
-          $ref: '#/components/schemas/messageDirectionEnum'
-        to:
-          uniqueItems: true
-          type: array
-          items:
-            type: string
-          example:
-            - '+15552223333'
-        from:
-          type: string
-          example: '+15553332222'
-        text:
-          type: string
-          example: Hello world
-        tag:
-          type: string
-          example: custom string
-        media:
-          type: array
-          items:
-            type: string
-            format: uri
-          example:
-            - https://dev.bandwidth.com/images/bandwidth-logo.png
-            - https://dev.bandwidth.com/images/github_logo.png
-        priority:
-          $ref: '#/components/schemas/priorityEnum'
-      required:
-        - id
-        - owner
-        - applicationId
-        - time
-        - segmentCount
-        - direction
-        - to
-        - from
-        - text
-        - tag
-    messageFailedCallback:
-      description: Message Failed Callback
-      type: object
-      properties:
-        time:
-          type: string
-          format: date-time
-          example: 2016-09-14T18:20:16.000Z
-        type:
-          type: string
-          example: message-failed
-        to:
-          type: string
-          example: '+15552223333'
-        description:
-          type: string
-          example: rejected-unallocated-from-number
-        message:
-          $ref: '#/components/schemas/messageFailedCallbackMessage'
-        errorCode:
-          type: integer
-          example: 9902
-      required:
-        - time
-        - type
-        - to
-        - description
-        - message
-        - errorCode
-    messageFailedCallbackMessage:
-      description: Message Failed Callback Message Schema
-      type: object
-      properties:
-        id:
-          type: string
-          example: 1661365814859loidf7mcwd4qacn7
-        owner:
-          type: string
-          example: '+15553332222'
-        applicationId:
-          type: string
-          example: 93de2206-9669-4e07-948d-329f4b722ee2
-        time:
-          type: string
-          format: date-time
-          example: 2016-09-14T18:20:16.000Z
-        segmentCount:
-          type: integer
-          example: 1
-        direction:
-          $ref: '#/components/schemas/messageDirectionEnum'
-        to:
-          uniqueItems: true
-          type: array
-          items:
-            type: string
-          example:
-            - '+15552223333'
-        from:
-          type: string
-          example: '+15553332222'
-        text:
-          type: string
-          example: Hello world
-        tag:
-          type: string
-          example: custom string
-        media:
-          type: array
-          items:
-            type: string
-            format: uri
-          example:
-            - https://dev.bandwidth.com/images/bandwidth-logo.png
-            - https://dev.bandwidth.com/images/github_logo.png
-        priority:
-          $ref: '#/components/schemas/priorityEnum'
-      required:
-        - id
-        - owner
-        - applicationId
-        - time
-        - segmentCount
-        - direction
-        - to
-        - from
-        - text
-        - tag
-    callbackMethodEnum:
-      type: string
-      nullable: true
-      default: POST
-      enum:
-        - GET
-        - POST
-      description: >-
-        The HTTP method to use to deliver the callback. GET or POST. Default
-        value is POST.
-      example: POST
-    redirectMethodEnum:
-      type: string
-      nullable: true
-      default: POST
-      enum:
-        - GET
-        - POST
-      description: >-
-        The HTTP method to use for the request to `redirectUrl`. GET
-
-        or POST. Default value is POST.<br><br>Not allowed if `state` is
-        `completed`.
-      example: POST
-    recordingStateEnum:
-      type: string
-      enum:
-        - paused
-        - recording
-      description: |-
-        The recording state. Possible values:
-
-        `paused` to pause an active recording
-
-        `recording` to resume a paused recording
-      example: paused
-    callDirectionEnum:
-      type: string
-      enum:
-        - inbound
-        - outbound
-      description: The direction of the call.
-      example: inbound
-    fileFormatEnum:
-      type: string
-      enum:
-        - mp3
-        - wav
-      description: The format that the recording is stored in.
-      example: wav
-    callStateEnum:
-      nullable: true
-      type: string
-      default: active
-      enum:
-        - active
-        - completed
-      description: >-
-        The call state. Possible values:<br>`active` to redirect the
-
-        call (default)<br>`completed` to hang up the call if it is answered,
-        cancel
-
-        it if it is an unanswered outbound call, or reject it if it an
-        unanswered
-
-        inbound call
-      example: completed
-    conferenceStateEnum:
-      nullable: true
-      type: string
-      default: active
-      enum:
-        - active
-        - completed
-      description: >-
-        Setting the conference state to `completed` ends the conference and
-        ejects all members.
-      example: completed
-    machineDetectionModeEnum:
-      type: string
-      default: async
-      enum:
-        - sync
-        - async
-      description: >-
-        The machine detection mode. If set to 'async', the detection
-
-        result will be sent in a 'machineDetectionComplete' callback. If set to
-
-        'sync', the 'answer' callback will wait for the machine detection to
-        complete
-
-        and will include its result.
-      example: async
-    callTranscriptionDetectedLanguageEnum:
-      type: string
-      enum:
-        - en-US
-        - es-US
-        - fr-FR
-      description: The detected language for this transcription.
-      example: en-US
-    callTranscriptionTrackEnum:
-      type: string
-      enum:
-        - inbound
-        - outbound
-      description: Which `track` this transcription is derived from.
-      example: inbound
-    createCall:
-      type: object
-      required:
-        - answerUrl
-        - applicationId
-        - from
-        - to
-      properties:
-        to:
-          type: string
-          description: >-
-            The destination to call (must be an E.164 formatted number
-
-            (e.g. `+15555551212`) or a SIP URI (e.g.
-            `sip:user@server.example`)).
-          example: '+19195551234'
-        from:
+          description: >-
+            The destination to call (must be an E.164 formatted number
+
+            (e.g. `+15555551212`) or a SIP URI (e.g.
+            `sip:user@server.example`)).
+          example: '+19195551234'
+        from:
           type: string
           description: >-
             A Bandwidth phone number on your account the call should come
@@ -4621,31 +4650,665 @@ components:
           example: (919) 555-1234
         Country:
           type: string
-          description: The country of the telephone number.
-          example: US
-        Line Type:
+          description: The country of the telephone number.
+          example: US
+        Line Type:
+          type: string
+          description: The line type of the telephone number.
+          example: Mobile
+        Line Provider:
+          type: string
+          description: The messaging service provider of the telephone number.
+          example: Verizon Wireless
+        Mobile Country Code:
+          type: string
+          description: The first half of the Home Network Identity (HNI).
+          example: '310'
+        Mobile Network Code:
+          type: string
+          description: The second half of the HNI.
+          example: '010'
+    tnLookupRequestError:
+      type: object
+      properties:
+        message:
+          type: string
+          description: A description of what validation error occurred.
+          example: example error message
+    accountId1:
+      type: string
+      description: User's account ID.
+      example: '1234567'
+    tfPhoneNumber:
+      type: string
+      description: Toll-free telephone number in E.164 format.
+      minLength: 12
+      maxLength: 12
+      nullable: false
+      pattern: ^\+1(800|833|844|855|866|877|888)[2-9]\d{6}$
+      example: '+18005555555'
+    tfvWebhookErrors:
+      type: array
+      description: Details of the errors that were encountered when processing the request.
+      items:
+        type: string
+        example: 'optInWorkflowImageURLs: Entries must be a valid array of objects.'
+    tfvCallbackStatusEnum:
+      type: string
+      enum:
+        - VERIFIED
+        - UNVERIFIED
+      example: VERIFIED
+    tfvUnverifiedStatus:
+      type: string
+      default: UNVERIFIED
+      example: UNVERIFIED
+    declineReasonDescription:
+      type: string
+      description: Explanation for why a verification request was declined.
+      nullable: false
+      example: >-
+        Invalid Information - Can't Validate URL - Website is not accessible /
+        not available
+    denialStatusCode:
+      description: Reason code for denial.
+      type: integer
+      example: 511
+    resubmitAllowed:
+      description: >-
+        Whether a Toll-Free Verification request qualifies for resubmission via
+        PUT.
+      example: true
+      type: boolean
+    additionalDenialReason:
+      properties:
+        statusCode:
+          $ref: '#/components/schemas/denialStatusCode'
+        reason:
+          $ref: '#/components/schemas/declineReasonDescription'
+        resubmitAllowed:
+          $ref: '#/components/schemas/resubmitAllowed'
+      required:
+        - statusCode
+        - reason
+        - resubmitAllowed
+      type: object
+    internalTicketNumber:
+      type: string
+      format: uuid
+      description: >-
+        Unique identifier (UUID) generated by Bandwidth to assist in tracking
+        the verification status of a toll-free number - included in all webhook
+        payloads.
+      example: acde070d-8c4c-4f0d-9d8a-162843c10333
+    internalTicketNumberForWebhook:
+      type: string
+      format: uuid
+      description: >-
+        Unique identifier (UUID) generated by Bandwidth to assist in tracking
+        the verification status of a toll-free number.
+      example: acde070d-8c4c-4f0d-9d8a-162843c10333
+    businessContactPhoneNumber:
+      description: Contact telephone number
+      type: string
+      minLength: 1
+      maxLength: 500
+      nullable: false
+      example: '+19192654500'
+    verificationRequest:
+      type: object
+      required:
+        - businessAddress
+        - businessContact
+        - messageVolume
+        - phoneNumbers
+        - useCase
+        - useCaseSummary
+        - productionMessageContent
+        - optInWorkflow
+      properties:
+        businessAddress:
+          $ref: '#/components/schemas/address'
+        businessContact:
+          $ref: '#/components/schemas/contact'
+        messageVolume:
+          type: integer
+          description: Estimated monthly volume of messages from the toll-free number.
+          minimum: 10
+          maximum: 10000000
+          example: 10000
+        phoneNumbers:
+          type: array
+          minItems: 1
+          maxItems: 10
+          items:
+            $ref: '#/components/schemas/tfPhoneNumber'
+        useCase:
+          $ref: '#/components/schemas/useCase'
+        useCaseSummary:
+          type: string
+          description: A general idea of the use case and customer.
+          minLength: 1
+          maxLength: 500
+          nullable: false
+        productionMessageContent:
+          type: string
+          description: Example of message content.
+          minLength: 1
+          maxLength: 500
+          nullable: false
+        optInWorkflow:
+          $ref: '#/components/schemas/optInWorkflow'
+        additionalInformation:
+          type: string
+          description: Any additional information.
+          minLength: 0
+          maxLength: 500
+          nullable: true
+        isvReseller:
+          $ref: '#/components/schemas/isvReseller'
+    verificationUpdateRequest:
+      type: object
+      required:
+        - businessAddress
+        - businessContact
+        - messageVolume
+        - useCase
+        - useCaseSummary
+        - productionMessageContent
+        - optInWorkflow
+      properties:
+        businessAddress:
+          $ref: '#/components/schemas/address'
+        businessContact:
+          $ref: '#/components/schemas/contact'
+        messageVolume:
+          type: integer
+          description: Estimated monthly volume of messages from the toll-free number.
+          minimum: 10
+          maximum: 10000000
+          example: 10000
+        useCase:
+          $ref: '#/components/schemas/useCase'
+        useCaseSummary:
+          type: string
+          description: A general idea of the use case and customer.
+          minLength: 0
+          maxLength: 500
+          nullable: false
+        productionMessageContent:
+          type: string
+          description: Example of message content.
+          minLength: 0
+          maxLength: 500
+          nullable: false
+        optInWorkflow:
+          $ref: '#/components/schemas/optInWorkflow'
+        additionalInformation:
+          type: string
+          description: Any additional information.
+          minLength: 0
+          maxLength: 500
+          nullable: true
+        isvReseller:
+          $ref: '#/components/schemas/isvReseller'
+    tfvBasicAuthentication:
+      type: object
+      properties:
+        username:
+          type: string
+          maxLength: 100
+        password:
+          type: string
+          maxLength: 200
+      required:
+        - username
+        - password
+    webhookSubscriptionRequestSchema:
+      type: object
+      properties:
+        basicAuthentication:
+          $ref: '#/components/schemas/tfvBasicAuthentication'
+        callbackUrl:
+          $ref: '#/components/schemas/webhookUrl'
+        sharedSecretKey:
+          $ref: '#/components/schemas/sharedSecretKey'
+      required:
+        - callbackUrl
+    failureWebhook:
+      type: object
+      properties:
+        accountId:
+          $ref: '#/components/schemas/accountId1'
+        phoneNumber:
+          $ref: '#/components/schemas/tfPhoneNumber'
+        errorCode:
+          type: string
+          description: >-
+            An error code indicating what error was encountered. This code can
+            be interpreted as an HTTP status code in regards to the error that
+            was encountered.
+          example: '400'
+        errorDescription:
+          type: string
+          description: A description of the error that was encountered.
+          example: cannot process request.
+        errors:
+          $ref: '#/components/schemas/tfvWebhookErrors'
+        internalTicketNumber:
+          $ref: '#/components/schemas/internalTicketNumberForWebhook'
+    verificationDenialWebhook:
+      type: object
+      properties:
+        accountId:
+          $ref: '#/components/schemas/accountId1'
+        additionalDenialReasons:
+          description: >-
+            An optional list of denial reasons in addition to
+            declineReasonDescription when multiple reasons apply.
+          items:
+            $ref: '#/components/schemas/additionalDenialReason'
+          example:
+            - statusCode: 512
+              reason: Reason A
+              resubmitAllowed: true
+            - statusCode: 513
+              reason: Reason B
+              resubmitAllowed: true
+          type: array
+        declineReasonDescription:
+          $ref: '#/components/schemas/declineReasonDescription'
+        denialStatusCode:
+          $ref: '#/components/schemas/denialStatusCode'
+        internalTicketNumber:
+          $ref: '#/components/schemas/internalTicketNumberForWebhook'
+        phoneNumber:
+          $ref: '#/components/schemas/tfPhoneNumber'
+        resubmitAllowed:
+          $ref: '#/components/schemas/resubmitAllowed'
+        status:
+          $ref: '#/components/schemas/tfvUnverifiedStatus'
+    verificationWebhook:
+      type: object
+      properties:
+        accountId:
+          $ref: '#/components/schemas/accountId1'
+        phoneNumber:
+          $ref: '#/components/schemas/tfPhoneNumber'
+        status:
+          $ref: '#/components/schemas/tfvCallbackStatusEnum'
+        internalTicketNumber:
+          $ref: '#/components/schemas/internalTicketNumberForWebhook'
+    tfvSubmissionWrapper:
+      type: object
+      properties:
+        submission:
+          $ref: '#/components/schemas/verificationUpdateRequest'
+    address:
+      type: object
+      nullable: false
+      required:
+        - name
+        - addr1
+        - city
+        - state
+        - zip
+        - url
+      properties:
+        name:
+          type: string
+          description: The name of the business using the toll-free number.
+          minLength: 1
+          maxLength: 500
+          nullable: false
+          example: Bandwidth Inc.
+        addr1:
+          type: string
+          description: The address of the business using the toll-free number.
+          minLength: 1
+          maxLength: 500
+          nullable: false
+          example: 2230 Bandmate Way
+        addr2:
+          type: string
+          description: The address of the business using the toll-free number.
+          minLength: 0
+          maxLength: 500
+          nullable: true
+        city:
+          type: string
+          description: The city of the business using the toll-free number.
+          minLength: 1
+          maxLength: 500
+          nullable: false
+          example: Raleigh
+        state:
+          type: string
+          description: The state of the business using the toll-free number.
+          minLength: 1
+          maxLength: 500
+          nullable: false
+          example: NC
+        zip:
+          type: string
+          description: The zip of the business using the toll-free number.
+          nullable: false
+          example: '27606'
+          pattern: '[- A-Za-z0-9]{0,500}'
+        url:
+          type: string
+          format: url
+          description: The website of the business using the toll-free number.
+          minLength: 1
+          maxLength: 500
+          nullable: false
+          example: https://www.example.com/path/to/resource
+    optInWorkflow:
+      type: object
+      nullable: false
+      required:
+        - description
+        - imageUrls
+      properties:
+        description:
+          type: string
+          minLength: 1
+          maxLength: 500
+          nullable: false
+          example: Opt In Flow
+        imageUrls:
+          type: array
+          items:
+            type: string
+            minLength: 1
+            maxLength: 500
+            nullable: false
+            example: https://www.example.com/path/to/resource
+            pattern: >-
+              ^$|(https?:\/\/)?(www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,253}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#()?&//=]*)
+    isvReseller:
+      type: string
+      description: ISV name.
+      minLength: 0
+      maxLength: 500
+      nullable: true
+      example: Test ISV
+    contact:
+      type: object
+      nullable: false
+      required:
+        - firstName
+        - lastName
+        - email
+        - phoneNumber
+      properties:
+        firstName:
+          type: string
+          description: The first name of the business contact using the toll-free number.
+          minLength: 1
+          maxLength: 500
+          nullable: false
+          example: John
+        lastName:
+          type: string
+          description: The last name of the business contact using the toll-free number.
+          minLength: 1
+          maxLength: 500
+          nullable: false
+          example: Doe
+        email:
+          $ref: '#/components/schemas/email'
+        phoneNumber:
+          $ref: '#/components/schemas/businessContactPhoneNumber'
+    email:
+      type: string
+      format: email
+      minLength: 0
+      maxLength: 500
+      nullable: false
+      pattern: >-
+        ^(?:[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-z0-9-]*[a-z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])$
+      example: foo@bar.com
+    useCases:
+      type: array
+      items:
+        type: string
+      example:
+        - 2FA
+        - App Notifications
+        - Appointments
+        - Auctions
+        - Auto Repair Services
+        - Bank Transfers
+        - Billing
+        - Booking Confirmations
+        - Business Updates
+        - COVID-19 Alerts
+    useCase:
+      type: string
+      description: The category of the use case.
+      minLength: 0
+      maxLength: 500
+      example: 2FA
+    webhookSubscriptionsListBody:
+      description: >-
+        A list of all webhook subscriptions registered for this account ID for
+        this particular feature (unpaginated).
+      type: object
+      required:
+        - data
+      properties:
+        links:
+          $ref: '#/components/schemas/linksObject'
+        errors:
+          type: array
+          items:
+            $ref: '#/components/schemas/error'
+        data:
+          items:
+            $ref: '#/components/schemas/webhookSubscription'
+          type: array
+    linksObject:
+      type: object
+      properties:
+        first:
+          description: The first (or only) page of results matching the query.
+          type: string
+        next:
+          description: >-
+            If more results exist than specified by 'size', this link returns
+            the next page of 'size' results.
+          type: string
+        previous:
+          description: >-
+            If the results are more than one page, this link returns the
+            previous page of 'size' results.
+          type: string
+        last:
+          description: >-
+            If more results exist than specified by 'size', this link return the
+            last page of result.
+          type: string
+    error:
+      type: object
+      properties:
+        code:
+          type: integer
+        description:
+          type: string
+        telephoneNumbers:
+          type: array
+          items:
+            $ref: '#/components/schemas/telephoneNumber'
+    telephoneNumber:
+      type: object
+      properties:
+        telephoneNumber:
+          description: Simple Telephone Number.
+          type: string
+    webhookSubscriptionTypeEnum:
+      type: string
+      enum:
+        - TOLLFREE_VERIFICATION_STATUS
+        - MESSAGING_PORTOUT_APPROVAL_STATUS
+      example: TOLLFREE_VERIFICATION_STATUS
+    webhookSubscription:
+      description: >-
+        Information about a webhook that Bandwidth should send upon the
+        completion of event customer has subscribed to.
+      type: object
+      required:
+        - callbackUrl
+      properties:
+        id:
+          type: string
+          example: 7hICGStfAfeGxEq3N0lQwO
+        accountId:
           type: string
-          description: The line type of the telephone number.
-          example: Mobile
-        Line Provider:
+          example: '1234567'
+        callbackUrl:
+          $ref: '#/components/schemas/webhookUrl'
+        type:
+          $ref: '#/components/schemas/webhookSubscriptionTypeEnum'
+        basicAuthentication:
+          description: >-
+            Basic authentication credentials are not required, but if present,
+            both username and password must be provided.
+          type: object
+          required:
+            - username
+            - password
+          properties:
+            username:
+              type: string
+              maxLength: 100
+            password:
+              type: string
+              maxLength: 200
+        createdDate:
           type: string
-          description: The messaging service provider of the telephone number.
-          example: Verizon Wireless
-        Mobile Country Code:
+          format: date-time
+          example: '2023-05-15T13:56:39.965Z'
+        modifiedDate:
           type: string
-          description: The first half of the Home Network Identity (HNI).
-          example: '310'
-        Mobile Network Code:
+          format: date-time
+          example: '2023-05-15T13:56:39.965Z'
+    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.
+      type: string
+      format: url
+      minLength: 0
+      maxLength: 2000
+      nullable: true
+      example: https://www.example.com/path/to/resource
+      pattern: >-
+        ^$|(https?:\/\/)?(www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,253}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#()?&//=]*)
+    tfvError:
+      description: A generic error object.
+      properties:
+        type:
           type: string
-          description: The second half of the HNI.
-          example: '010'
-    tnLookupRequestError:
+          example: Error Type
+        description:
+          type: string
+          example: Error Message
+        errors:
+          type: object
+          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
+    tfvStatus:
       type: object
       properties:
-        message:
+        phoneNumber:
+          $ref: '#/components/schemas/tfPhoneNumber'
+        status:
+          $ref: '#/components/schemas/tfvStatusEnum'
+        internalTicketNumber:
+          $ref: '#/components/schemas/internalTicketNumber'
+        declineReasonDescription:
+          $ref: '#/components/schemas/declineReasonDescription'
+        resubmitAllowed:
+          $ref: '#/components/schemas/resubmitAllowed'
+        createdDateTime:
+          type: string
+          description: Date and time the verification request was created.
+          format: date-time
+          example: '2021-06-08T06:45:13.0Z'
+        modifiedDateTime:
           type: string
-          description: A description of what validation error occurred.
-          example: example error message
+          description: Date and time the verification request was last modified.
+          format: date-time
+          example: '2021-06-08T06:45:13.0Z'
+        submission:
+          $ref: '#/components/schemas/tfvSubmissionInfo'
+    tfvSubmissionInfo:
+      type: object
+      properties:
+        businessAddress:
+          $ref: '#/components/schemas/address'
+        businessContact:
+          $ref: '#/components/schemas/contact'
+        messageVolume:
+          type: integer
+          description: Estimated monthly volume of messages from the toll-free number.
+          minimum: 10
+          maximum: 10000000
+          example: 10000
+        useCase:
+          $ref: '#/components/schemas/useCase'
+        useCaseSummary:
+          type: string
+          description: A general idea of the use case and customer.
+          minLength: 0
+          maxLength: 500
+          nullable: false
+          example: Text summarizing the use case for the toll-free number
+        productionMessageContent:
+          type: string
+          description: Example of message content.
+          minLength: 0
+          maxLength: 500
+          nullable: false
+          example: Production message content
+        optInWorkflow:
+          $ref: '#/components/schemas/optInWorkflow'
+        additionalInformation:
+          type: string
+          description: Any additional information.
+          minLength: 0
+          maxLength: 500
+          nullable: true
+          example: Any additional information
+        isvReseller:
+          $ref: '#/components/schemas/isvReseller'
+    tfvStatusEnum:
+      type: string
+      enum:
+        - VERIFIED
+        - UNVERIFIED
+        - PENDING
+        - PARTIALLY_VERIFIED
+        - INVALID_STATUS
+      example: VERIFIED
+    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
   responses:
     createMessageResponse:
       description: Accepted
@@ -5096,6 +5759,120 @@ components:
               summary: Example Internal Server Error Error
               value:
                 message: Request has not been passed further.
+    getTollFreeVerificationStatusResponse:
+      description: OK
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/tfvStatus'
+    listWebhookSubscriptionsResponse:
+      description: OK
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/webhookSubscriptionsListBody'
+    createWebhookSubscriptionResponse:
+      description: Created
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/webhookSubscription'
+    updateWebhookSubscriptionResponse:
+      description: OK
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/webhookSubscription'
+    listTollFreeUseCasesResponse:
+      description: OK
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/useCases'
+    tfvBadRequestResponse:
+      description: Bad Request
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/tfvError'
+          example:
+            description: Cannot process request.
+            type: bad request
+    tfvPostBadRequestResponse:
+      description: Bad Request
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/tfvError'
+          example:
+            description: cannot process request.
+            errors:
+              businessName: Business name is required.
+              businessContactEmail: Business contact email is not a valid email address.
+              optInWorkflowImageURLs: Entries must be a valid array of objects.
+    tfvUnauthorizedResponse:
+      description: Unauthorized
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/tfvError'
+          example:
+            description: Client is providing incorrect or invalid credentials.
+            type: unauthorized
+    tfvForbiddenResponse:
+      description: Forbidden
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/tfvError'
+          example:
+            description: Client is not authorized for the action.
+            type: forbidden
+    tfvNotFoundResponse:
+      description: Cannot find the requested resource.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/tfvError'
+          example:
+            description: Cannot find the requested resource.
+            type: Not Found
+    tfvNotAllowedResponse:
+      description: Method Not Allowed
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/tfvError'
+          example:
+            description: Method is not allowed.
+            type: Method Not Allowed
+    tfvTooManyRequestsResponse:
+      description: Too Many Requests
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/tfvError'
+          example:
+            description: Throttling error. Too many requests.
+            type: Too Many Requests
+    tfvServerErrorResponse:
+      description: Internal Server Error
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/tfvError'
+          example:
+            description: Internal Server Error.
+            type: Internal Server Error
+    tfvServiceUnavailableResponse:
+      description: Service Unavailable
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/tfvError'
+          example:
+            description: Service Unavailable Error.
+            type: Service Unavailable
   parameters:
     accountId:
       in: path
@@ -5463,6 +6240,333 @@ components:
         type: string
       description: The phone number lookup request ID from Bandwidth.
       example: 004223a0-8b17-41b1-bf81-20732adf5590
+    tfPhoneNumberPathParam:
+      in: path
+      name: phoneNumber
+      required: true
+      schema:
+        $ref: '#/components/schemas/tfPhoneNumber'
+      description: Valid Toll-Free telephone number in E.164 format.
+      example: '+18885555555'
+    webhookSubscriptionIdPathParam:
+      in: path
+      name: id
+      required: true
+      schema:
+        type: string
+      description: Webhook subscription ID
+      example: 7bt57JcsVYJrN9K1OcV1Nu
+  examples:
+    smsMessageReceivedCallbackExample:
+      summary: An example of a sms message-received callback body.
+      value:
+        time: '2025-01-06T15:43:35.502180Z'
+        type: message-received
+        to: '+12345678902'
+        description: Incoming message received
+        message:
+          id: 14762070468292kw2fuqty55yp2b2
+          owner: '+12345678902'
+          applicationId: 93de2206-9669-4e07-948d-329f4b722ee2
+          time: '2025-01-06T15:43:34.000000Z'
+          segmentCount: 1
+          direction: in
+          to:
+            - '+12345678902'
+          from: '+12345678901'
+          text: Hey, check out this SMS!
+    mmsMessageReceivedCallbackExample:
+      summary: An example of a mms message-received callback body.
+      value:
+        time: '2024-09-14T18:20:45.160744Z'
+        type: message-received
+        to: '+12345678902'
+        description: Incoming message received
+        message:
+          id: 14762070468292kw2fuqty55yp2b2
+          owner: '+12345678902'
+          applicationId: 93de2206-9669-4e07-948d-329f4b722ee2
+          time: '2024-09-14T18:20:45.160744Z'
+          segmentCount: 1
+          direction: in
+          to:
+            - '+12345678902'
+            - '+12345678903'
+          from: '+12345678901'
+          text: Hey, check out the MMS!
+          media:
+            - >-
+              https://messaging.bandwidth.com/api/v2/users/9900902/media/14762070468292kw2fuqty55yp2b2/0/bw.png
+    messageSendingCallbackExample:
+      summary: An example of a message-sending callback body.
+      value:
+        time: '2024-06-25T18:42:36.979456Z'
+        type: message-sending
+        to: '+15554443333'
+        description: Message is sending to carrier.
+        message:
+          id: 1593110555875xo7watq5px6rbe5d
+          owner: '+15552221111'
+          applicationId: cfd4fb83-7531-4acc-b471-42d0bb76a65c
+          time: '2024-06-25T18:42:35.876906Z'
+          segmentCount: 1
+          direction: out
+          to:
+            - '+15554443333'
+          from: '+15552221111'
+          text: ''
+          media:
+            - https://dev.bandwidth.com/images/bandwidth-logo.png
+          tag: your tag here
+    smsMessageDeliveredCallbackExample:
+      summary: An example of a sms message-delivered callback body.
+      value:
+        type: message-delivered
+        time: '2024-09-14T18:20:11.160744Z'
+        description: Message delivered to carrier.
+        to: '+12345678902'
+        message:
+          id: 14762070468292kw2fuqty55yp2b2
+          time: '2024-09-14T18:20:11.160744Z'
+          to:
+            - '+12345678902'
+          from: '+12345678901'
+          text: ''
+          applicationId: 93de2206-9669-4e07-948d-329f4b722ee2
+          owner: '+12345678902'
+          direction: out
+          segmentCount: 1
+    mmsMessageDeliveredCallbackExample:
+      summary: An example of a mms message-delivered callback body.
+      value:
+        type: message-delivered
+        time: '2024-09-14T18:20:24.160544Z'
+        description: Message delivered to carrier.
+        to: '+12345678902'
+        message:
+          id: 14762070468292kw2fuqty55yp2b2
+          time: '2024-09-14T18:20:24.160544Z'
+          to:
+            - '+12345678902'
+          from: '+12345678901'
+          text: ''
+          applicationId: 93de2206-9669-4e07-948d-329f4b722ee2
+          owner: '+12345678902'
+          direction: out
+          segmentCount: 1
+          media:
+            - https://dev.bandwidth.com/images/bandwidth-logo.png
+    groupMmsMessageDeliveredCallbackExample:
+      summary: An example of a group mms message-delivered callback body.
+      value:
+        type: message-delivered
+        time: '2024-09-14T18:20:17.160544Z'
+        description: Message delivered to carrier.
+        to: '+12345678902'
+        message:
+          id: 14762070468292kw2fuqty55yp2b2
+          time: '2024-09-14T18:20:17.160544Z'
+          to:
+            - '+12345678902'
+            - '+12345678903'
+          from: '+12345678901'
+          text: ''
+          applicationId: 93de2206-9669-4e07-948d-329f4b722ee2
+          owner: '+12345678902'
+          direction: out
+          segmentCount: 1
+    messageFailedCallbackExample:
+      summary: An example of a message-failed callback body.
+      value:
+        type: message-failed
+        time: '2024-12-18T16:51:27.704450Z'
+        description: forbidden to country
+        to: '+52345678903'
+        errorCode: 4432
+        message:
+          id: 14762070468292kw2fuqty55yp2b2
+          time: '2024-12-18T16:51:27.704450Z'
+          to:
+            - '+12345678902'
+            - '+52345678903'
+          from: '+12345678901'
+          text: ''
+          applicationId: 93de2206-9669-4e07-948d-329f4b722ee2
+          media:
+            - https://dev.bandwidth.com/images/bandwidth-logo.png
+          owner: '+12345678901'
+          direction: out
+          segmentCount: 1
+    createCallResponseExample:
+      summary: Example of a createCall Response
+      value:
+        applicationId: 04e88489-df02-4e34-a0ee-27a91849555f
+        accountId: '9900000'
+        callId: c-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85
+        to: '+19195551234'
+        from: '+19195554312'
+        enqueuedTime: '2022-06-16T13:15:07.160Z'
+        callUrl: >-
+          https://voice.bandwidth.com/api/v2/accounts/9900000/calls/c-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85
+        callTimeout: 30
+        callbackTimeout: 15
+        tag: My custom tag value
+        answerMethod: POST
+        answerUrl: https://myServer.example/bandwidth/webhooks/answer
+        answerFallbackMethod: POST
+        answerFallbackUrl: https://myServer.example/bandwidth/webhooks/answerFallback
+        disconnectMethod: POST
+        disconnectUrl: https://myServer.example/bandwidth/webhooks/disconnect
+        username: mySecretUsername
+        password: '*****'
+        fallbackUsername: mySecretUsername
+        fallbackPassword: '*****'
+        priority: 5
+    listConferencesResponseExample:
+      summary: Example of a listConferences Response
+      value:
+        - id: conf-fe23a767-a75a5b77-20c5-4cca-b581-cbbf0776eca9
+          name: my-conference-name
+          createdTime: '2022-06-17T22:19:40.375Z'
+          completedTime: '2022-06-17T22:20:00.000Z'
+          conferenceEventUrl: https://myServer.example/bandwidth/webhooks/conferenceEvent
+          conferenceEventMethod: POST
+          tag: my custom tag
+    voiceBadRequestErrorExample:
+      summary: Example of a Bad Request (400) Error
+      value:
+        type: validation
+        description: 'Invalid answerUrl: only http and https are allowed.'
+    voiceUnauthorizedErrorExample:
+      summary: Example of an Unauthorized (401) Error
+      value:
+        type: validation
+        description: 'Invalid answerUrl: only http and https are allowed.'
+    voiceForbiddenErrorExample:
+      summary: Example of a Forbidden (403) Error
+      value:
+        type: validation
+        description: 'Invalid answerUrl: only http and https are allowed.'
+    voiceNotFoundErrorExample:
+      summary: Example of a Not Found (404) Error
+      value:
+        type: validation
+        description: 'Invalid answerUrl: only http and https are allowed.'
+    voiceNotAllowedErrorExample:
+      summary: Example of a Not Allowed (405) Error
+      value:
+        type: validation
+        description: 'Invalid answerUrl: only http and https are allowed.'
+    voiceConflictErrorExample:
+      summary: Example of a Conflict (409) Error
+      value:
+        type: validation
+        description: 'Invalid answerUrl: only http and https are allowed.'
+    voiceUnsupportedMediaTypeErrorExample:
+      summary: Example of an Unsupported Media Type (415) Error
+      value:
+        type: validation
+        description: 'Invalid answerUrl: only http and https are allowed.'
+    voiceTooManyRequestsErrorExample:
+      summary: Example of a Too Many Requests (429) Error
+      value:
+        type: validation
+        description: 'Invalid answerUrl: only http and https are allowed.'
+    voiceInternalServerErrorExample:
+      summary: Example of an Internal Server (500) Error
+      value:
+        type: validation
+        description: 'Invalid answerUrl: only http and https are allowed.'
+    singleNumberRequestExample:
+      summary: Example Number Lookup Request for One Number
+      value:
+        tns:
+          - '+19195551234'
+    multipleNumberRequestExample:
+      summary: Example Number Lookup Request for Multiple Numbers
+      value:
+        tns:
+          - '+19195551234'
+          - '+19195554321'
+    lookupInProgressExample:
+      summary: Example Lookup In Progress Response
+      value:
+        requestId: 004223a0-8b17-41b1-bf81-20732adf5590
+        status: IN_PROGRESS
+    lookupFailedExample:
+      summary: Example Lookup Failed Response
+      value:
+        requestId: 004223a0-8b17-41b1-bf81-20732adf5590
+        status: FAILED
+        failedTelephoneNumbers:
+          - '+191955512345'
+    lookupSingleNumberCompleteExample:
+      summary: Example Single Number Lookup Complete Response
+      value:
+        requestId: 004223a0-8b17-41b1-bf81-20732adf5590
+        status: COMPLETE
+        result:
+          - Response Code: 0
+            Message: NOERROR
+            E.164 Format: '+19195551234'
+            Formatted: (919) 555-1234
+            Country: US
+            Line Type: Mobile
+            Line Provider: Verizon Wireless
+            Mobile Country Code: '310'
+            Mobile Network Code: '010'
+    lookupMultipleNumbersCompleteExample:
+      summary: Example Multiple Numbers Lookup Complete Response
+      value:
+        requestId: 004223a0-8b17-41b1-bf81-20732adf5590
+        status: COMPLETE
+        result:
+          - Response Code: 0
+            Message: NOERROR
+            E.164 Format: '+19195551234'
+            Formatted: (919) 555-1234
+            Country: US
+            Line Type: Mobile
+            Line Provider: Verizon Wireless
+            Mobile Country Code: '310'
+            Mobile Network Code: '010'
+          - Response Code: 0
+            Message: NOERROR
+            E.164 Format: '+19195554321'
+            Formatted: (919) 555-4321
+            Country: US
+            Line Type: Mobile
+            Line Provider: T-Mobile USA
+            Mobile Country Code: '310'
+            Mobile Network Code: '160'
+    lookupMultipleNumbersPartialCompleteExample:
+      summary: Example Multiple Numbers Lookup Partial Complete Response
+      value:
+        requestId: 004223a0-8b17-41b1-bf81-20732adf5590
+        status: PARTIAL_COMPLETE
+        result:
+          - Response Code: 0
+            Message: NOERROR
+            E.164 Format: '+19195551234'
+            Formatted: (919) 555-1234
+            Country: US
+            Line Type: Mobile
+            Line Provider: Verizon Wireless
+            Mobile Country Code: '310'
+            Mobile Network Code: '010'
+        failedTelephoneNumbers:
+          - '+191955512345'
+    lookupSingleNumberCompleteNoInfoExample:
+      summary: Example Single Number Lookup Complete with No Information Response
+      value:
+        requestId: 004223a0-8b17-41b1-bf81-20732adf5590
+        status: COMPLETE
+        result:
+          - Response Code: 3
+            Message: NXDOMAIN
+            E.164 Format: '+19195550000'
+            Formatted: (919) 555-0000
+            Country: US
   requestBodies:
     createMessageRequest:
       content:
@@ -5560,6 +6664,14 @@ components:
           schema:
             type: string
             format: binary
+        image/heic:
+          schema:
+            type: string
+            format: binary
+        image/heif:
+          schema:
+            type: string
+            format: binary
         image/jpeg:
           schema:
             type: string
@@ -5600,6 +6712,10 @@ components:
           schema:
             type: string
             format: binary
+        text/html:
+          schema:
+            type: string
+            format: binary
         text/plain:
           schema:
             type: string
@@ -5648,6 +6764,10 @@ components:
           schema:
             type: string
             format: binary
+        video/x-flv:
+          schema:
+            type: string
+            format: binary
       required: true
     createCallRequest:
       description: JSON object containing information to create an outbound call
@@ -5752,6 +6872,39 @@ components:
               $ref: '#/components/examples/singleNumberRequestExample'
             multipleNumberRequestExample:
               $ref: '#/components/examples/multipleNumberRequestExample'
+    requestTollFreeVerificationRequest:
+      description: Request for verification of a toll-free phone number.
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/verificationRequest'
+    updateTollFreeVerificationRequestRequest:
+      description: Update a request for verification of a toll-free phone number.
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/tfvSubmissionWrapper'
+    verificationWebhookRequest:
+      description: Verification callback status of a toll-free phone number.
+      required: true
+      content:
+        application/json:
+          schema:
+            oneOf:
+              - $ref: '#/components/schemas/verificationWebhook'
+              - $ref: '#/components/schemas/verificationDenialWebhook'
+              - $ref: '#/components/schemas/failureWebhook'
+    webhookSubscriptionRequest:
+      description: >-
+        Information about a webhook that Bandwidth should send upon the
+        completion of event customer is trying to subscribe to.
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/webhookSubscriptionRequestSchema'
   securitySchemes:
     Basic:
       type: http
@@ -5770,11 +6923,22 @@ components:
         post:
           requestBody:
             required: true
-            description: Inbound Message Callback Payload
+            description: >
+              <p>This Inbound Message Webhook is an envelope containing a
+              received (MO) message to your message-enabled Bandwidth telephone
+              number. The payload type will always indicate "message-received".
+
+              </p><p>Please visit <a
+              href='/docs/messaging/webhooks/'>Webhooks</a></p>
             content:
               application/json:
                 schema:
-                  $ref: '#/components/schemas/inboundMessageCallback'
+                  $ref: '#/components/schemas/messageCallback'
+                examples:
+                  smsMessageReceivedCallback:
+                    $ref: '#/components/examples/smsMessageReceivedCallbackExample'
+                  mmsMessageReceivedCallback:
+                    $ref: '#/components/examples/mmsMessageReceivedCallbackExample'
           responses:
             '200':
               description: OK
@@ -5783,186 +6947,71 @@ components:
         post:
           requestBody:
             required: true
-            description: Status Callback Payload
+            description: >
+              <p>This Outbound Message Webhook is an envelope containing status
+              information regarding a message sent (MT) from your
+              message-enabled Bandwidth telephone number. The payload type will
+              be one of "message-sending", "message-delivered", or
+              "message-failed".
+
+              </p><p>Please visit <a
+              href='/docs/messaging/webhooks/'>Webhooks</a></p>
             content:
               application/json:
                 schema:
-                  type: object
-                  oneOf:
-                    - $ref: '#/components/schemas/messageSendingCallback'
-                    - $ref: '#/components/schemas/messageDeliveredCallback'
-                    - $ref: '#/components/schemas/messageFailedCallback'
+                  $ref: '#/components/schemas/messageCallback'
+                examples:
+                  messageSendingCallback:
+                    $ref: '#/components/examples/messageSendingCallbackExample'
+                  smsMessageDeliveredCallback:
+                    $ref: '#/components/examples/smsMessageDeliveredCallbackExample'
+                  mmsMessageDeliveredCallback:
+                    $ref: '#/components/examples/mmsMessageDeliveredCallbackExample'
+                  groupMmsMessageDeliveredCallback:
+                    $ref: >-
+                      #/components/examples/groupMmsMessageDeliveredCallbackExample
+                  messageFailedCallback:
+                    $ref: '#/components/examples/messageFailedCallbackExample'
           responses:
             '200':
               description: OK
-  examples:
-    createCallResponseExample:
-      summary: Example of a createCall Response
-      value:
-        applicationId: 04e88489-df02-4e34-a0ee-27a91849555f
-        accountId: '9900000'
-        callId: c-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85
-        to: '+19195551234'
-        from: '+19195554312'
-        enqueuedTime: '2022-06-16T13:15:07.160Z'
-        callUrl: >-
-          https://voice.bandwidth.com/api/v2/accounts/9900000/calls/c-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85
-        callTimeout: 30
-        callbackTimeout: 15
-        tag: My custom tag value
-        answerMethod: POST
-        answerUrl: https://myServer.example/bandwidth/webhooks/answer
-        answerFallbackMethod: POST
-        answerFallbackUrl: https://myServer.example/bandwidth/webhooks/answerFallback
-        disconnectMethod: POST
-        disconnectUrl: https://myServer.example/bandwidth/webhooks/disconnect
-        username: mySecretUsername
-        password: '*****'
-        fallbackUsername: mySecretUsername
-        fallbackPassword: '*****'
-        priority: 5
-    listConferencesResponseExample:
-      summary: Example of a listConferences Response
-      value:
-        - id: conf-fe23a767-a75a5b77-20c5-4cca-b581-cbbf0776eca9
-          name: my-conference-name
-          createdTime: '2022-06-17T22:19:40.375Z'
-          completedTime: '2022-06-17T22:20:00.000Z'
-          conferenceEventUrl: https://myServer.example/bandwidth/webhooks/conferenceEvent
-          conferenceEventMethod: POST
-          tag: my custom tag
-    voiceBadRequestErrorExample:
-      summary: Example of a Bad Request (400) Error
-      value:
-        type: validation
-        description: 'Invalid answerUrl: only http and https are allowed.'
-    voiceUnauthorizedErrorExample:
-      summary: Example of an Unauthorized (401) Error
-      value:
-        type: validation
-        description: 'Invalid answerUrl: only http and https are allowed.'
-    voiceForbiddenErrorExample:
-      summary: Example of a Forbidden (403) Error
-      value:
-        type: validation
-        description: 'Invalid answerUrl: only http and https are allowed.'
-    voiceNotFoundErrorExample:
-      summary: Example of a Not Found (404) Error
-      value:
-        type: validation
-        description: 'Invalid answerUrl: only http and https are allowed.'
-    voiceNotAllowedErrorExample:
-      summary: Example of a Not Allowed (405) Error
-      value:
-        type: validation
-        description: 'Invalid answerUrl: only http and https are allowed.'
-    voiceConflictErrorExample:
-      summary: Example of a Conflict (409) Error
-      value:
-        type: validation
-        description: 'Invalid answerUrl: only http and https are allowed.'
-    voiceUnsupportedMediaTypeErrorExample:
-      summary: Example of an Unsupported Media Type (415) Error
-      value:
-        type: validation
-        description: 'Invalid answerUrl: only http and https are allowed.'
-    voiceTooManyRequestsErrorExample:
-      summary: Example of a Too Many Requests (429) Error
-      value:
-        type: validation
-        description: 'Invalid answerUrl: only http and https are allowed.'
-    voiceInternalServerErrorExample:
-      summary: Example of an Internal Server (500) Error
-      value:
-        type: validation
-        description: 'Invalid answerUrl: only http and https are allowed.'
-    singleNumberRequestExample:
-      summary: Example Number Lookup Request for One Number
-      value:
-        tns:
-          - '+19195551234'
-    multipleNumberRequestExample:
-      summary: Example Number Lookup Request for Multiple Numbers
-      value:
-        tns:
-          - '+19195551234'
-          - '+19195554321'
-    lookupInProgressExample:
-      summary: Example Lookup In Progress Response
-      value:
-        requestId: 004223a0-8b17-41b1-bf81-20732adf5590
-        status: IN_PROGRESS
-    lookupFailedExample:
-      summary: Example Lookup Failed Response
-      value:
-        requestId: 004223a0-8b17-41b1-bf81-20732adf5590
-        status: FAILED
-        failedTelephoneNumbers:
-          - '+191955512345'
-    lookupSingleNumberCompleteExample:
-      summary: Example Single Number Lookup Complete Response
-      value:
-        requestId: 004223a0-8b17-41b1-bf81-20732adf5590
-        status: COMPLETE
-        result:
-          - Response Code: 0
-            Message: NOERROR
-            E.164 Format: '+19195551234'
-            Formatted: (919) 555-1234
-            Country: US
-            Line Type: Mobile
-            Line Provider: Verizon Wireless
-            Mobile Country Code: '310'
-            Mobile Network Code: '010'
-    lookupMultipleNumbersCompleteExample:
-      summary: Example Multiple Numbers Lookup Complete Response
-      value:
-        requestId: 004223a0-8b17-41b1-bf81-20732adf5590
-        status: COMPLETE
-        result:
-          - Response Code: 0
-            Message: NOERROR
-            E.164 Format: '+19195551234'
-            Formatted: (919) 555-1234
-            Country: US
-            Line Type: Mobile
-            Line Provider: Verizon Wireless
-            Mobile Country Code: '310'
-            Mobile Network Code: '010'
-          - Response Code: 0
-            Message: NOERROR
-            E.164 Format: '+19195554321'
-            Formatted: (919) 555-4321
-            Country: US
-            Line Type: Mobile
-            Line Provider: T-Mobile USA
-            Mobile Country Code: '310'
-            Mobile Network Code: '160'
-    lookupMultipleNumbersPartialCompleteExample:
-      summary: Example Multiple Numbers Lookup Partial Complete Response
-      value:
-        requestId: 004223a0-8b17-41b1-bf81-20732adf5590
-        status: PARTIAL_COMPLETE
-        result:
-          - Response Code: 0
-            Message: NOERROR
-            E.164 Format: '+19195551234'
-            Formatted: (919) 555-1234
-            Country: US
-            Line Type: Mobile
-            Line Provider: Verizon Wireless
-            Mobile Country Code: '310'
-            Mobile Network Code: '010'
-        failedTelephoneNumbers:
-          - '+191955512345'
-    lookupSingleNumberCompleteNoInfoExample:
-      summary: Example Single Number Lookup Complete with No Information Response
-      value:
-        requestId: 004223a0-8b17-41b1-bf81-20732adf5590
-        status: COMPLETE
-        result:
-          - Response Code: 3
-            Message: NXDOMAIN
-            E.164 Format: '+19195550000'
-            Formatted: (919) 555-0000
-            Country: US
+    tfVerificationStatus:
+      your_url.com/webhookService:
+        post:
+          summary: TFV status updates sent to customer's webhook URL.
+          description: >-
+            Unique webhook URL provided by customers to which Bandwidth sends a
+            POST request to notify customer regarding TFV status updates.
+          operationId: tfvRequest
+          parameters:
+            - description: >-
+                64-character lowercase hexidecimal 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/verificationWebhookRequest'
+          responses:
+            '204':
+              description: No Content
+            '400':
+              $ref: '#/components/responses/tfvBadRequestResponse'
+            '401':
+              $ref: '#/components/responses/tfvUnauthorizedResponse'
+            '403':
+              $ref: '#/components/responses/tfvForbiddenResponse'
+            '404':
+              $ref: '#/components/responses/tfvNotFoundResponse'
+            '405':
+              $ref: '#/components/responses/tfvNotAllowedResponse'
+            '429':
+              $ref: '#/components/responses/tfvTooManyRequestsResponse'
+            '500':
+              $ref: '#/components/responses/tfvServerErrorResponse'
+            '503':
+              $ref: '#/components/responses/tfvServiceUnavailableResponse'