OpenAPI Specification
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 Verify 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: Two factor authentication API
name: Verify
paths:
/verifications/by_phone_number/{phone_number}:
get:
operationId: ListVerifications
parameters:
- description: The phone number associated with the verifications to retrieve.
in: path
name: phone_number
required: true
schema:
description: +E164 formatted phone number.
example: '+13035551234'
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListVerificationsResponse'
description: Expected verifications response to a valid request.
'400':
$ref: '#/components/responses/verify_GenericErrorResponse'
summary: List verifications by phone number
tags:
- Verify
x-latency-category: responsive
/verifications/by_phone_number/{phone_number}/actions/verify:
post:
operationId: VerifyVerificationCodeByPhoneNumber
parameters:
- description: The phone number associated with the verification code being verified.
in: path
name: phone_number
required: true
schema:
description: +E164 formatted phone number.
example: '+13035551234'
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyVerificationCodeRequestByPhoneNumber'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyVerificationCodeResponse'
description: Expected verify response to a valid request.
'400':
$ref: '#/components/responses/verify_GenericErrorResponse'
summary: Verify verification code by phone number
tags:
- Verify
x-latency-category: responsive
/verifications/call:
post:
operationId: CreateVerificationCall
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateVerificationRequestCall'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CreateVerificationResponse'
description: Expected verifications response to a valid request.
'400':
$ref: '#/components/responses/verify_GenericErrorResponse'
summary: Trigger Call verification
tags:
- Verify
x-latency-category: responsive
/verifications/flashcall:
post:
operationId: CreateFlashcallVerification
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateVerificationRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CreateVerificationResponse'
description: Expected verifications response to a valid request.
'400':
$ref: '#/components/responses/verify_GenericErrorResponse'
summary: Trigger Flash call verification
tags:
- Verify
x-latency-category: responsive
/verifications/sms:
post:
operationId: CreateVerificationSms
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateVerificationRequestSMS'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CreateVerificationResponse'
description: Expected verifications response to a valid request.
'400':
$ref: '#/components/responses/verify_GenericErrorResponse'
summary: Trigger SMS verification
tags:
- Verify
x-latency-category: responsive
/verifications/whatsapp:
post:
operationId: CreateWhatsappVerification
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateVerificationRequestSMS'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CreateVerificationResponse'
description: Expected verifications response to a valid request.
'400':
$ref: '#/components/responses/verify_GenericErrorResponse'
summary: Trigger WhatsApp verification
tags:
- Verify
x-latency-category: responsive
/verifications/{verification_id}:
get:
operationId: RetrieveVerification
parameters:
- description: The identifier of the verification to retrieve.
in: path
name: verification_id
required: true
schema:
example: 12ade33a-21c0-473b-b055-b3c836e1c292
format: uuid
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RetrieveVerificationResponse'
description: Expected verifications response to a valid request.
'400':
$ref: '#/components/responses/verify_GenericErrorResponse'
summary: Retrieve verification
tags:
- Verify
x-latency-category: responsive
/verifications/{verification_id}/actions/verify:
post:
operationId: VerifyVerificationCodeById
parameters:
- description: The identifier of the verification to retrieve.
in: path
name: verification_id
required: true
schema:
example: 12ade33a-21c0-473b-b055-b3c836e1c292
format: uuid
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyVerificationCodeRequestById'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyVerificationCodeResponse'
description: Expected verify response to a valid request.
'400':
$ref: '#/components/responses/verify_GenericErrorResponse'
summary: Verify verification code by ID
tags:
- Verify
x-latency-category: responsive
/verify_profiles:
get:
description: Gets a paginated list of Verify profiles.
operationId: ListProfiles
parameters:
- description: 'Consolidated filter parameter (deepObject style). Originally: filter[name]'
explode: true
in: query
name: filter
required: false
schema:
properties:
name:
description: Optional filter for profile names.
title: filter[name]
type: string
type: object
style: deepObject
- description: 'Consolidated page parameter (deepObject style). Originally: page[size], page[number]'
explode: true
in: query
name: page
required: false
schema:
properties:
number:
default: 1
title: page[number]
type: integer
size:
default: 25
title: page[size]
type: integer
type: object
style: deepObject
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListVerifyProfilesResponse'
description: Expected Verify profile response to a valid request.
'400':
$ref: '#/components/responses/verify_GenericErrorResponse'
summary: List all Verify profiles
tags:
- Verify
x-group-parameters: 'true'
x-latency-category: responsive
post:
description: Creates a new Verify profile to associate verifications with.
operationId: CreateVerifyProfile
requestBody:
content:
application/json:
schema:
properties:
call:
$ref: '#/components/schemas/CreateVerifyProfileCallRequest'
additionalProperties: true
type: object
daily_spend_limit:
description: The maximum daily spend allowed on this verify profile, in USD.
example: 100.0
minimum: 0
type: number
daily_spend_limit_enabled:
default: false
description: Whether the daily spend limit is enforced for this verify profile.
example: true
type: boolean
flashcall:
$ref: '#/components/schemas/CreateVerifyProfileSettingsRequest'
additionalProperties: true
type: object
language:
example: en-US
type: string
name:
example: Test Profile
type: string
sms:
$ref: '#/components/schemas/CreateVerifyProfileSMSRequest'
additionalProperties: true
type: object
webhook_failover_url:
example: http://example.com/webhook/failover
type: string
webhook_url:
example: http://example.com/webhook
type: string
whatsapp:
$ref: '#/components/schemas/CreateVerifyProfileSettingsWhatsAppRequest'
additionalProperties: true
type: object
required:
- name
title: Create Verify Profile Request
type: object
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyProfileResponseDataWrapper'
description: Expected Verify profile response to a valid request.
'400':
$ref: '#/components/responses/verify_GenericErrorResponse'
summary: Create a Verify profile
tags:
- Verify
x-latency-category: responsive
/verify_profiles/templates:
get:
description: List all Verify profile message templates.
operationId: ListProfileMessageTemplates
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListVerifyProfileMessageTemplateResponse'
description: Expected Verify profile message template response to a valid request.
'400':
$ref: '#/components/responses/verify_GenericErrorResponse'
'500':
$ref: '#/components/responses/verify_GenericErrorResponse'
summary: Retrieve Verify profile message templates
tags:
- Verify
x-latency-category: responsive
post:
description: Create a new Verify profile message template.
operationId: CreateMessageTemplate
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMessageTemplateRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/MessageTemplateResponseDataWrapper'
description: Expected message template response to a valid request.
'400':
$ref: '#/components/responses/verify_GenericErrorResponse'
summary: Create message template
tags:
- Verify
x-latency-category: responsive
/verify_profiles/templates/{template_id}:
patch:
description: Update an existing Verify profile message template.
operationId: UpdateMessageTemplate
parameters:
- description: The identifier of the message template to update.
in: path
name: template_id
required: true
schema:
example: 12ade33a-21c0-473b-b055-b3c836e1c292
format: uuid
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateMessageTemplateRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/MessageTemplateResponseDataWrapper'
description: Expected message template response to a valid request.
'400':
$ref: '#/components/responses/verify_GenericErrorResponse'
summary: Update message template
tags:
- Verify
x-latency-category: responsive
/verify_profiles/{verify_profile_id}:
delete:
operationId: DeleteProfile
parameters:
- description: The identifier of the Verify profile to delete.
in: path
name: verify_profile_id
required: true
schema:
example: 12ade33a-21c0-473b-b055-b3c836e1c292
format: uuid
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyProfileResponseDataWrapper'
description: Expected Verify profile response to a valid request.
'400':
$ref: '#/components/responses/verify_GenericErrorResponse'
summary: Delete Verify profile
tags:
- Verify
x-latency-category: responsive
get:
description: Gets a single Verify profile.
operationId: GetVerifyProfile
parameters:
- description: The identifier of the Verify profile to retrieve.
in: path
name: verify_profile_id
required: true
schema:
example: 12ade33a-21c0-473b-b055-b3c836e1c292
format: uuid
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyProfileResponseDataWrapper'
description: Expected Verify profile response to a valid request.
'400':
$ref: '#/components/responses/verify_GenericErrorResponse'
summary: Retrieve Verify profile
tags:
- Verify
x-latency-category: responsive
patch:
operationId: UpdateVerifyProfile
parameters:
- description: The identifier of the Verify profile to update.
in: path
name: verify_profile_id
required: true
schema:
example: 12ade33a-21c0-473b-b055-b3c836e1c292
format: uuid
type: string
requestBody:
content:
application/json:
schema:
properties:
call:
$ref: '#/components/schemas/UpdateVerifyProfileCallRequest'
additionalProperties: true
type: object
daily_spend_limit:
description: The maximum daily spend allowed on this verify profile, in USD.
example: 100.0
minimum: 0
type: number
daily_spend_limit_enabled:
description: Whether the daily spend limit is enforced for this verify profile.
example: true
type: boolean
language:
example: en-US
type: string
name:
example: Test Profile
type: string
sms:
$ref: '#/components/schemas/UpdateVerifyProfileSMSRequest'
additionalProperties: true
type: object
webhook_failover_url:
example: http://example.com/webhook/failover
type: string
webhook_url:
example: http://example.com/webhook
type: string
whatsapp:
$ref: '#/components/schemas/UpdateVerifyProfileSettingsWhatsAppRequest'
additionalProperties: true
type: object
title: Update Verify Profile Request
type: object
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyProfileResponseDataWrapper'
description: Expected Verify profile response to a valid request.
'400':
$ref: '#/components/responses/verify_GenericErrorResponse'
summary: Update Verify profile
tags:
- Verify
x-latency-category: responsive
components:
schemas:
ListVerificationsResponse:
properties:
data:
items:
$ref: '#/components/schemas/Verification'
type: array
meta:
$ref: '#/components/schemas/verify_Meta'
required:
- data
- meta
title: ListVerificationsResponse
type: object
VerifyProfileFlashcallResponse:
properties:
app_name:
description: The name that identifies the application requesting 2fa in the verification message.
example: Example Secure App
pattern: ^[A-Za-z0-9 -]{1,30}$
type: string
default_verification_timeout_secs:
default: 300
description: For every request that is initiated via this Verify profile, this sets the number of seconds before a verification request code expires. Once the verification request expires, the user cannot use the code to verify their identity.
example: 300
type: integer
title: VerifyProfileFlashcallResponse
type: object
CreateVerifyProfileSettingsWhatsAppRequest:
properties:
default_verification_timeout_secs:
default: 300
description: For every request that is initiated via this Verify profile, this sets the number of seconds before a verification request code expires. Once the verification request expires, the user cannot use the code to verify their identity.
example: 300
type: integer
sender_phone_number:
default: null
description: Phone number registered on the customer WABA to send OTPs from
example: '+13035551234'
type:
- string
- 'null'
template_id:
default: null
description: Customer pre-approved authentication template name registered on Meta
example: authentication_template_name
type:
- string
- 'null'
waba_id:
default: null
description: Customer Meta WABA ID for Bring-Your-Own-WABA sending
example: '1234567890'
type:
- string
- 'null'
whitelisted_destinations:
description: Enabled country destinations to send verification codes. The elements in the list must be valid ISO 3166-1 alpha-2 country codes. If set to `["*"]`, all destinations will be allowed. **Conditionally required:** this field must be provided when your organization is configured to require explicit whitelisted destinations; otherwise it is optional.
example:
- US
- CA
items:
description: ISO 3166-1 alpha-2 country code
pattern: ^[A-Z]{2}$
type: string
type: array
title: CreateVerifyProfileSettingsWhatsAppRequest
type: object
RetrieveVerificationResponse:
properties:
data:
$ref: '#/components/schemas/Verification'
required:
- data
title: RetrieveVerificationResponse
type: object
VerifyProfileWhatsAppResponse:
properties:
app_name:
description: The name that identifies the application requesting 2fa in the verification message.
example: Example Secure App
pattern: ^[A-Za-z0-9 -]{1,30}$
type: string
code_length:
default: 5
description: The length of the verify code to generate.
example: 6
type: integer
default_verification_timeout_secs:
default: 300
description: For every request that is initiated via this Verify profile, this sets the number of seconds before a verification request code expires. Once the verification request expires, the user cannot use the code to verify their identity.
example: 300
type: integer
messaging_template_id:
description: The message template identifier selected from /verify_profiles/templates
example: 0abb5b4f-459f-445a-bfcd-488998b7572d
format: uuid
type: string
sender_phone_number:
default: null
description: Phone number registered on the customer WABA to send OTPs from
example: '+13035551234'
type:
- string
- 'null'
template_id:
default: null
description: Customer pre-approved authentication template name registered on Meta
example: authentication_template_name
type:
- string
- 'null'
waba_id:
default: null
description: Customer Meta WABA ID for Bring-Your-Own-WABA sending
example: '1234567890'
type:
- string
- 'null'
whitelisted_destinations:
description: Enabled country destinations to send verification codes. The elements in the list must be valid ISO 3166-1 alpha-2 country codes. If set to `["*"]`, all destinations will be allowed. **Conditionally required:** this field must be provided when your organization is configured to require explicit whitelisted destinations; otherwise it is optional.
example:
- US
- CA
items:
description: ISO 3166-1 alpha-2 country code
pattern: ^[A-Z]{2}$
type: string
type: array
title: VerifyProfileWhatsAppResponse
type: object
UpdateVerifyProfileSettingsWhatsAppRequest:
properties:
default_verification_timeout_secs:
default: 300
description: For every request that is initiated via this Verify profile, this sets the number of seconds before a verification request code expires. Once the verification request expires, the user cannot use the code to verify their identity.
example: 300
type: integer
sender_phone_number:
default: null
description: Phone number registered on the customer WABA to send OTPs from
example: '+13035551234'
type:
- string
- 'null'
template_id:
default: null
description: Customer pre-approved authentication template name registered on Meta
example: authentication_template_name
type:
- string
- 'null'
waba_id:
default: null
description: Customer Meta WABA ID for Bring-Your-Own-WABA sending
example: '1234567890'
type:
- string
- 'null'
whitelisted_destinations:
description: Enabled country destinations to send verification codes. The elements in the list must be valid ISO 3166-1 alpha-2 country codes. If set to `["*"]`, all destinations will be allowed. **Conditionally required:** this field must be provided when your organization is configured to require explicit whitelisted destinations; otherwise it is optional.
example:
- US
- CA
items:
description: ISO 3166-1 alpha-2 country code
pattern: ^[A-Z]{2}$
type: string
type: array
title: UpdateVerifyProfileSettingsWhatsAppRequest
type: object
VerificationStatus:
description: The possible statuses of the verification request.
enum:
- pending
- accepted
- invalid
- expired
- error
example: accepted
title: VerificationStatus
type: string
CreateVerifyProfileSMSRequest:
properties:
alpha_sender:
default: Telnyx
description: The alphanumeric sender ID to use when sending to destinations that require an alphanumeric sender ID.
pattern: ^[A-Za-z0-9 ]{1,11}$
type:
- string
- 'null'
app_name:
description: The name that identifies the application requesting 2fa in the verification message.
example: Example Secure App
pattern: ^[A-Za-z0-9 -]{1,30}$
type: string
code_length:
default: 5
description: The length of the verify code to generate.
example: 6
type: integer
default_verification_timeout_secs:
default: 300
description: For every request that is initiated via this Verify profile, this sets the number of seconds before a verification request code expires. Once the verification request expires, the user cannot use the code to verify their identity.
example: 300
type: integer
messaging_template_id:
description: The message template identifier selected from /verify_profiles/templates
example: 0abb5b4f-459f-445a-bfcd-488998b7572d
format: uuid
type: string
whitelisted_destinations:
description: Enabled country destinations to send verification codes. The elements in the list must be valid ISO 3166-1 alpha-2 country codes. If set to `["*"]`, all destinations will be allowed. **Conditionally required:** this field must be provided when your organization is configured to require explicit whitelisted destinations; otherwise it is optional.
example:
- US
- CA
items:
description: ISO 3166-1 alpha-2 country code
pattern: ^[A-Z]{2}$
type: string
type: array
title: CreateVerifyProfileSMSRequest
type: object
VerifyVerificationCodeRequestById:
properties:
code:
description: This is the code the user submits for verification.
example: '17686'
type: string
status:
description: Identifies if the verification code has been accepted or rejected. Only permitted if custom_code was used for the verification.
enum:
- accepted
- rejected
example: accepted
type: string
title: VerifyVerificationCodeRequestById
type: object
CreateVerificationResponse:
properties:
data:
$ref: '#/components/schemas/Verification'
required:
- data
title: CreateVerifyVerificationResponse
type: object
CreateMessageTemplateRequest:
description: The request body when creating a message template.
properties:
text:
description: The text content of the message template.
example: 'Your {{app_name}} verification code is: {{code}}.'
type: string
required:
- text
title: CreateMessageTemplateRequest
type: object
CreateVerificationRequestSMS:
description: The request body when creating a verification.
properties:
custom_code:
default: null
description: Send a self-generated numeric code to the end-user
example: '43612'
type:
- string
- 'null'
phone_number:
description: +E164 formatted phone number.
example: '+13035551234'
type: string
timeout_secs:
description: The number of seconds the verification code is valid for.
example: 300
type: integer
verify_profile_id:
description: The identifier of the associated Verify profile.
example: 12ade33a-21c0-473b-b055-b3c836e1c292
format: uuid
type: string
required:
- phone_number
- verify_profile_id
title: CreateVerificationRequestSMS
type: object
verify_Meta:
properties:
page_number:
example: 2
type: integer
page_size:
example: 25
type: integer
total_pages:
example: 3
type: integer
total_results:
example: 55
type: integer
required:
- total_pages
- total_results
- page_size
- page_number
type: object
VerifyProfileSMSResponse:
properties:
alpha_sender:
default: Telnyx
description: The alphanumeric sender ID to use when sending to destinations that require an alphanumeric sender ID.
pattern: ^[A-Za-z0-9 ]{1,11}$
type:
- string
- 'null'
app_name:
description: The name that identifies the application requesting 2fa in the verification message.
example: Example Secure App
pattern: ^[A-Za-z0-9 -]{1,30}$
type: string
code_length:
default: 5
description: The length of the verify code to generate.
example: 6
type: integer
default_verification_timeout_secs:
default: 300
description: For every request that is initiated via this Verify profile, this sets the number of seconds before a verification request code expires. Once the verification request expires, the user cannot use the code to verify their identity.
example: 300
type: integer
messaging_template_id:
description: The message template identifier selected from /verify_profiles/templates
example: 0abb5b4f-459f-445a-bfcd-488998b7572d
format: uuid
type: string
whitelisted_destinations:
description: Enabled country destinations to send verification codes. The elements in the list must be valid ISO 3166-1 alpha-2 country codes. If set to `["*"]`, all destinations will be allowed. **Conditionally required:** this field must be provided when your organization is configured to require explicit whitelisted destinations; otherwise it is optional.
example:
- US
- CA
items:
description: ISO 3166-1 alpha-2 country code
pattern: ^[A-Z]{2}$
type: string
type: array
title: VerifyProfileSMSResponse
type: object
UpdateMessageTemplateRequest:
description: The request body when updating a message template.
properties:
text:
description: The text content of the message template.
example: 'Your {{app_name}} verification code is: {{code}}.'
type: string
required:
- text
title: UpdateMessageTemplateRequest
type: object
CreateVerifyProfileSettingsRequest:
properties:
app_name:
description: The name that identifies the application requesting 2fa in the verification message.
example: Example Secure App
pattern: ^[A-Za-z0-9 -]{1,30}$
type: string
default_verification_timeout_secs:
default: 300
description: For every request that is initiated via this Verify profile, this sets the number of seconds before a verification request code expires. Once the verification request expires, the user cannot use the code to verify their identity.
example: 300
type: integer
whitelisted_destinations:
des
# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/telnyx/refs/heads/main/openapi/telnyx-verify-api-openapi.yml