`: The RCS service returned an unrecognized
status code, where `` is the raw value.
**Service-level errors:**
- `MISSING_FROM_RESPONSE`: The phone number was absent from the RCS
service response.
- `RCS_SERVICE_UNAVAILABLE`: An exception was thrown during the async
RCS service call.
- `RCS_SERVICE_DISABLED`: RCS lookup is disabled in configuration.
- `EMPTY_RESPONSE`: The RCS service returned a null or empty response
body.
example: RCS_SERVICE_UNAVAILABLE
lookupResult:
type: object
description: Carrier information results for the specified telephone number.
properties:
phoneNumber:
type: string
description: The telephone number in E.164 format.
example: '+10072904498'
lineType:
$ref: '#/components/schemas/lineTypeEnum'
messagingProvider:
type: string
description: The messaging service provider of the telephone number.
example: Verizon Wireless
voiceProvider:
type: string
description: The voice service provider of the telephone number.
example: Verizon Wireless
countryCodeA3:
type: string
description: >-
The country code of the telephone number in ISO 3166-1 alpha-3
format.
example: USA
deactivationReporter:
type: string
description: >
[DNI-Only](#section/DNI-Only).
The carrier that reported a deactivation event for this phone
number.
deactivationDate:
type: string
format: date-time-local
description: >-
[DNI-Only](#section/DNI-Only). The datetime the carrier reported a
deactivation event.
example: 2025-06-20 18:35
deactivationEvent:
$ref: '#/components/schemas/deactivationEventEnum'
latestMessageDeliveryStatus:
$ref: '#/components/schemas/latestMessageDeliveryStatusEnum'
initialMessageDeliveryStatusDate:
type: string
format: date
description: >-
[DNI-Only](#section/DNI-Only). The date the phone number entered the
status described in `latestMessageDeliveryStatus`.
Think of this as the "start time" for that status.
Value resets every time the `latestMessageDeliveryStatus` changes.
example: '2025-06-20'
latestMessageDeliveryStatusDate:
type: string
format: date
description: >-
[DNI-Only](#section/DNI-Only). The date bandwidth last received
delivery status information for this phone number.
Use this field to understand how up-to-date the
`latestMessageDeliveryStatus` is.
Value resets every time the `latestMessageDeliveryStatus` changes.
example: '2025-06-21'
rcsEnabled:
type: boolean
description: >
[RCS-Only](#section/RCS-Only). Indicates whether the phone number is
capable of receiving RCS messages. Value will be null if account has
RCS, but no value was returned. Absent when account does not have
RCS.
example: true
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
blocked:
description: >-
Whether a Toll-Free Verification is blocked. This attribute will only be
defined when the number is blocked.
example: true
type: boolean
blockedReason:
description: >-
The reason why the Toll-Free Verification is blocked. This attribute
will only be defined when the number is blocked.
example: Toll-free number was used to send spam messages
type: string
privacyPolicyUrl:
description: The Toll-Free Verification request privacy policy URL.
maxLength: 500
example: http://your-company.com/privacyPolicy
type: string
termsAndConditionsUrl:
description: The Toll-Free Verification request terms and conditions policy URL.
maxLength: 500
example: http://your-company.com/termsAndConditions
type: string
businessDba:
description: The company 'Doing Business As'.
maxLength: 500
example: Another Company Name Inc.
type: string
businessRegistrationNumber:
type: string
description: >
Government-issued business identifying number.
**Note: As of October 19th, 2026 this field will be required when
`businessEntityType` is _not_ `SOLE_PROPRIETOR`. If this field is
provided, `businessRegistrationType` and
`businessRegistrationIssuingCountry` are also required.**
nullable: true
maxLength: 500
example: 12-3456789
businessRegistrationTypeEnum:
type: string
description: >
The type of business registration number.
**Note: As of October 19th, 2026 this field will be required when
`businessRegistrationNumber` is provided.**
enum:
- EIN
- CBN
- NEQ
- PROVINCIAL_NUMBER
- CRN
- VAT
- ACN
- ABN
- BRN
- SIREN
- SIRET
- NZBN
- UST_IDNR
- CIF
- NIF
- CNPJ
- UID
- OTHER
example: EIN
nullable: true
businessRegistrationIssuingCountry:
type: string
description: >-
The country issuing the business registration in ISO-3166-1 alpha-3
format. Alpha-2 format is accepted by the API, but alpha-3 is highly
encouraged.
**Note: As of October 19th, 2026 this field will be required when
`businessRegistrationNumber` is provided.**
| Registration Type | Supported Countries |
|----------------------|------------------------------------|
| EIN | USA |
| CBN | CAN |
| NEQ | CAN |
| PROVINCIAL_NUMBER | CAN |
| CRN | GBR, HKG |
| VAT | GBR, IRL, BRA, NLD |
| ACN | AUS |
| ABN | AUS |
| BRN | HKG |
| SIREN | FRA |
| SIRET | FRA |
| NZBN | NZL |
| UST_IDNR | DEU |
| CIF | ESP |
| NIF | ESP |
| CNPJ | BRA |
| UID | CHE |
| OTHER | Must Provide Country Code |
example: USA
nullable: true
businessEntityTypeEnum:
type: string
description: >
The type of registered business.
**Note: As of October 19th, 2026 submissions using a value other than
`SOLE_PROPRIETOR` must provide a value for `businessRegistrationNumber`,
`businessRegistrationType`, and `businessRegistrationIssuingCountry`.
Submissions using `SOLE_PROPRIETOR` must _omit_
`businessRegistrationNumber`, `businessRegistrationType`, and
`businessRegistrationIssuingCountry`. Failure to adhere to these
constraints will result in a 400 Bad Request rejection.**
enum:
- SOLE_PROPRIETOR
- PRIVATE_PROFIT
- PUBLIC_PROFIT
- NON_PROFIT
- GOVERNMENT
example: PRIVATE_PROFIT
nullable: false
helpMessageResponse:
type: string
description: A message that gets sent to users requesting help.
nullable: true
maxLength: 500
example: Please contact support for assistance.
ageGatedContent:
type: boolean
description: Indicates whether the content is age-gated.
example: false
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
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
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
- businessEntityType
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:
$ref: '#/components/schemas/useCaseSummary'
productionMessageContent:
$ref: '#/components/schemas/productionMessageContent'
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'
privacyPolicyUrl:
$ref: '#/components/schemas/privacyPolicyUrl'
termsAndConditionsUrl:
$ref: '#/components/schemas/termsAndConditionsUrl'
businessDba:
$ref: '#/components/schemas/businessDba'
businessRegistrationNumber:
$ref: '#/components/schemas/businessRegistrationNumber'
businessRegistrationType:
$ref: '#/components/schemas/businessRegistrationTypeEnum'
businessRegistrationIssuingCountry:
$ref: '#/components/schemas/businessRegistrationIssuingCountry'
businessEntityType:
$ref: '#/components/schemas/businessEntityTypeEnum'
helpMessageResponse:
$ref: '#/components/schemas/helpMessageResponse'
ageGatedContent:
$ref: '#/components/schemas/ageGatedContent'
cvToken:
$ref: '#/components/schemas/cvTokenNullable'
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:
$ref: '#/components/schemas/useCaseSummary'
productionMessageContent:
$ref: '#/components/schemas/productionMessageContent'
optInWorkflow:
$ref: '#/components/schemas/optInWorkflow'
additionalInformation:
$ref: '#/components/schemas/additionalInformation'
isvReseller:
$ref: '#/components/schemas/isvReseller'
privacyPolicyUrl:
$ref: '#/components/schemas/privacyPolicyUrl'
termsAndConditionsUrl:
$ref: '#/components/schemas/termsAndConditionsUrl'
businessDba:
$ref: '#/components/schemas/businessDba'
businessRegistrationNumber:
$ref: '#/components/schemas/businessRegistrationNumber'
businessRegistrationType:
$ref: '#/components/schemas/businessRegistrationTypeEnum'
businessEntityType:
$ref: '#/components/schemas/businessEntityTypeEnum'
businessRegistrationIssuingCountry:
$ref: '#/components/schemas/businessRegistrationIssuingCountry'
helpMessageResponse:
$ref: '#/components/schemas/helpMessageResponse'
ageGatedContent:
$ref: '#/components/schemas/ageGatedContent'
cvToken:
$ref: '#/components/schemas/cvTokenNullable'
tfvBasicAuthentication:
type: object
properties:
username:
type: string
maxLength: 100
example: username
password:
type: string
maxLength: 200
example: password
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'
errorMessage:
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'
blocked:
$ref: '#/components/schemas/blocked'
blockedReason:
$ref: '#/components/schemas/blockedReason'
verificationWebhook:
type: object
properties:
accountId:
$ref: '#/components/schemas/accountId1'
phoneNumber:
$ref: '#/components/schemas/tfPhoneNumber'
status:
$ref: '#/components/schemas/tfvCallbackStatusEnum'
internalTicketNumber:
$ref: '#/components/schemas/internalTicketNumberForWebhook'
blockedWebhook:
type: object
properties:
accountId:
$ref: '#/components/schemas/accountId1'
phoneNumber:
$ref: '#/components/schemas/tfPhoneNumber'
status:
$ref: '#/components/schemas/tfvCallbackStatusEnum'
internalTicketNumber:
$ref: '#/components/schemas/internalTicketNumberForWebhook'
blocked:
$ref: '#/components/schemas/blocked'
blockedReason:
$ref: '#/components/schemas/blockedReason'
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
example: 2230 Bandmate Way
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
additionalInformation:
type: string
description: Any additional information.
minLength: 0
maxLength: 500
nullable: true
example: Any additional information
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@:%_\+.~#()?&//=]*)
confirmationResponse:
type: string
minLength: 0
maxLength: 500
nullable: true
example: Thank you for opting in!
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
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
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/webhookSubscriptionError'
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
webhookSubscriptionError:
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
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
format: date-time
example: '2023-05-15T13:56:39.965Z'
modifiedDate:
type: string
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
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:
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: Date and time the verification request was last modified.
format: date-time
example: '2021-06-08T06:45:13.0Z'
submission:
$ref: '#/components/schemas/tfvSubmissionInfo'
blocked:
$ref: '#/components/schemas/blocked'
blockedReason:
$ref: '#/components/schemas/blockedReason'
cvToken:
$ref: '#/components/schemas/cvTokenNullable'
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:
$ref: '#/components/schemas/useCaseSummary'
productionMessageContent:
$ref: '#/components/schemas/productionMessageContent'
optInWorkflow:
$ref: '#/components/schemas/optInWorkflow'
additionalInformation:
$ref: '#/components/schemas/additionalInformation'
isvReseller:
$ref: '#/components/schemas/isvReseller'
privacyPolicyUrl:
$ref: '#/components/schemas/privacyPolicyUrl'
termsAndConditionsUrl:
$ref: '#/components/schemas/termsAndConditionsUrl'
businessDba:
$ref: '#/components/schemas/businessDba'
businessRegistrationNumber:
$ref: '#/components/schemas/businessRegistrationNumber'
description: Government-issued business identifying number.
businessRegistrationType:
$ref: '#/components/schemas/businessRegistrationTypeEnum'
description: The type of business registration number.
businessRegistrationIssuingCountry:
$ref: '#/components/schemas/businessRegistrationIssuingCountry'
description: >-
The country issuing the business registration in ISO-3166-1 alpha-3
format.
businessEntityType:
$ref: '#/components/schemas/businessEntityTypeEnum'
description: The type of registered business.
tfvStatusEnum:
type: string
enum:
- VERIFIED
- UNVERIFIED
- PENDING
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
cvTokenNullable:
type: string
description: >-
The token provided by Campaign Verify to validate your political use
case. Only required for 527 political organizations. If you are not a
527 political organization, this field should be omitted. Supplying an
empty string will likely result in rejection.
minLength: 0
maxLength: 500
nullable: true
example: >-
cv.user123|sess456|mno|tfree|read_write|X7yZ9aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789aBcDeFgHiJkLmNoPqRsTuVw
endpointId:
type: string
description: The unique ID of the endpoint.
example: e-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85
endpointStatusEnum:
type: string
enum:
- CONNECTED
- DISCONNECTED
deviceStatusEnum:
type: string
enum:
- CONNECTED
- DISCONNECTED
endpointTypeEnum:
type: string
enum:
- WEBRTC
endpointDirectionEnum:
type: string
enum:
- INBOUND
- OUTBOUND
- BIDIRECTIONAL
sipCredentials:
type: object
properties:
username:
type: string
description: The username for the SIP connection.
example: username
password:
type: string
description: The password for the SIP connection.
example: password
sipConnectionMetadata:
title: SIP Connection
type: object
properties:
ipAddress:
type: string
format: ipv4
description: The IP address of the SIP connection.
example: 192.168.0.0
port:
type: integer
description: The port of the SIP connection.
example: 5060
credentials:
$ref: '#/components/schemas/sipCredentials'
uuiHeader:
type: string
description: The User-to-User Information header for the SIP connection.
example: my-uui-header
webRtcConnectionMetadata:
title: WebRTC Connection
type: object
endpointToken:
type: string
description: >-
The json web token specific to the endpoint. Used to authenticate the
client with the media gateway.
example: xxxxx.yyyyy.zzzzz
endpointTag:
type: string
description: A tag for the endpoint.
example: my-tag
maximum: 1024
device:
type: object
properties:
deviceId:
type: string
description: The unique ID of the device.
example: d-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85
deviceName:
type: string
description: The name of the device.
maximum: 1024
example: David's iPhone
status:
$ref: '#/components/schemas/deviceStatusEnum'
creationTimestamp:
type: string
format: date-time
description: The time the device was created. In ISO-8601 format.
example: '2021-01-01T00:00:00Z'
required:
- deviceId
- status
- creationTimestamp
endpoints:
type: object
properties:
endpointId:
$ref: '#/components/schemas/endpointId'
type:
$ref: '#/components/schemas/endpointTypeEnum'
status:
$ref: '#/components/schemas/endpointStatusEnum'
creationTimestamp:
type: string
format: date-time
description: The time the endpoint was created. In ISO-8601 format.
example: '2021-01-01T00:00:00Z'
expirationTimestamp:
type: string
format: date-time
description: >-
The time the endpoint token will expire. In ISO-8601 format. Tokens
last 24 hours.
example: '2021-01-02T00:00:00Z'
tag:
$ref: '#/components/schemas/endpointTag'
required:
- endpointId
- type
- status
- creationTimestamp
- expirationTimestamp
endpoint:
type: object
allOf:
- $ref: '#/components/schemas/endpoints'
- type: object
properties:
devices:
type: array
items:
$ref: '#/components/schemas/device'
createWebRtcConnectionRequest:
allOf:
- $ref: '#/components/schemas/createEndpointRequestBase'
- type: object
properties:
connectionMetadata:
$ref: '#/components/schemas/webRtcConnectionMetadata'
createEndpointRequestBase:
type: object
properties:
type:
$ref: '#/components/schemas/endpointTypeEnum'
direction:
$ref: '#/components/schemas/endpointDirectionEnum'
eventCallbackUrl:
type: string
format: uri
description: The URL to send event callbacks to.
example: https://myapp.com/callback
eventFallbackUrl:
type: string
format: uri
description: The URL to send event fallbacks to.
example: https://fallback.myapp.com/callback
tag:
$ref: '#/components/schemas/endpointTag'
required:
- type
- direction
createEndpointRequest:
oneOf:
- $ref: '#/components/schemas/createWebRtcConnectionRequest'
discriminator:
propertyName: type
mapping:
WEBRTC: '#/components/schemas/createWebRtcConnectionRequest'
createEndpointResponseData:
allOf:
- $ref: '#/components/schemas/endpoint'
- type: object
properties:
token:
$ref: '#/components/schemas/endpointToken'
required:
- token
endpointEventTypeEnum:
type: string
enum:
- DEVICE_CONNECTED
- DEVICE_DISCONNECTED
endpointEvent:
description: An event that occurred on an endpoint.
allOf:
- $ref: '#/components/schemas/endpoints'
- type: object
properties:
eventTime:
type: string
format: date-time
description: The time the event occurred. In ISO-8601 format.
example: '2021-01-01T00:00:00Z'
eventType:
$ref: '#/components/schemas/endpointEventTypeEnum'
device:
$ref: '#/components/schemas/device'
required:
- eventType
- eventTime
brtcLink:
type: object
properties:
href:
type: string
description: The full URL of the link.
example: >-
https://api.bandwidth.com/v2/accounts/5500123/endpoints/e-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85
rel:
type: string
description: The relationship of the link to the current resource.
example: self
method:
type: string
description: The HTTP method to use when making the request.
example: GET
page:
type: object
properties:
pageSize:
type: integer
description: The number of items per page.
minimum: 0
example: 10
totalElements:
type: integer
description: The total number of items.
minimum: 0
example: 100
totalPages:
type: integer
description: The total number of pages.
minimum: 0
example: 10
pageNumber:
type: integer
description: The current page number.
minimum: 0
example: 0
required:
- pageSize
brtcError:
type: object
properties:
id:
type: string
format: uuid
description: A unique identifier for the error.
example: 59512d87-7a92-4040-8e4a-78fb772019b9
type:
type: string
description: The type of error.
example: resource.not_found
description:
type: string
description: A description of the error.
example: The requested resource was not found.
code:
type: string
description: A code that uniquely identifies the error.
example: '404'
source:
$ref: '#/components/schemas/brtcErrorSource'
required:
- type
- description
brtcErrorSource:
type: object
properties:
parameter:
type: string
description: The URI parameter that caused the error.
example: accountId
field:
type: string
description: The request body field that caused the error.
example: accountId
header:
type: string
description: The header that caused the error.
example: Authorization
reference:
type: string
description: >-
The resource ID or path to the resource (or non-existent resource)
causing the error.
example: e-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85
listEndpointsResponse:
type: object
properties:
links:
type: array
items:
$ref: '#/components/schemas/brtcLink'
page:
$ref: '#/components/schemas/page'
data:
type: array
items:
$ref: '#/components/schemas/endpoints'
errors:
type: array
items:
$ref: '#/components/schemas/brtcError'
required:
- links
- data
- errors
endpointResponse:
type: object
properties:
links:
type: array
items:
$ref: '#/components/schemas/brtcLink'
data:
$ref: '#/components/schemas/endpoint'
errors:
type: array
items:
$ref: '#/components/schemas/brtcError'
required:
- links
- data
- errors
createEndpointResponse:
type: object
properties:
links:
type: array
items:
$ref: '#/components/schemas/brtcLink'
data:
$ref: '#/components/schemas/createEndpointResponseData'
errors:
type: array
items:
$ref: '#/components/schemas/brtcError'
required:
- links
- data
- errors
brtcErrorResponse:
type: object
properties:
links:
type: array
items:
$ref: '#/components/schemas/brtcLink'
data:
type: object
nullable: true
additionalProperties: false
errors:
type: array
items:
$ref: '#/components/schemas/brtcError'
required:
- links
- data
- errors
responses:
createMessageResponse:
description: Accepted
content:
application/json:
schema:
$ref: '#/components/schemas/message'
createMultiChannelMessageResponse:
description: Accepted
content:
application/json:
schema:
$ref: '#/components/schemas/createMultiChannelMessageResponse'
listMessagesResponse:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/messagesList'
getMediaResponse:
description: OK
content:
application/octet-stream:
schema:
type: string
description: Successful Operation
format: binary
listMediaResponse:
description: OK
headers:
Continuation-Token:
description: Continuation token used to retrieve subsequent media.
schema:
type: string
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/media'
messagingBadRequestError:
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/messagingRequestError'
messagingNotAcceptableError:
description: Not Acceptable
content:
application/json:
schema:
$ref: '#/components/schemas/messagingRequestError'
createMessageBadRequestError:
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/createMessageRequestError'
messagingUnauthorizedError:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/messagingRequestError'
messagingForbiddenError:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/messagingRequestError'
messagingNotFoundError:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/messagingRequestError'
messagingMethodNotAllowedError:
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/messagingRequestError'
messagingInvalidMediaTypeError:
description: Unsupported Media Type
content:
application/json:
schema:
$ref: '#/components/schemas/messagingRequestError'
messagingTooManyRequestsError:
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/messagingRequestError'
messagingInternalServerError:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/messagingRequestError'
multiChannelBadRequestError:
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/multiChannelError'
example:
links: []
data: null
errors:
- type: request-validation
description: >-
The 'channelList[0].from' field must contain exactly one
telephone number
source:
field: channelList[0].from
multiChannelNotAcceptableError:
description: Not Acceptable
multiChannelUnauthorizedError:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/multiChannelError'
example:
links: []
data: null
errors:
- type: unauthorized
description: Authentication Failed
source: {}
multiChannelForbiddenError:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/multiChannelError'
example:
links: []
data: null
errors:
- type: forbidden
description: Access Denied
source: {}
multiChannelNotFoundError:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/multiChannelError'
example:
links: []
data: null
errors:
- type: forbidden
description: Resource not found.
source: {}
multiChannelMethodNotAllowedError:
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/multiChannelError'
example:
links: []
data: null
errors:
- type: method-not-allowed
description: Method 'PUT' not supported for this resource.
source: {}
multiChannelInvalidMediaTypeError:
description: Unsupported Media Type
content:
application/json:
schema:
$ref: '#/components/schemas/multiChannelError'
example:
links: []
data: null
errors:
- type: unsupported-content-type
description: >-
Content-Type 'application/xml;charset=UTF-8' is not supported.
Please use 'application/json'
source:
header: Content-Type
multiChannelTooManyRequestsError:
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/multiChannelError'
example:
links: []
data: null
errors:
- type: rate-limit-exceeded
description: >-
You have exceeded your rate limit for this endpoint. Please
retry later.
source: {}
multiChannelInternalServerError:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/multiChannelError'
example:
links: []
data: null
errors:
- type: internal-server-error
description: Internal server error. No further information available
source: {}
listMessagesTooManyRequestsError:
description: Too Many Requests
headers:
Retry-After:
description: The number of seconds to wait before retrying the request.
schema:
type: integer
example: 300
content:
application/json:
schema:
$ref: '#/components/schemas/messagingRequestError'
example:
type: rate_limit_exceeded
description: >-
Rate limit exceeded. Wait for Retry-After time before sending
another request.
createCallResponse:
description: Created
headers:
Location:
description: The URL for further interactions with this call
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/createCallResponse'
examples:
createCall Response:
$ref: '#/components/examples/createCallResponseExample'
getCallStateResponse:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/callState'
updateCallResponse:
description: OK
listCallsResponse:
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/callState'
getStatisticsResponse:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/accountStatistics'
updateRecordingResponse:
description: OK
listCallRecordingsResponse:
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/callRecordingMetadata'
getCallRecordingResponse:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/callRecordingMetadata'
downloadRecordingMediaResponse:
description: OK
content:
audio/vnd.wave:
schema:
type: string
format: binary
audio/mpeg:
schema:
type: string
format: binary
getRecordingTranscriptionResponse:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/recordingTranscriptions'
listTranscriptionsResponse:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/callTranscriptionMetadataList'
getCallTranscriptionResponse:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/callTranscriptionResponse'
deleteCallTranscriptionResponse:
description: No Content
listConferencesResponse:
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/conference'
examples:
listConferences Response:
$ref: '#/components/examples/listConferencesResponseExample'
getConferenceResponse:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/conference'
getConferenceMemberResponse:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/conferenceMember'
listConferenceRecordingsResponse:
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/conferenceRecordingMetadata'
getConferenceRecordingResponse:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/conferenceRecordingMetadata'
voiceBadRequestError:
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/voiceApiError'
examples:
badRequestErrorExample:
$ref: '#/components/examples/voiceBadRequestErrorExample'
voiceUnauthorizedError:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/voiceApiError'
examples:
unauthorizedErrorExample:
$ref: '#/components/examples/voiceUnauthorizedErrorExample'
voiceForbiddenError:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/voiceApiError'
examples:
forbiddenErrorExample:
$ref: '#/components/examples/voiceForbiddenErrorExample'
voiceNotFoundError:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/voiceApiError'
examples:
notFoundErrorExample:
$ref: '#/components/examples/voiceNotFoundErrorExample'
voiceNotAllowedError:
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/voiceApiError'
examples:
notAllowedErrorExample:
$ref: '#/components/examples/voiceNotAllowedErrorExample'
voiceConflictError:
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/voiceApiError'
examples:
conflictErrorExample:
$ref: '#/components/examples/voiceConflictErrorExample'
voiceUnsupportedMediaTypeError:
description: Unsupported Media Type
content:
application/json:
schema:
$ref: '#/components/schemas/voiceApiError'
examples:
tooManyRequestsErrorExample:
$ref: '#/components/examples/voiceUnsupportedMediaTypeErrorExample'
voiceTooManyRequestsError:
description: Too Many Requests
headers:
Retry-After:
description: When you should try your request again.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/voiceApiError'
examples:
tooManyRequestsErrorExample:
$ref: '#/components/examples/voiceTooManyRequestsErrorExample'
voiceInternalServerError:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/voiceApiError'
examples:
internalServerErrorExample:
$ref: '#/components/examples/voiceInternalServerErrorExample'
voiceCodeResponse:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/voiceCodeResponse'
messagingCodeResponse:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/messagingCodeResponse'
verifyCodeResponse:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/verifyCodeResponse'
mfaBadRequestError:
description: Bad Request
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/mfaRequestError'
mfaUnauthorizedError:
description: Unauthorized
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/mfaUnauthorizedRequestError'
mfaForbiddenError:
description: Forbidden
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/mfaForbiddenRequestError'
mfaTooManyRequestsError:
description: Too Many Requests
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/mfaRequestError'
mfaInternalServerError:
description: Internal Server Error
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/mfaRequestError'
createSyncLookupResponse:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/createSyncLookupResponse'
examples:
lookupCompleteWithDniExample:
$ref: '#/components/examples/lookupCompleteWithDniExample'
lookupCompleteExample:
$ref: '#/components/examples/lookupCompleteExample'
lookupCompleteWithRcsExample:
$ref: '#/components/examples/lookupCompleteWithRcsExample'
lookupCompleteWithRcsErrorExample:
$ref: '#/components/examples/lookupCompleteWithRcsErrorExample'
lookupPartialExample:
$ref: '#/components/examples/lookupPartialExample'
lookupFailedExample:
$ref: '#/components/examples/lookupFailedExample'
createAsyncBulkLookupResponse:
description: Accepted
content:
application/json:
schema:
$ref: '#/components/schemas/createAsyncBulkLookupResponse'
examples:
lookupAcceptedExample:
$ref: '#/components/examples/lookupAcceptedExample'
getAsyncBulkLookupResponse:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/getAsyncBulkLookupResponse'
examples:
lookupCompleteWithDniExample:
$ref: '#/components/examples/lookupCompleteWithDniExample'
lookupCompleteExample:
$ref: '#/components/examples/lookupCompleteExample'
lookupInProgressExample:
$ref: '#/components/examples/lookupInProgressExample'
lookupPartialExample:
$ref: '#/components/examples/lookupPartialExample'
lookupFailedExample:
$ref: '#/components/examples/lookupFailedExample'
tnLookupDefaultResponse:
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/lookupErrorResponse'
examples:
badRequest:
$ref: '#/components/examples/badRequestExample'
unauthorized:
$ref: '#/components/examples/unauthorizedExample'
forbidden:
$ref: '#/components/examples/forbiddenExample'
mediaType:
$ref: '#/components/examples/unsupportedMediaTypeExample'
notFound:
$ref: '#/components/examples/notFoundExample'
tooManyRequests:
$ref: '#/components/examples/tooManyRequestsExample'
internalServer:
$ref: '#/components/examples/internalServerErrorExample'
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
noContentResponse:
description: No Content
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
verifyPutResponse:
description: Accepted
listEndpointsResponse:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/listEndpointsResponse'
examples:
listEndpointsResponseExample:
$ref: '#/components/examples/listEndpointsResponseExample'
createEndpointResponse:
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/createEndpointResponse'
examples:
createEndpointResponseExample:
$ref: '#/components/examples/createEndpointResponseExample'
getEndpointResponse:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/endpointResponse'
examples:
getEndpointResponseExample:
$ref: '#/components/examples/getEndpointResponseExample'
badRequestErrorResponse:
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/brtcErrorResponse'
examples:
badRequestErrorExample:
$ref: '#/components/examples/badRequestErrorExample'
unauthorizedErrorResponse:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/brtcErrorResponse'
examples:
unauthorizedErrorExample:
$ref: '#/components/examples/unauthorizedErrorExample'
forbiddenErrorResponse:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/brtcErrorResponse'
examples:
forbiddenErrorExample:
$ref: '#/components/examples/forbiddenErrorExample'
notFoundErrorResponse:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/brtcErrorResponse'
examples:
notFoundErrorExample:
$ref: '#/components/examples/notFoundErrorExample'
methodNotAllowedErrorResponse:
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/brtcErrorResponse'
examples:
methodNotAllowedErrorExample:
$ref: '#/components/examples/methodNotAllowedErrorExample'
unsupportedMediaTypeErrorResponse:
description: Unsupported Media Type
content:
application/json:
schema:
$ref: '#/components/schemas/brtcErrorResponse'
examples:
unsuppotedMediaTypeErrorExample:
$ref: '#/components/examples/unsupportedMediaTypeErrorExample'
tooManyRequestsErrorResponse:
description: Too Many Requests
headers:
Retry-After:
description: >-
The number of seconds the client should wait before making another
request.
required: true
schema:
type: integer
example: 900
content:
application/json:
schema:
$ref: '#/components/schemas/brtcErrorResponse'
examples:
tooManyRequestsErrorExample:
$ref: '#/components/examples/tooManyRequestsErrorExample'
serviceUnavailableErrorResponse:
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/brtcErrorResponse'
examples:
serviceUnavailableErrorExample:
$ref: '#/components/examples/serviceUnavailableErrorExample'
parameters:
accountId:
in: path
name: accountId
required: true
schema:
type: string
description: Your Bandwidth Account ID.
example: '9900000'
mediaId:
in: path
name: mediaId
required: true
description: Media ID to retrieve.
example: 14762070468292kw2fuqty55yp2b2/0/bw.png
schema:
type: string
contentType:
in: header
name: Content-Type
style: simple
explode: false
description: The media type of the entity-body.
example: audio/wav
schema:
type: string
cacheControl:
in: header
name: Cache-Control
style: simple
explode: false
description: >-
General-header field is used to specify directives that MUST be obeyed
by all caching mechanisms along the request/response chain.
example: no-cache
schema:
type: string
continuationToken:
in: header
name: Continuation-Token
description: Continuation token used to retrieve subsequent media.
example: >-
1XEi2tsFtLo1JbtLwETnM1ZJ+PqAa8w6ENvC5QKvwyrCDYII663Gy5M4s40owR1tjkuWUif6qbWvFtQJR5/ipqbUnfAqL254LKNlPy6tATCzioKSuHuOqgzloDkSwRtX0LtcL2otHS69hK343m+SjdL+vlj71tT39
schema:
type: string
messageId:
in: query
name: messageId
required: false
description: >-
The ID of the message to search for. Special characters need to be
encoded using URL encoding. Message IDs could come in different formats,
e.g., 9e0df4ca-b18d-40d7-a59f-82fcdf5ae8e6 and
1589228074636lm4k2je7j7jklbn2 are valid message ID formats. Note that
you must include at least one query parameter.
example: 9e0df4ca-b18d-40d7-a59f-82fcdf5ae8e6
schema:
type: string
sourceTn:
in: query
name: sourceTn
required: false
description: >-
The phone number that sent the message. Accepted values are: a single
full phone number a comma separated list of full phone numbers (maximum
of 10) or a single partial phone number (minimum of 5 characters e.g.
'%2B1919').
example: '%2B15554443333'
schema:
type: string
destinationTn:
in: query
name: destinationTn
required: false
description: >-
The phone number that received the message. Accepted values are: a
single full phone number a comma separated list of full phone numbers
(maximum of 10) or a single partial phone number (minimum of 5
characters e.g. '%2B1919').
example: '%2B15554443333'
schema:
type: string
messageStatus:
in: query
name: messageStatus
required: false
description: >-
The status of the message. One of RECEIVED QUEUED SENDING SENT FAILED
DELIVERED ACCEPTED UNDELIVERED.
schema:
$ref: '#/components/schemas/messageStatusEnum'
messageDirection:
in: query
name: messageDirection
required: false
description: The direction of the message. One of INBOUND OUTBOUND.
schema:
$ref: '#/components/schemas/listMessageDirectionEnum'
carrierName:
in: query
name: carrierName
required: false
description: >-
The name of the carrier used for this message. Possible values include
but are not limited to Verizon and TMobile. Special characters need to
be encoded using URL encoding (i.e. AT&T should be passed as AT%26T).
example: Verizon
schema:
type: string
messageType:
in: query
name: messageType
required: false
description: The type of message. Either sms or mms.
schema:
$ref: '#/components/schemas/messageTypeEnum'
errorCode:
in: query
name: errorCode
required: false
description: The error code of the message.
example: 9902
schema:
type: integer
fromDateTime:
in: query
name: fromDateTime
required: false
description: >-
The start of the date range to search in ISO 8601 format. Uses the
message receive time. The date range to search in is currently 14 days.
example: 2022-09-14T18:20:16.000Z
schema:
type: string
toDateTime:
in: query
name: toDateTime
required: false
description: >-
The end of the date range to search in ISO 8601 format. Uses the message
receive time. The date range to search in is currently 14 days.
example: 2022-09-14T18:20:16.000Z
schema:
type: string
campaignId:
in: query
name: campaignId
required: false
description: The campaign ID of the message.
example: CJEUMDK
schema:
type: string
fromBwLatency:
in: query
name: fromBwLatency
required: false
description: >-
The minimum Bandwidth latency of the message in seconds. Only available
for accounts with the Advanced Quality Metrics feature enabled.
example: 5
schema:
type: integer
bwQueued:
in: query
name: bwQueued
required: false
description: >-
A boolean value indicating whether the message is queued in the
Bandwidth network.
example: true
schema:
type: boolean
product:
in: query
name: product
required: false
description: Messaging product associated with the message.
example: P2P
schema:
$ref: '#/components/schemas/productTypeEnum'
location:
in: query
name: location
required: false
description: Location Id associated with the message.
example: 123ABC
schema:
type: string
carrierQueued:
in: query
name: carrierQueued
required: false
description: >-
A boolean value indicating whether the message is queued in the carrier
network. Only available for OUTBOUND messages from accounts with the
Advanced Quality Metrics feature enabled.
example: true
schema:
type: boolean
fromCarrierLatency:
in: query
name: fromCarrierLatency
required: false
description: >-
The minimum carrier latency of the message in seconds. Only available
for OUTBOUND messages from accounts with the Advanced Quality Metrics
feature enabled.
example: 50
schema:
type: integer
callingNumberCountryA3:
in: query
name: callingNumberCountryA3
required: false
description: Calling number country in A3 format.
example: USA
schema:
type: string
calledNumberCountryA3:
in: query
name: calledNumberCountryA3
required: false
description: Called number country in A3 format.
example: USA
schema:
type: string
fromSegmentCount:
in: query
name: fromSegmentCount
required: false
description: Segment count (start range).
example: 1
schema:
type: integer
toSegmentCount:
in: query
name: toSegmentCount
required: false
description: Segment count (end range).
example: 3
schema:
type: integer
fromMessageSize:
in: query
name: fromMessageSize
required: false
description: Message size (start range).
example: 100
schema:
type: integer
toMessageSize:
in: query
name: toMessageSize
required: false
description: Message size (end range).
example: 120
schema:
type: integer
sort:
in: query
name: sort
required: false
description: >-
The field and direction to sort by combined with a colon. Direction is
either asc or desc.
example: sourceTn:desc
schema:
type: string
pageToken:
in: query
name: pageToken
required: false
description: A base64 encoded value used for pagination of results.
example: gdEewhcJLQRB5
schema:
type: string
limit:
in: query
name: limit
required: false
description: >-
The maximum records requested in search result. Default 100. The sum of
limit and after cannot be more than 10000.
schema:
type: integer
example: 50
limitTotalCount:
in: query
name: limitTotalCount
required: false
description: >-
When set to true, the response's totalCount field will have a maximum
value of 10,000. When set to false, or excluded, this will give an
accurate totalCount of all messages that match the provided filters. If
you are experiencing latency, try using this parameter to limit your
results.
example: true
schema:
type: boolean
callId:
name: callId
in: path
required: true
schema:
type: string
description: Programmable Voice API Call ID.
example: c-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85
recordingId:
name: recordingId
in: path
required: true
schema:
type: string
description: Programmable Voice API Recording ID.
example: r-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85
conferenceId:
name: conferenceId
in: path
required: true
schema:
type: string
description: Programmable Voice API Conference ID.
example: conf-fe23a767-a75a5b77-20c5-4cca-b581-cbbf0776eca9
memberId:
name: memberId
in: path
required: true
schema:
type: string
description: Programmable Voice API Conference Member ID.
example: c-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85
transcriptionId:
name: transcriptionId
in: path
required: true
schema:
type: string
description: Programmable Voice API Transcription ID.
example: t-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85
to:
name: to
in: query
required: false
schema:
type: string
description: Filter results by the `to` field.
example: '%2b19195551234'
from:
name: from
in: query
required: false
schema:
type: string
description: Filter results by the `from` field.
example: '%2b19195554321'
name:
name: name
in: query
required: false
schema:
type: string
description: Filter results by the `name` field.
example: my-custom-name
minCreatedTime:
name: minCreatedTime
in: query
required: false
schema:
type: string
description: >-
Filter results to conferences which have a `createdTime` after or at
`minCreatedTime` (in ISO8601 format).
example: '2022-06-21T19:13:21Z'
maxCreatedTime:
name: maxCreatedTime
in: query
required: false
schema:
type: string
description: >-
Filter results to conferences which have a `createdTime` before or at
`maxCreatedTime` (in ISO8601 format).
example: '2022-06-21T19:13:21Z'
minStartTime:
name: minStartTime
in: query
required: false
schema:
type: string
description: >-
Filter results to recordings which have a `startTime` after or including
`minStartTime` (in ISO8601 format).
example: '2022-06-21T19:13:21Z'
maxStartTime:
name: maxStartTime
in: query
required: false
schema:
type: string
description: >-
Filter results to recordings which have a `startTime` before
`maxStartTime` (in ISO8601 format).
example: '2022-06-21T19:13:21Z'
pageSize:
name: pageSize
in: query
required: false
schema:
type: integer
format: int32
minimum: 1
maximum: 1000
default: 1000
description: Specifies the max number of conferences that will be returned.
example: 500
minStartTimeCalls:
name: minStartTime
in: query
required: false
schema:
type: string
description: >-
Filter results to calls which have a `startTime` after or including
`minStartTime` (in ISO8601 format).
example: '2022-06-21T19:13:21Z'
maxStartTimeCalls:
name: maxStartTime
in: query
required: false
schema:
type: string
description: >-
Filter results to calls which have a `startTime` before or including
`maxStartTime` (in ISO8601 format).
example: '2022-06-21T19:13:21Z'
pageSizeCalls:
name: pageSize
in: query
required: false
schema:
type: integer
format: int32
minimum: 1
maximum: 10000
default: 1000
description: Specifies the max number of calls that will be returned.
example: 500
pageToken1:
name: pageToken
in: query
required: false
schema:
type: string
description: >-
Not intended for explicit use. To use pagination, follow the links in
the `Link` header of the response, as indicated in the endpoint
description.
example: eyJwYWdlVG9rZW4iOiJ0b2tlbiJ9
disconnectCause:
name: disconnectCause
in: query
required: false
schema:
type: string
description: Filter results to calls with specified call Disconnect Cause.
example: hangup
accountId1:
in: path
name: accountId
required: true
schema:
type: string
description: Your Bandwidth Account ID.
example: '9900000'
requestId:
in: path
name: requestId
required: true
schema:
type: string
format: uuid
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
endpointId:
name: endpointId
in: path
required: true
schema:
type: string
example: e-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85
description: BRTC Endpoint ID.
endpointType:
name: type
in: query
schema:
$ref: '#/components/schemas/endpointTypeEnum'
description: The type of endpoint.
endpointStatus:
name: status
in: query
schema:
$ref: '#/components/schemas/endpointStatusEnum'
description: The status of the endpoint.
afterCursor:
name: afterCursor
in: query
schema:
type: string
example: TWF5IHRoZSBmb3JjZSBiZSB3aXRoIHlvdQ==
description: >-
The cursor to use for pagination. This is the value of the `next` link
in the previous response.
limit1:
name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 1000
default: 100
example: 2
description: The maximum number of endpoints to return in the response.
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: Number Lookup Request
value:
phoneNumbers:
- '+19196104423'
multipleNumberRequestExample:
summary: Number Lookup Request for Multiple Numbers
value:
phoneNumbers:
- '+19196104423'
- '+19196104424'
rcsAgentRequestExample:
summary: Number Lookup Request with Custom RCS Agent
value:
phoneNumbers:
- '+19196104423'
- '+19196104424'
rcsAgent: MyCustomRcsAgent
lookupAcceptedExample:
summary: Numbers Lookup Accepted
value:
links:
- href: >-
/accounts/9912345/phoneNumberLookup/bulk/004223a0-8b17-41b1-bf81-20732adf5590
rel: createdRequest
method: GET
data:
requestId: 004223a0-8b17-41b1-bf81-20732adf5590
status: IN_PROGRESS
results: []
errors: []
lookupInProgressExample:
summary: Numbers Lookup In Progress
value:
links: []
data:
requestId: 004223a0-8b17-41b1-bf81-20732adf5590
status: IN_PROGRESS
results: []
errors: []
lookupFailedExample:
summary: Numbers Lookup Failed
value:
links: []
data:
requestId: 004223a0-8b17-41b1-bf81-20732adf5590
status: FAILED
results: []
errors:
- code: NO-MATCH
description: The following TNs could not be found in the Number Industry data
meta:
phoneNumbers:
- '+13992077164'
message: Invalid TNs
code: 1001
type: NumberInventory
lookupPartialExample:
summary: Numbers Lookup Partial Complete
value:
links: []
data:
requestId: 004223a0-8b17-41b1-bf81-20732adf5590
status: PARTIAL_COMPLETE
results:
- phoneNumber: '+19196104423'
lineType: MOBILE
messagingProvider: Verizon Wireless
voiceProvider: Verizon Wireless
countryCodeA3: USA
- phoneNumber: '+19196104424'
lineType: MOBILE
messagingProvider: T-Mobile USA
voiceProvider: T-Mobile USA
countryCodeA3: USA
errors:
- code: NO-MATCH
description: The following TNs could not be found in the Number Industry data
meta:
phoneNumbers:
- '+13992077164'
message: Invalid TNs
code: 1001
type: NumberInventory
lookupCompleteExample:
summary: Numbers Lookup Complete (without DNI)
value:
links: []
data:
requestId: 004223a0-8b17-41b1-bf81-20732adf5590
status: COMPLETE
results:
- phoneNumber: '+10072904497'
lineType: MOBILE
messagingProvider: Verizon Wireless
voiceProvider: Verizon Wireless
countryCodeA3: USA
- phoneNumber: '+10072904498'
lineType: MOBILE
messagingProvider: T-Mobile USA
voiceProvider: T-Mobile USA
countryCodeA3: USA
errors: []
lookupCompleteWithDniExample:
summary: Numbers Lookup Complete (with DNI)
value:
links: []
data:
requestId: 20732adf-bf81-8b17-41b1-004223a05590
status: COMPLETE
results:
- phoneNumber: '+10072904497'
countryCodeA3: USA
lineType: MOBILE
messagingProvider: T-MOBILE USA INC
voiceProvider: T-MOBILE USA INC
latestMessageDeliveryStatus: ACTIVE
initialMessageDeliveryStatusDate: '2025-05-14'
latestMessageDeliveryStatusDate: '2025-05-18'
- phoneNumber: '+10072904498'
countryCodeA3: USA
lineType: MOBILE
voiceProvider: VERIZON
latestMessageDeliveryStatus: DEACTIVATED
initialMessageDeliveryStatusDate: '2025-09-05'
latestMessageDeliveryStatusDate: '2025-09-05'
- phoneNumber: '+10072904499'
lineType: MOBILE
countryCodeA3: USA
messagingProvider: VERIZON
voiceProvider: VERIZON
deactivationReporter: Verizon Wireless
deactivationDate: '2025-09-29 01:23:00'
deactivationEvent: DEACTIVATED
latestMessageDeliveryStatus: UNKNOWN
- phoneNumber: '+10072904500'
lineType: FIXED
countryCodeA3: USA
voiceProvider: VERIZON
deactivationReporter: Verizon Wireless
deactivationDate: '2025-09-29 01:23:00'
deactivationEvent: DEACTIVATED
latestMessageDeliveryStatus: NOT_ENABLED
errors: []
lookupCompleteWithRcsExample:
summary: Numbers Lookup Complete (with RCS)
value:
links: []
data:
requestId: 004223a0-8b17-41b1-bf81-20732adf5590
status: COMPLETE
results:
- phoneNumber: '+10072904497'
lineType: MOBILE
messagingProvider: Verizon Wireless
voiceProvider: Verizon Wireless
countryCodeA3: USA
rcsEnabled: true
- phoneNumber: '+10072904498'
lineType: MOBILE
messagingProvider: T-Mobile USA
voiceProvider: T-Mobile USA
countryCodeA3: USA
rcsEnabled: false
errors: []
lookupCompleteWithRcsErrorExample:
summary: Numbers Lookup Complete (with RCS error)
value:
links: []
data:
requestId: 004223a0-8b17-41b1-bf81-20732adf5590
status: COMPLETE
results:
- phoneNumber: '+10072904497'
lineType: MOBILE
messagingProvider: Verizon Wireless
voiceProvider: Verizon Wireless
countryCodeA3: USA
- phoneNumber: '+10072904498'
lineType: MOBILE
messagingProvider: T-Mobile USA
voiceProvider: T-Mobile USA
countryCodeA3: USA
errors:
- code: RCS_SERVICE_UNAVAILABLE
type: rcs-error
description: An exception was thrown during the async RCS service call.
meta:
phoneNumbers:
- '+10072904497'
- code: MISSING_FROM_RESPONSE
type: rcs-error
description: The phone number was absent from the RCS service response.
meta:
phoneNumbers:
- '+10072904498'
badRequestExample:
summary: Example Bad Request Error
value:
links: []
data: {}
errors:
- type: bad-request
description: >-
Bad Request. Ensure that you have set the requestId as a URL path
parameter.
unauthorizedExample:
summary: Unauthorized Error
value:
links: []
data: {}
errors:
- type: Unauthorized
description: You are not authorized to access this resource.
code: '1'
page: null
forbiddenExample:
summary: Forbidden Error
value:
links: []
data: {}
errors:
- type: Forbidden
description: You do not have permission to access this resource.
code: '2'
page: null
unsupportedMediaTypeExample:
summary: Unsupported Media Type Error
value:
links: []
data: {}
errors:
- type: invalid-content-type
description: >-
Invalid content-type. Ensure that your content-type header is set
to application/json.
notFoundExample:
summary: Not Found Error
value:
links: []
data: {}
errors:
- type: not-found
description: >-
RequestId not found. Ensure that the requestId used in the URL
path is valid and maps to a previous request that was submitted.
tooManyRequestsExample:
summary: Too Many Requests Error
value:
links: []
data: {}
errors:
- type: rate-limiting
description: >-
Rate limit exceeded. Wait for the time specified in the
Retry-After header before sending another request.
internalServerErrorExample:
summary: Internal Server Error
value:
links: []
data: {}
errors:
- code: '500'
type: unexpected-error
description: >-
Unexpected error. Please contact Bandwidth Support if your
requests are receiving this status code for an extended period of
time.
listEndpointsResponseExample:
summary: List Endpoints Paginated Response
value:
links:
- href: >-
https://api.bandwidth.com/v2/accounts/5500123/endpoints?type=SIP&status=CONNECTED&limit=2
rel: self
method: GET
- href: >-
https://api.bandwidth.com/v2/accounts/5500123/endpoints?type=SIP&status=CONNECTED&limit=2&afterCursor=TWF5IHRoZSBmb3JjZSBiZSB3aXRoIHlvdQ==
rel: next
method: GET
page:
pageSize: 2
totalElements: 10
totalPages: 5
pageNumber: 0
data:
- endpointId: e-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85
type: WEBRTC
status: CONNECTED
creationTimestamp: '2021-01-01T00:00:00Z'
expirationTimestamp: '2021-01-02T00:00:00Z'
tag: my-tag
- endpointId: e-2cb0-4a07-b215-b22865662d85-15ac29a2-1331029c
type: WEBRTC
status: CONNECTED
creationTimestamp: '2021-01-01T00:00:00Z'
expirationTimestamp: '2021-01-02T00:00:00Z'
tag: my-tag
errors: []
createEndpointResponseExample:
summary: Create Endpoint Response
value:
links:
- href: >-
https://api.bandwidth.com/v2/accounts/5500123/endpoints/e-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85
rel: endpoint
method: GET
data:
endpointId: e-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85
token: xxxxx.yyyyy.zzzzz
type: WEBRTC
status: CONNECTED
creationTimestamp: '2021-01-01T00:00:00Z'
expirationTimestamp: '2021-01-02T00:00:00Z'
devices: []
tag: my-tag
errors: []
getEndpointResponseExample:
summary: Get Endpoint Response
value:
links:
- href: >-
https://api.bandwidth.com/v2/accounts/5500123/endpoints/e-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85
rel: self
method: GET
data:
endpointId: e-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85
type: WEBRTC
status: CONNECTED
creationTimestamp: '2021-01-01T00:00:00Z'
expirationTimestamp: '2021-01-02T00:00:00Z'
devices: []
tag: my-tag
errors: []
createSipEndpointRequestExample:
summary: SIP Endpoint Example
value:
type: SIP
connectionMetadata:
ipAddress: 0.0.0.0
port: 3000
credentials:
username: username
password: '********'
uuiHeader: 123456;encoding=jwt
direction: INBOUND
eventCallbackUrl: https://myEventCallbackUrl.com/callbacks/bandwidth
eventFallbackUrl: https://fallback.myEventCallbackUrl.com/callbacks/bandwidth
tag: '{"myTag": "myTagValue"}'
createWeRtcEndpointExample:
summary: WebRTC Endpoint Example
value:
type: WEBRTC
direction: BIDIRECTIONAL
eventCallbackUrl: https://myEventCallbackUrl.com/callbacks/bandwidth
eventFallbackUrl: https://fallback.myEventCallbackUrl.com/callbacks/bandwidth
tag: '{"myTag": "myTagValue"}'
updateEndpointBxmlRequestExample:
summary: Update Endpoint BXML Request Example
value:
This is a test sentence.
redirectUrl:
summary: Redirect
value: |-
updateCallRecordingRequest:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/updateCallRecording'
transcribeRecordingRequest:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/transcribeRecording'
updateConferenceRequest:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/updateConference'
updateConferenceBxmlRequest:
required: true
content:
application/xml:
schema:
type: string
description: A valid BXML document to replace the call's current BXML.
examples:
stopRecording:
summary: Stop Recording
value: |-
updateConferenceMemberRequest:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/updateConferenceMember'
codeRequest:
description: MFA code request body.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/codeRequest'
codeVerify:
description: MFA code verify request body.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/verifyCodeRequest'
createSyncLookupRequest:
description: Synchronous phone number lookup request.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/syncLookupRequest'
examples:
singleNumberRequestExample:
$ref: '#/components/examples/singleNumberRequestExample'
multipleNumberRequestExample:
$ref: '#/components/examples/multipleNumberRequestExample'
rcsAgentRequestExample:
$ref: '#/components/examples/rcsAgentRequestExample'
createAsyncBulkLookupRequest:
description: Asynchronous bulk phone number lookup request.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/asyncLookupRequest'
examples:
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'
- $ref: '#/components/schemas/blockedWebhook'
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'
createEndpointRequest:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/createEndpointRequest'
examples:
createWebRtcEndpointRequestExample:
$ref: '#/components/examples/createWeRtcEndpointExample'
updateEndpointBxmlRequest:
required: true
content:
application/xml:
schema:
type: string
description: >-
The BXML document to update the endpoint with. This BXML document
will be executed against the endpoint when it is updated.
For more information, please refer to our [BXML
documentation](/docs/voice/bxml/).
examples:
updateEndpointBxmlRequestExample:
$ref: '#/components/examples/updateEndpointBxmlRequestExample'
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==`
OAuth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api.bandwidth.com/api/v1/oauth2/token
scopes: {}
callbacks:
inboundCallback:
'{inboundCallbackUrl}':
post:
requestBody:
required: true
description: >-
This Inbound Message Webhook is an envelope containing either a
received (MO) message to your
message-enabled Bandwidth telephone number or a multichannel
client's response to a suggestion response
or location request.
The payload type will be one of message-received,
suggestion-response, or
location-request-response.
Note that suggestion-response and
location-request-response callback types are
pertinent only for RBM messages sent from the
/messages/multiChannel endpoint.
Please visit Webhooks
content:
application/json:
schema:
$ref: '#/components/schemas/inboundCallback'
examples:
smsMessageReceivedCallback:
$ref: '#/components/examples/smsMessageReceivedCallbackExample'
mmsMessageReceivedCallback:
$ref: '#/components/examples/mmsMessageReceivedCallbackExample'
responses:
'200':
description: OK
'202':
description: Accepted
statusCallback:
'{statusCallbackUrl}':
post:
requestBody:
required: true
description: >-
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, message-failed or message-read.
Note that message-read callbacks are pertinent only for RBM messages sent from the /messages/multiChannel endpoint.
Please visit Webhooks
content:
application/json:
schema:
$ref: '#/components/schemas/statusCallback'
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
'202':
description: Accepted
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':
$ref: '#/components/responses/noContentResponse'
'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'
endpointEvent:
'{request.body#/eventCallbackUrl}':
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/endpointEvent'
examples:
endpointDisconnectedEventExample:
$ref: '#/components/examples/endpointDisconnectedEventExample'
responses:
'204':
description: Event was successfully received.