Telnyx Verification Requests API
Manage your tollfree verification requests
Manage your tollfree verification requests
openapi: 3.1.0
info:
contact:
email: support@telnyx.com
description: Telnyx provides global communications and connectivity APIs for developers — including SIP trunking, programmable voice, SMS, MMS, WhatsApp Business Messaging, Call Control, Fax, Wireless (IoT & eSIM), Phone Numbers (DID provisioning & porting), Emergency Services, and Network APIs for private interconnects and edge connectivity. Build, scale, and manage voice, messaging, and data networks with Telnyx's carrier-grade global infrastructure and API-first platform.
title: Telnyx Access Tokens Verification Requests API
version: 2.0.0
x-endpoint-cost: light
servers:
- description: Version 2.0.0 of the Telnyx API
url: https://api.telnyx.com/v2
security:
- bearerAuth: []
tags:
- description: Manage your tollfree verification requests
name: Verification Requests
paths:
/messaging_tollfree/verification/requests:
get:
description: Get a list of previously-submitted tollfree verification requests
operationId: ListVerificationRequests
parameters:
- in: query
name: page
required: true
schema:
minimum: 1
title: Page
type: integer
- description: "\n Request this many records per page\n\n This value is automatically clamped if the provided value is too large.\n "
in: query
name: page_size
required: true
schema:
description: "\n Request this many records per page\n\n This value is automatically clamped if the provided value is too large.\n "
minimum: 1
title: Page Size
type: integer
- in: query
name: date_start
required: false
schema:
format: date-time
title: Date Start
type: string
- in: query
name: date_end
required: false
schema:
format: date-time
title: Date End
type: string
- in: query
name: status
required: false
schema:
$ref: '#/components/schemas/TFVerificationStatus'
- in: query
name: phone_number
required: false
schema:
title: Phone Number
type: string
- description: Filter verification requests by business name
in: query
name: business_name
required: false
schema:
title: Business Name
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Paginated_VerificationRequestStatus_'
description: Successful Response
4XX:
$ref: '#/components/responses/toll-free-verification_GenericErrorResponse'
summary: List Verification Requests
tags:
- Verification Requests
x-latency-category: responsive
post:
description: Submit a new tollfree verification request
operationId: SubmitVerificationRequest
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TFVerificationRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/VerificationRequestEgress'
description: Successful Response
4XX:
$ref: '#/components/responses/toll-free-verification_GenericErrorResponse'
summary: Submit Verification Request
tags:
- Verification Requests
x-latency-category: responsive
/messaging_tollfree/verification/requests/{id}:
delete:
description: 'Delete a verification request
A request may only be deleted when when the request is in the "rejected" state.
* `HTTP 200`: request successfully deleted
* `HTTP 400`: request exists but can''t be deleted (i.e. not rejected)
* `HTTP 404`: request unknown or already deleted'
operationId: DeleteVerificationRequest
parameters:
- in: path
name: id
required: true
schema:
format: uuid
title: Id
type: string
responses:
'200':
description: Successful deleted
'404':
$ref: '#/components/responses/toll-free-verification_GenericErrorResponse'
description: Not Found
4XX:
$ref: '#/components/responses/toll-free-verification_GenericErrorResponse'
summary: Delete Verification Request
tags:
- Verification Requests
x-latency-category: responsive
get:
description: Get a single verification request by its ID.
operationId: GetVerificationRequest
parameters:
- in: path
name: id
required: true
schema:
format: uuid
title: Id
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/VerificationRequestStatus'
description: Successful Response
4XX:
$ref: '#/components/responses/toll-free-verification_GenericErrorResponse'
summary: Get Verification Request
tags:
- Verification Requests
x-latency-category: responsive
patch:
description: Update an existing tollfree verification request. This is particularly useful when there are pending customer actions to be taken.
operationId: UpdateVerificationRequest
parameters:
- in: path
name: id
required: true
schema:
format: uuid
title: Id
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TFVerificationRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/VerificationRequestEgress'
description: Successful Response
4XX:
$ref: '#/components/responses/toll-free-verification_GenericErrorResponse'
summary: Update Verification Request
tags:
- Verification Requests
x-latency-category: responsive
/messaging_tollfree/verification/requests/{id}/status_history:
get:
description: 'Get the history of status changes for a verification request.
Returns a paginated list of historical status changes including the reason for each change and when it occurred.'
operationId: GetVerificationStatusHistory
parameters:
- in: path
name: id
required: true
schema:
format: uuid
title: Id
type: string
- in: query
name: page[number]
required: true
schema:
minimum: 1
title: Page Number
type: integer
- in: query
name: page[size]
required: true
schema:
description: Request this many records per page. This value is automatically clamped if the provided value is too large.
minimum: 1
title: Page Size
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Paginated_VerificationStatusHistoryEntry_'
description: Successful Response
4XX:
$ref: '#/components/responses/toll-free-verification_GenericErrorResponse'
summary: Get Verification Request Status History
tags:
- Verification Requests
x-latency-category: responsive
components:
schemas:
Paginated_VerificationStatusHistoryEntry_:
description: A paginated response
properties:
records:
default: []
description: The records yielded by this request
items:
$ref: '#/components/schemas/VerificationStatusHistoryEntry'
title: Records
type: array
total_records:
default: 0
description: The total amount of records for these query parameters
title: Total Records
type: integer
required:
- records
- total_records
title: Paginated[VerificationStatusHistoryEntry]
type: object
toll-free-verification_Errors:
properties:
errors:
items:
$ref: '#/components/schemas/toll-free-verification_Error'
type: array
type: object
toll-free-verification_Error:
properties:
code:
type: string
detail:
type: string
meta:
additionalProperties: true
type: object
source:
properties:
parameter:
description: Indicates which query parameter caused the error.
type: string
pointer:
description: JSON pointer (RFC6901) to the offending entity.
type: string
type: object
title:
type: string
required:
- code
- title
type: object
UseCaseCategories:
description: Tollfree usecase categories
enum:
- 2FA
- App Notifications
- Appointments
- Auctions
- Auto Repair Services
- Bank Transfers
- Billing
- Booking Confirmations
- Business Updates
- COVID-19 Alerts
- Career Training
- Chatbot
- Conversational / Alerts
- Courier Services & Deliveries
- Emergency Alerts
- Events & Planning
- Financial Services
- Fraud Alerts
- Fundraising
- General Marketing
- General School Updates
- HR / Staffing
- Healthcare Alerts
- Housing Community Updates
- Insurance Services
- Job Dispatch
- Legal Services
- Mixed
- Motivational Reminders
- Notary Notifications
- Order Notifications
- Political
- Public Works
- Real Estate Services
- Religious Services
- Repair and Diagnostics Alerts
- Rewards Program
- Surveys
- System Alerts
- Voting Reminders
- Waitlist Alerts
- Webinar Reminders
- Workshop Alerts
title: UseCaseCategories
type: string
VerificationRequestStatus:
description: A verification request and its status, suitable for returning to users
properties:
additionalInformation:
example: This is for security purposes, blah blah blah
title: Additionalinformation
type: string
ageGatedContent:
example: false
title: Agegatedcontent
type: boolean
businessAddr1:
example: 600 Congress Avenue
title: Businessaddr1
type: string
businessAddr2:
example: 14th Floor
title: Businessaddr2
type: string
businessCity:
example: Austin
title: Businesscity
type: string
businessContactEmail:
example: email@example.com
title: Businesscontactemail
type: string
businessContactFirstName:
example: John
title: Businesscontactfirstname
type: string
businessContactLastName:
example: Doe
title: Businesscontactlastname
type: string
businessContactPhone:
example: '+18889809750'
title: Businesscontactphone
type: string
businessName:
example: Telnyx LLC
title: Businessname
type: string
businessRegistrationCountry:
example: US
title: Businessregistrationcountry
type: string
businessRegistrationNumber:
example: 12-3456789
title: Businessregistrationnumber
type: string
businessRegistrationType:
example: EIN
title: Businessregistrationtype
type: string
businessState:
example: Texas
title: Businessstate
type: string
businessZip:
example: '78701'
title: Businesszip
type: string
campaignVerifyAuthorizationToken:
description: Campaign Verify Authorization Token required for Political use case submissions starting February 17, 2026
example: cv_token_abc123xyz
maxLength: 500
title: Campaignverifyauthorizationtoken
type:
- string
- 'null'
corporateWebsite:
example: http://example.com
title: Corporatewebsite
type: string
createdAt:
example: '2024-01-23T18:10:02.574Z'
format: date-time
title: Createdat
type: string
doingBusinessAs:
example: Acme Services
title: Doingbusinessas
type: string
entityType:
allOf:
- $ref: '#/components/schemas/toll-free-verification_EntityType'
example: PRIVATE_PROFIT
helpMessageResponse:
example: 'Reply HELP for assistance or STOP to unsubscribe. Contact: support@example.com'
title: Helpmessageresponse
type: string
id:
example: eaba9f52-164e-58e0-b002-4f668e18b7ed
format: uuid
title: Id
type: string
isvReseller:
example: 'Yes'
title: Isvreseller
type: string
messageVolume:
allOf:
- $ref: '#/components/schemas/Volume'
description: 'One of the following exact values: 10; 100; 1,000; 10,000; 100,000; 250,000; 500,000; 750,000; 1,000,000; 5,000,000; 10,000,000+'
example: 100,000
optInConfirmationResponse:
example: You have successfully opted in to receive messages from Acme Corp
title: Optinconfirmationresponse
type: string
optInKeywords:
example: START, YES, SUBSCRIBE
title: Optinkeywords
type: string
optInWorkflow:
example: User signs into the Telnyx portal, enters number and is prompted to select whether they want to use 2FA verification for security purposes. If they've opted in a confirmation message is sent out to the handset
title: Optinworkflow
type: string
optInWorkflowImageURLs:
example:
- url: https://telnyx.com/sign-up
- url: https://telnyx.com/company/data-privacy
items:
$ref: '#/components/schemas/Url'
title: Optinworkflowimageurls
type: array
phoneNumbers:
example:
- phoneNumber: '+18773554398'
- phoneNumber: '+18773554399'
items:
$ref: '#/components/schemas/TFPhoneNumber'
title: Phonenumbers
type: array
privacyPolicyURL:
example: https://example.com/privacy
title: Privacypolicyurl
type: string
productionMessageContent:
example: Your Telnyx OTP is XXXX
title: Productionmessagecontent
type: string
reason:
example: Unfortunately, we have to cancel this request as we do not support non tollfree US numbers.
title: Reason
type: string
termsAndConditionURL:
example: https://example.com/terms
title: Termsandconditionurl
type: string
updatedAt:
example: '2024-01-23T18:10:02.574Z'
format: date-time
title: Updatedat
type: string
useCase:
allOf:
- $ref: '#/components/schemas/UseCaseCategories'
example: 2FA
useCaseSummary:
example: This is a use case where Telnyx sends out 2FA codes to portal users to verify their identity in order to sign into the portal
title: Usecasesummary
type: string
verificationStatus:
allOf:
- $ref: '#/components/schemas/TFVerificationStatus'
example: Waiting For Customer
webhookUrl:
example: http://example-webhook.com
title: Webhookurl
type: string
required:
- businessName
- corporateWebsite
- businessAddr1
- businessCity
- businessState
- businessZip
- businessContactFirstName
- businessContactLastName
- businessContactEmail
- businessContactPhone
- messageVolume
- phoneNumbers
- useCase
- useCaseSummary
- productionMessageContent
- optInWorkflow
- optInWorkflowImageURLs
- additionalInformation
- id
- verificationStatus
title: VerificationRequestStatus
type: object
VerificationRequestEgress:
description: A verification request as it comes out of the database
properties:
additionalInformation:
example: This is for security purposes, blah blah blah
title: Additionalinformation
type: string
ageGatedContent:
example: false
title: Agegatedcontent
type: boolean
businessAddr1:
example: 600 Congress Avenue
title: Businessaddr1
type: string
businessAddr2:
example: 14th Floor
title: Businessaddr2
type: string
businessCity:
example: Austin
title: Businesscity
type: string
businessContactEmail:
example: email@example.com
title: Businesscontactemail
type: string
businessContactFirstName:
example: John
title: Businesscontactfirstname
type: string
businessContactLastName:
example: Doe
title: Businesscontactlastname
type: string
businessContactPhone:
example: '+18005550100'
title: Businesscontactphone
type: string
businessName:
example: Telnyx LLC
title: Businessname
type: string
businessRegistrationCountry:
example: US
title: Businessregistrationcountry
type: string
businessRegistrationNumber:
example: 12-3456789
title: Businessregistrationnumber
type: string
businessRegistrationType:
example: EIN
title: Businessregistrationtype
type: string
businessState:
example: Texas
title: Businessstate
type: string
businessZip:
example: '78701'
title: Businesszip
type: string
campaignVerifyAuthorizationToken:
description: Campaign Verify Authorization Token required for Political use case submissions starting February 17, 2026
example: cv_token_abc123xyz
maxLength: 500
title: Campaignverifyauthorizationtoken
type:
- string
- 'null'
corporateWebsite:
example: http://example.com
title: Corporatewebsite
type: string
doingBusinessAs:
example: Acme Services
title: Doingbusinessas
type: string
entityType:
allOf:
- $ref: '#/components/schemas/toll-free-verification_EntityType'
example: PRIVATE_PROFIT
helpMessageResponse:
example: 'Reply HELP for assistance or STOP to unsubscribe. Contact: support@example.com'
title: Helpmessageresponse
type: string
id:
format: uuid
title: Id
type: string
isvReseller:
example: 'Yes'
title: Isvreseller
type: string
messageVolume:
allOf:
- $ref: '#/components/schemas/Volume'
description: 'One of the following exact values: 10; 100; 1,000; 10,000; 100,000; 250,000; 500,000; 750,000; 1,000,000; 5,000,000; 10,000,000+'
example: 100,000
optInConfirmationResponse:
example: You have successfully opted in to receive messages from Acme Corp
title: Optinconfirmationresponse
type: string
optInKeywords:
example: START, YES, SUBSCRIBE
title: Optinkeywords
type: string
optInWorkflow:
example: User signs into the Telnyx portal, enters number and is prompted to select whether they want to use 2FA verification for security purposes. If they've opted in a confirmation message is sent out to the handset
title: Optinworkflow
type: string
optInWorkflowImageURLs:
example:
- url: https://telnyx.com/sign-up
- url: https://telnyx.com/company/data-privacy
items:
$ref: '#/components/schemas/Url'
title: Optinworkflowimageurls
type: array
phoneNumbers:
example:
- phoneNumber: '+18773554398'
- phoneNumber: '+18773554399'
items:
$ref: '#/components/schemas/TFPhoneNumber'
title: Phonenumbers
type: array
privacyPolicyURL:
example: https://example.com/privacy
title: Privacypolicyurl
type: string
productionMessageContent:
example: Your Telnyx OTP is XXXX
title: Productionmessagecontent
type: string
termsAndConditionURL:
example: https://example.com/terms
title: Termsandconditionurl
type: string
useCase:
allOf:
- $ref: '#/components/schemas/UseCaseCategories'
example: 2FA
useCaseSummary:
example: This is a use case where Telnyx sends out 2FA codes to portal users to verify their identity in order to sign into the portal
title: Usecasesummary
type: string
verificationRequestId:
title: Verificationrequestid
type: string
verificationStatus:
allOf:
- $ref: '#/components/schemas/TFVerificationStatus'
default: In Progress
webhookUrl:
example: http://example-webhook.com
title: Webhookurl
type: string
required:
- businessName
- corporateWebsite
- businessAddr1
- businessCity
- businessState
- businessZip
- businessContactFirstName
- businessContactLastName
- businessContactEmail
- businessContactPhone
- messageVolume
- phoneNumbers
- useCase
- useCaseSummary
- productionMessageContent
- optInWorkflow
- optInWorkflowImageURLs
- additionalInformation
- id
- verificationRequestId
title: VerificationRequestEgress
type: object
TFVerificationRequest:
description: The body of a tollfree verification request
properties:
additionalInformation:
description: Any additional information
maxLength: 500
title: Additionalinformation
type: string
ageGatedContent:
default: false
description: Indicates if messaging content requires age gating (e.g., 18+). Defaults to false if not provided.
title: Agegatedcontent
type: boolean
businessAddr1:
description: Line 1 of the business address
example: 600 Congress Avenue
maxLength: 500
title: Businessaddr1
type: string
businessAddr2:
description: Line 2 of the business address
example: 14th Floor
maxLength: 500
title: Businessaddr2
type: string
businessCity:
description: The city of the business address; the first letter should be capitalized
example: Austin
maxLength: 500
title: Businesscity
type: string
businessContactEmail:
description: The email address of the business contact
example: email@example.com
maxLength: 500
title: Businesscontactemail
type: string
businessContactFirstName:
description: First name of the business contact; there are no specific requirements on formatting
example: John
maxLength: 500
title: Businesscontactfirstname
type: string
businessContactLastName:
description: Last name of the business contact; there are no specific requirements on formatting
example: Doe
maxLength: 500
title: Businesscontactlastname
type: string
businessContactPhone:
description: The phone number of the business contact in E.164 format
example: '+18005550100'
maxLength: 500
title: Businesscontactphone
type: string
businessName:
description: Name of the business; there are no specific formatting requirements
example: Telnyx LLC
maxLength: 500
title: Businessname
type: string
businessRegistrationCountry:
description: ISO 3166-1 alpha-2 country code of the issuing business authority. Must be exactly 2 letters. Automatically converted to uppercase. Required from January 2026.
example: US
maxLength: 2
pattern: ^[A-Z]{2}$
title: Businessregistrationcountry
type:
- string
- 'null'
businessRegistrationNumber:
description: Official business registration number (e.g., Employer Identification Number (EIN) in the U.S.). Required from January 2026.
example: 12-3456789
maxLength: 500
title: Businessregistrationnumber
type:
- string
- 'null'
businessRegistrationType:
description: Type of business registration being provided. Required from January 2026.
example: EIN
maxLength: 500
title: Businessregistrationtype
type:
- string
- 'null'
businessState:
description: The full name of the state (not the 2 letter code) of the business address; the first letter should be capitalized
example: Texas
maxLength: 500
title: Businessstate
type: string
businessZip:
description: The ZIP code of the business address
example: '78701'
maxLength: 500
title: Businesszip
type: string
campaignVerifyAuthorizationToken:
description: Campaign Verify Authorization Token required for Political use case submissions starting February 17, 2026. This token is validated by Zipwhip and must be provided for all Political use case verifications after the deadline.
example: cv_token_abc123xyz
maxLength: 500
title: Campaignverifyauthorizationtoken
type:
- string
- 'null'
corporateWebsite:
description: A URL, including the scheme, pointing to the corporate website
example: http://example.com
maxLength: 500
title: Corporatewebsite
type: string
doingBusinessAs:
description: Doing Business As (DBA) name if different from legal name
example: Acme Services
maxLength: 500
title: Doingbusinessas
type:
- string
- 'null'
entityType:
anyOf:
- $ref: '#/components/schemas/toll-free-verification_EntityType'
- type: 'null'
description: Business entity classification. Must be one of the 5 valid enum values.
helpMessageResponse:
description: The message returned when users text 'HELP'
example: 'Reply HELP for assistance or STOP to unsubscribe. Contact: support@example.com'
maxLength: 500
title: Helpmessageresponse
type:
- string
- 'null'
isvReseller:
description: ISV name
maxLength: 500
title: Isvreseller
type:
- string
- 'null'
messageVolume:
allOf:
- $ref: '#/components/schemas/Volume'
description: Estimated monthly volume of messages from the given phone numbers
example: 100,000
optInConfirmationResponse:
description: Message sent to users confirming their opt-in to receive messages
example: You have successfully opted in to receive messages from Acme Corp
maxLength: 500
title: Optinconfirmationresponse
type:
- string
- 'null'
optInKeywords:
description: Keywords used to collect and process consumer opt-ins
example: START, YES, SUBSCRIBE
maxLength: 500
title: Optinkeywords
type:
- string
- 'null'
optInWorkflow:
description: Human-readable description of how end users will opt into receiving messages from the given phone numbers
example: User signs into the Telnyx portal, enters a number and is prompted to select whether they want to use 2FA verification for security purposes. If they've opted in a confirmation message is sent out to the handset
maxLength: 500
title: Optinworkflow
type: string
optInWorkflowImageURLs:
description: Images showing the opt-in workflow
example:
- url: https://telnyx.com/sign-up
- url: https://telnyx.com/company/data-privacy
items:
$ref: '#/components/schemas/Url'
minItems: 1
title: Optinworkflowimageurls
type: array
phoneNumbers:
description: The phone numbers to request the verification of
example:
- phoneNumber: '+18773554398'
- phoneNumber: '+18773554399'
items:
$ref: '#/components/schemas/TFPhoneNumber'
minItems: 1
title: Phonenumbers
type: array
privacyPolicyURL:
description: URL pointing to the business's privacy policy. Plain string, no URL format validation.
example: https://example.com/privacy
maxLength: 500
title: Privacypolicyurl
type:
- string
- 'null'
productionMessageContent:
description: An example of a message that will be sent from the given phone numbers
example: Your Telnyx OTP is XXXX
maxLength: 1000
title: Productionmessagecontent
type: string
termsAndConditionURL:
description: URL pointing to the business's terms and conditions. Plain string, no URL format validation.
example: https://example.com/terms
maxLength: 500
title: Termsandconditionurl
type:
- string
- 'null'
useCase:
allOf:
- $ref: '#/components/schemas/UseCaseCategories'
description: Machine-readable use-case for the phone numbers
example: 2FA
useCaseSummary:
description: Human-readable summary of the desired use-case
example: This is a use case where Telnyx sends out 2FA codes to portal users to verify their identity in order to sign into the portal
maxLength: 500
title: Usecasesummary
type: string
webhookUrl:
description: URL that should receive webhooks relating to this verification request
example: http://example-webhook.com
maxLength: 500
title: Webhookurl
type: string
required:
- businessName
- corporateWebsite
- businessAddr1
- businessCity
- businessState
- businessZip
- businessContactFirstName
- businessContactLastName
- businessContactEmail
- businessContactPhone
- messageVolume
- phoneNumbers
- useCase
- useCaseSummary
- productionMessageContent
- optInWorkflow
- optInWorkflowImageURLs
- additionalInformation
title: VerificationRequest
type: object
Url:
properties:
url:
format: uri
maxLength: 2083
minLength: 1
title: Url
type: string
required:
- url
title: Url
type: object
Paginated_VerificationRequestStatus_:
description: A paginated response
properties:
records:
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/telnyx/refs/heads/main/openapi/telnyx-verification-requests-api-openapi.yml