openapi: 3.1.0 info: title: Bandwidth Toll-Free Verification API description: >- The Bandwidth Toll-Free Verification API enables developers to programmatically submit and manage toll-free number verification requests for A2P messaging compliance. It automates the verification submission process, allowing developers to view and update the verification status of their toll-free numbers. This API helps ensure that toll-free messaging traffic complies with carrier requirements and regulations including the Telephone Consumer Protection Act (TCPA). version: '1.0' contact: name: Bandwidth Support url: https://support.bandwidth.com termsOfService: https://www.bandwidth.com/legal/ externalDocs: description: Bandwidth Toll-Free Verification API Documentation url: https://dev.bandwidth.com/apis/messaging-apis/toll-free-verification/ servers: - url: https://dashboard.bandwidth.com/api description: Production Server tags: - name: Toll-Free Verification description: >- Submit and manage toll-free number verification requests for A2P messaging compliance. Track verification status and manage submissions throughout the verification lifecycle. security: - basicAuth: [] paths: /accounts/{accountId}/tollFreeVerification: get: operationId: listTollFreeVerifications summary: List toll-free verification requests description: >- Retrieves a list of all toll-free number verification requests for the account. Returns verification status, submission details, and associated toll-free numbers. tags: - Toll-Free Verification parameters: - $ref: '#/components/parameters/accountId' - name: status in: query description: Filter by verification status schema: type: string enum: - PENDING_VERIFICATION - VERIFIED - RESTRICTED - DENIED - SUBMITTED - name: telephoneNumber in: query description: Filter by toll-free telephone number schema: type: string responses: '200': description: Verification requests retrieved successfully content: application/json: schema: $ref: '#/components/schemas/VerificationListResponse' '401': description: Unauthorized post: operationId: createTollFreeVerification summary: Submit a toll-free verification request description: >- Submits a new toll-free number verification request to the toll-free aggregator. Once submitted, the number will have a Pending Verification status until the aggregator reviews and approves or denies the request. Status updates are delivered via webhook notifications. tags: - Toll-Free Verification parameters: - $ref: '#/components/parameters/accountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VerificationRequest' responses: '201': description: Verification request submitted successfully content: application/json: schema: $ref: '#/components/schemas/Verification' '400': description: Invalid verification request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized /accounts/{accountId}/tollFreeVerification/{verificationId}: get: operationId: getTollFreeVerification summary: Get toll-free verification details description: >- Retrieves detailed information about a specific toll-free number verification request including its current status, submission details, and any denial reasons if applicable. tags: - Toll-Free Verification parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/verificationId' responses: '200': description: Verification details retrieved successfully content: application/json: schema: $ref: '#/components/schemas/Verification' '401': description: Unauthorized '404': description: Verification request not found put: operationId: updateTollFreeVerification summary: Update a toll-free verification request description: >- Updates an existing toll-free verification request. This can be used to provide additional information or correct details on a pending or denied verification submission. tags: - Toll-Free Verification parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/verificationId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VerificationRequest' responses: '200': description: Verification request updated successfully content: application/json: schema: $ref: '#/components/schemas/Verification' '400': description: Invalid update request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized '404': description: Verification request not found components: securitySchemes: basicAuth: type: http scheme: basic description: >- HTTP Basic Authentication using your Bandwidth Dashboard API credentials. parameters: accountId: name: accountId in: path required: true description: The unique identifier for the Bandwidth account schema: type: string verificationId: name: verificationId in: path required: true description: The unique identifier for the verification request schema: type: string schemas: VerificationRequest: type: object required: - telephoneNumbers - businessName - businessContact - messageVolume - useCase - useCaseSummary - optInWorkflow properties: telephoneNumbers: type: array items: type: string description: >- List of toll-free numbers to verify in E.164 format example: - '+18005551234' businessName: type: string description: >- The legal name of the business sending messages from the toll-free number businessContact: type: object required: - firstName - lastName - email - phone properties: firstName: type: string description: First name of the business contact lastName: type: string description: Last name of the business contact email: type: string format: email description: Email address of the business contact phone: type: string description: Phone number of the business contact businessWebsite: type: string format: uri description: The business website URL messageVolume: type: string enum: - '10' - '100' - '1,000' - '10,000' - '100,000' - '250,000' - '500,000' - '750,000' - '1,000,000+' description: >- Estimated monthly message volume useCase: type: string enum: - TWO_FACTOR_AUTHENTICATION - APP_NOTIFICATIONS - ACCOUNT_NOTIFICATIONS - CUSTOMER_CARE - DELIVERY_NOTIFICATIONS - FRAUD_ALERT_MESSAGING - HIGHER_EDUCATION - MARKETING - POLLING_AND_VOTING - PUBLIC_SERVICE_ANNOUNCEMENT - SECURITY_ALERT description: >- The primary use case for messaging from this toll-free number useCaseSummary: type: string maxLength: 500 description: >- A detailed description of how the toll-free number will be used for messaging (max 500 characters) messageContent: type: string maxLength: 1000 description: >- Sample message content that will be sent from the number optInWorkflow: type: string maxLength: 500 description: >- Description of how recipients opt in to receive messages optInWorkflowImageUrls: type: array items: type: string format: uri description: >- URLs to images showing the opt-in workflow (screenshots) additionalInformation: type: string maxLength: 500 description: >- Any additional information to support the verification request Verification: type: object properties: verificationId: type: string description: The unique identifier for the verification request telephoneNumbers: type: array items: type: string description: The toll-free numbers associated with this verification status: type: string enum: - PENDING_VERIFICATION - VERIFIED - RESTRICTED - DENIED - SUBMITTED description: >- The current verification status businessName: type: string description: The business name on the verification useCase: type: string description: The messaging use case submissionDate: type: string format: date-time description: The date and time the verification was submitted verificationDate: type: string format: date-time description: >- The date and time the verification was approved or denied denialReason: type: string description: >- The reason for denial, if the verification was denied VerificationListResponse: type: object properties: totalCount: type: integer description: Total number of verification requests verifications: type: array items: $ref: '#/components/schemas/Verification' Error: type: object properties: type: type: string description: The error type identifier description: type: string description: A human-readable description of the error