Twilio Verify API is a powerful tool that enables developers to integrate phone verification capabilities into their applications with ease. By leveraging the API, developers can ensure that users are who they say they are by sending verification codes via SMS or voice calls. This helps to reduce fraud and increase security on platforms where user verification is crucial.
components:
schemas:
verify.v2.service.access_token:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^YK[0-9a-fA-F]{32}$
nullable: true
description: A 34 character string that uniquely identifies this Access Token.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: The unique SID identifier of the Account.
service_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^VA[0-9a-fA-F]{32}$
nullable: true
description: The unique SID identifier of the Verify Service.
entity_identity:
type: string
nullable: true
description: The unique external identifier for the Entity of the Service.
factor_type:
type: string
$ref: '#/components/schemas/access_token_enum_factor_types'
nullable: true
description: The Type of the Factor. Currently only `push` is supported.
factor_friendly_name:
type: string
nullable: true
description: >-
A human readable description of this factor, up to 64 characters.
For a push factor, this can be the device's name.
x-twilio:
pii:
handling: standard
deleteSla: 30
token:
type: string
nullable: true
description: >-
The access token generated for enrollment, this is an encrypted json
web token.
url:
type: string
format: uri
nullable: true
description: The URL of this resource.
ttl:
type: integer
nullable: true
description: 'How long, in seconds, the access token is valid. Max: 5 minutes'
date_created:
type: string
format: date-time
nullable: true
description: >-
The date that this access token was created, given in [ISO
8601](https://en.wikipedia.org/wiki/ISO_8601) format.
access_token_enum_factor_types:
type: string
enum:
- push
verify.v2.service.rate_limit.bucket:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^BL[0-9a-fA-F]{32}$
nullable: true
description: A 34 character string that uniquely identifies this Bucket.
rate_limit_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^RK[0-9a-fA-F]{32}$
nullable: true
description: >-
The Twilio-provided string that uniquely identifies the Rate Limit
resource.
service_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^VA[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Service](https://www.twilio.com/docs/verify/api/service) the
resource is associated with.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Account](https://www.twilio.com/docs/iam/api/account) that created
the Rate Limit resource.
max:
type: integer
nullable: true
description: Maximum number of requests permitted in during the interval.
interval:
type: integer
nullable: true
description: Number of seconds that the rate limit will be enforced over.
date_created:
type: string
format: date-time
nullable: true
description: >-
The date and time in GMT when the resource was created specified in
[RFC 2822](https://www.ietf.org/rfc/rfc2822.txt) format.
date_updated:
type: string
format: date-time
nullable: true
description: >-
The date and time in GMT when the resource was last updated
specified in [RFC 2822](https://www.ietf.org/rfc/rfc2822.txt)
format.
url:
type: string
format: uri
nullable: true
description: The URL of this resource.
verify.v2.service.entity.challenge:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^YC[0-9a-fA-F]{32}$
nullable: true
description: A 34 character string that uniquely identifies this Challenge.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: The unique SID identifier of the Account.
service_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^VA[0-9a-fA-F]{32}$
nullable: true
description: The unique SID identifier of the Service.
entity_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^YE[0-9a-fA-F]{32}$
nullable: true
description: The unique SID identifier of the Entity.
identity:
type: string
nullable: true
description: >-
Customer unique identity for the Entity owner of the Challenge. This
identifier should be immutable, not PII, length between 8 and 64
characters, and generated by your external system, such as your
user's UUID, GUID, or SID. It can only contain dash (-) separated
alphanumeric characters.
x-twilio:
pii:
handling: standard
deleteSla: 30
factor_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^YF[0-9a-fA-F]{32}$
nullable: true
description: The unique SID identifier of the Factor.
date_created:
type: string
format: date-time
nullable: true
description: >-
The date that this Challenge was created, given in [ISO
8601](https://en.wikipedia.org/wiki/ISO_8601) format.
date_updated:
type: string
format: date-time
nullable: true
description: >-
The date that this Challenge was updated, given in [ISO
8601](https://en.wikipedia.org/wiki/ISO_8601) format.
date_responded:
type: string
format: date-time
nullable: true
description: >-
The date that this Challenge was responded, given in [ISO
8601](https://en.wikipedia.org/wiki/ISO_8601) format.
expiration_date:
type: string
format: date-time
nullable: true
description: >-
The date-time when this Challenge expires, given in [ISO
8601](https://en.wikipedia.org/wiki/ISO_8601) format. The default
value is five (5) minutes after Challenge creation. The max value is
sixty (60) minutes after creation.
status:
type: string
$ref: '#/components/schemas/challenge_enum_challenge_statuses'
nullable: true
description: >-
The Status of this Challenge. One of `pending`, `expired`,
`approved` or `denied`.
responded_reason:
type: string
$ref: '#/components/schemas/challenge_enum_challenge_reasons'
nullable: true
description: >-
Reason for the Challenge to be in certain `status`. One of `none`,
`not_needed` or `not_requested`.
details:
nullable: true
description: >-
Details provided to give context about the Challenge. Intended to be
shown to the end user.
x-twilio:
pii:
handling: standard
deleteSla: 30
hidden_details:
nullable: true
description: >-
Details provided to give context about the Challenge. Intended to be
hidden from the end user. It must be a stringified JSON with only
strings values eg. `{"ip": "172.168.1.234"}`
x-twilio:
pii:
handling: standard
deleteSla: 30
metadata:
nullable: true
description: >-
Custom metadata associated with the challenge. This is added by the
Device/SDK directly to allow for the inclusion of device
information. It must be a stringified JSON with only strings values
eg. `{"os": "Android"}`. Can be up to 1024 characters in length.
x-twilio:
pii:
handling: standard
deleteSla: 30
factor_type:
type: string
$ref: '#/components/schemas/challenge_enum_factor_types'
nullable: true
description: >-
The Factor Type of this Challenge. Currently `push` and `totp` are
supported.
url:
type: string
format: uri
nullable: true
description: The URL of this resource.
links:
type: object
format: uri-map
nullable: true
description: >-
Contains a dictionary of URL links to nested resources of this
Challenge.
challenge_enum_challenge_statuses:
type: string
enum:
- pending
- expired
- approved
- denied
challenge_enum_challenge_reasons:
type: string
enum:
- none
- not_needed
- not_requested
challenge_enum_factor_types:
type: string
enum:
- push
- totp
challenge_enum_list_orders:
type: string
enum:
- asc
- desc
verify.v2.service.entity:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^YE[0-9a-fA-F]{32}$
nullable: true
description: A 34 character string that uniquely identifies this Entity.
identity:
type: string
nullable: true
description: >-
The unique external identifier for the Entity of the Service. This
identifier should be immutable, not PII, length between 8 and 64
characters, and generated by your external system, such as your
user's UUID, GUID, or SID. It can only contain dash (-) separated
alphanumeric characters.
x-twilio:
pii:
handling: standard
deleteSla: 30
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: The unique SID identifier of the Account.
service_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^VA[0-9a-fA-F]{32}$
nullable: true
description: The unique SID identifier of the Service.
date_created:
type: string
format: date-time
nullable: true
description: >-
The date that this Entity was created, given in [ISO
8601](https://en.wikipedia.org/wiki/ISO_8601) format.
date_updated:
type: string
format: date-time
nullable: true
description: >-
The date that this Entity was updated, given in [ISO
8601](https://en.wikipedia.org/wiki/ISO_8601) format.
url:
type: string
format: uri
nullable: true
description: The URL of this resource.
links:
type: object
format: uri-map
nullable: true
description: >-
Contains a dictionary of URL links to nested resources of this
Entity.
verify.v2.service.entity.factor:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^YF[0-9a-fA-F]{32}$
nullable: true
description: A 34 character string that uniquely identifies this Factor.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: The unique SID identifier of the Account.
service_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^VA[0-9a-fA-F]{32}$
nullable: true
description: The unique SID identifier of the Service.
entity_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^YE[0-9a-fA-F]{32}$
nullable: true
description: The unique SID identifier of the Entity.
identity:
type: string
nullable: true
description: >-
Customer unique identity for the Entity owner of the Factor. This
identifier should be immutable, not PII, length between 8 and 64
characters, and generated by your external system, such as your
user's UUID, GUID, or SID. It can only contain dash (-) separated
alphanumeric characters.
x-twilio:
pii:
handling: standard
deleteSla: 30
date_created:
type: string
format: date-time
nullable: true
description: >-
The date that this Factor was created, given in [ISO
8601](https://en.wikipedia.org/wiki/ISO_8601) format.
date_updated:
type: string
format: date-time
nullable: true
description: >-
The date that this Factor was updated, given in [ISO
8601](https://en.wikipedia.org/wiki/ISO_8601) format.
friendly_name:
type: string
nullable: true
description: >-
A human readable description of this resource, up to 64 characters.
For a push factor, this can be the device's name.
status:
type: string
$ref: '#/components/schemas/factor_enum_factor_statuses'
nullable: true
description: The Status of this Factor. One of `unverified` or `verified`.
factor_type:
type: string
$ref: '#/components/schemas/factor_enum_factor_types'
nullable: true
description: The Type of this Factor. Currently `push` and `totp` are supported.
config:
nullable: true
description: An object that contains configurations specific to a `factor_type`.
metadata:
nullable: true
description: >-
Custom metadata associated with the factor. This is added by the
Device/SDK directly to allow for the inclusion of device
information. It must be a stringified JSON with only strings values
eg. `{"os": "Android"}`. Can be up to 1024 characters in length.
x-twilio:
pii:
handling: standard
deleteSla: 30
url:
type: string
format: uri
nullable: true
description: The URL of this resource.
factor_enum_factor_statuses:
type: string
enum:
- unverified
- verified
factor_enum_factor_types:
type: string
enum:
- push
- totp
factor_enum_notification_platforms:
type: string
enum:
- apn
- fcm
- none
factor_enum_totp_algorithms:
type: string
enum:
- sha1
- sha256
- sha512
verify.v2.form:
type: object
properties:
form_type:
type: string
$ref: '#/components/schemas/form_enum_form_types'
nullable: true
description: The Type of this Form. Currently only `form-push` is supported.
forms:
nullable: true
description: >-
Object that contains the available forms for this type. This
available forms are given in the standard [JSON
Schema](https://json-schema.org/) format
form_meta:
nullable: true
description: >-
Additional information for the available forms for this type. E.g.
The separator string used for `binding` in a Factor push.
url:
type: string
format: uri
nullable: true
description: The URL to access the forms for this type.
form_enum_form_types:
type: string
enum:
- form-push
verify.v2.service.messaging_configuration:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Account](https://www.twilio.com/docs/iam/api/account) that created
the Service resource.
service_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^VA[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Service](https://www.twilio.com/docs/verify/api/service) that the
resource is associated with.
country:
type: string
nullable: true
description: >-
The [ISO-3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
country code of the country this configuration will be applied to.
If this is a global configuration, Country will take the value
`all`.
messaging_service_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^MG[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the [Messaging
Service](https://www.twilio.com/docs/messaging/api/service-resource)
to be used to send SMS to the country of this configuration.
date_created:
type: string
format: date-time
nullable: true
description: >-
The date and time in GMT when the resource was created specified in
[RFC 2822](https://www.ietf.org/rfc/rfc2822.txt) format.
date_updated:
type: string
format: date-time
nullable: true
description: >-
The date and time in GMT when the resource was last updated
specified in [RFC 2822](https://www.ietf.org/rfc/rfc2822.txt)
format.
url:
type: string
format: uri
nullable: true
description: The URL of this resource.
verify.v2.service.entity.new_factor:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^YF[0-9a-fA-F]{32}$
nullable: true
description: A 34 character string that uniquely identifies this Factor.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: The unique SID identifier of the Account.
service_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^VA[0-9a-fA-F]{32}$
nullable: true
description: The unique SID identifier of the Service.
entity_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^YE[0-9a-fA-F]{32}$
nullable: true
description: The unique SID identifier of the Entity.
identity:
type: string
nullable: true
description: >-
Customer unique identity for the Entity owner of the Factor. This
identifier should be immutable, not PII, length between 8 and 64
characters, and generated by your external system, such as your
user's UUID, GUID, or SID. It can only contain dash (-) separated
alphanumeric characters.
x-twilio:
pii:
handling: standard
deleteSla: 30
binding:
nullable: true
description: >-
Contains the `factor_type` specific secret and metadata.
For push, this is `binding.public_key` and `binding.alg`.
For totp, this is `binding.secret` and `binding.uri`. The
`binding.uri` property is generated following the [google
authenticator key URI
format](https://github.com/google/google-authenticator/wiki/Key-Uri-Format),
and `Factor.friendly_name` is used for the “accountname” value and
`Service.friendly_name` or `Service.totp.issuer` is used for the
`issuer` value.
The Binding property is ONLY returned upon Factor creation.
date_created:
type: string
format: date-time
nullable: true
description: >-
The date that this Factor was created, given in [ISO
8601](https://en.wikipedia.org/wiki/ISO_8601) format.
date_updated:
type: string
format: date-time
nullable: true
description: >-
The date that this Factor was updated, given in [ISO
8601](https://en.wikipedia.org/wiki/ISO_8601) format.
friendly_name:
type: string
nullable: true
description: >-
The friendly name of this Factor. This can be any string up to 64
characters, meant for humans to distinguish between Factors.
For `factor_type` `push`, this could be a device name.
For `factor_type` `totp`, this value is used as the “account name”
in constructing the `binding.uri` property.
At the same time, we recommend avoiding providing PII.
status:
type: string
$ref: '#/components/schemas/new_factor_enum_factor_statuses'
nullable: true
description: The Status of this Factor. One of `unverified` or `verified`.
factor_type:
type: string
$ref: '#/components/schemas/new_factor_enum_factor_types'
nullable: true
description: The Type of this Factor. Currently `push` and `totp` are supported.
config:
nullable: true
description: An object that contains configurations specific to a `factor_type`.
metadata:
nullable: true
description: >-
Custom metadata associated with the factor. This is added by the
Device/SDK directly to allow for the inclusion of device
information. It must be a stringified JSON with only strings values
eg. `{"os": "Android"}`. Can be up to 1024 characters in length.
x-twilio:
pii:
handling: standard
deleteSla: 30
url:
type: string
format: uri
nullable: true
description: The URL of this resource.
new_factor_enum_factor_statuses:
type: string
enum:
- unverified
- verified
new_factor_enum_factor_types:
type: string
enum:
- push
- totp
new_factor_enum_notification_platforms:
type: string
enum:
- apn
- fcm
- none
new_factor_enum_totp_algorithms:
type: string
enum:
- sha1
- sha256
- sha512
verify.v2.service.entity.challenge.notification:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^NT[0-9a-fA-F]{32}$
nullable: true
description: A 34 character string that uniquely identifies this Notification.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: The unique SID identifier of the Account.
service_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^VA[0-9a-fA-F]{32}$
nullable: true
description: The unique SID identifier of the Service.
entity_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^YE[0-9a-fA-F]{32}$
nullable: true
description: The unique SID identifier of the Entity.
identity:
type: string
nullable: true
description: >-
Customer unique identity for the Entity owner of the Challenge. This
identifier should be immutable, not PII, length between 8 and 64
characters, and generated by your external system, such as your
user's UUID, GUID, or SID. It can only contain dash (-) separated
alphanumeric characters.
x-twilio:
pii:
handling: standard
deleteSla: 30
challenge_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^YC[0-9a-fA-F]{32}$
nullable: true
description: The unique SID identifier of the Challenge.
priority:
type: string
nullable: true
description: >-
The priority of the notification. For `push` Challenges it's always
`high` which sends the notification immediately, and can wake up a
sleeping device.
ttl:
type: integer
nullable: true
description: 'How long, in seconds, the notification is valid. Max: 5 minutes'
date_created:
type: string
format: date-time
nullable: true
description: >-
The date that this Notification was created, given in [ISO
8601](https://en.wikipedia.org/wiki/ISO_8601) format.
verify.v2.service.rate_limit:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^RK[0-9a-fA-F]{32}$
nullable: true
description: A 34 character string that uniquely identifies this Rate Limit.
service_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^VA[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Service](https://www.twilio.com/docs/verify/api/service) the
resource is associated with.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Account](https://www.twilio.com/docs/iam/api/account) that created
the Rate Limit resource.
unique_name:
type: string
nullable: true
description: >-
Provides a unique and addressable name to be assigned to this Rate
Limit, assigned by the developer, to be optionally used in addition
to SID. **This value should not contain PII.**
description:
type: string
nullable: true
description: Description of this Rate Limit
date_created:
type: string
format: date-time
nullable: true
description: >-
The date and time in GMT when the resource was created specified in
[RFC 2822](https://www.ietf.org/rfc/rfc2822.txt) format.
date_updated:
type: string
format: date-time
nullable: true
description: >-
The date and time in GMT when the resource was last updated
specified in [RFC 2822](https://www.ietf.org/rfc/rfc2822.txt)
format.
url:
type: string
format: uri
nullable: true
description: The URL of this resource.
links:
type: object
format: uri-map
nullable: true
description: The URLs of related resources.
verify.v2.safelist:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^GN[0-9a-fA-F]{32}$
nullable: true
description: The unique string that we created to identify the SafeList resource.
phone_number:
type: string
nullable: true
description: The phone number in SafeList.
x-twilio:
pii:
handling: standard
deleteSla: 0
url:
type: string
format: uri
nullable: true
description: The absolute URL of the SafeList resource.
verify.v2.service:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^VA[0-9a-fA-F]{32}$
nullable: true
description: The unique string that we created to identify the Service resource.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Account](https://www.twilio.com/docs/iam/api/account) that created
the Service resource.
friendly_name:
type: string
nullable: true
description: >-
The string that you assigned to describe the verification service.
It can be up to 32 characters long. **This value should not contain
PII.**
code_length:
type: integer
nullable: true
description: The length of the verification code to generate.
lookup_enabled:
type: boolean
nullable: true
description: >-
Whether to perform a lookup with each verification started and
return info about the phone number.
psd2_enabled:
type: boolean
nullable: true
description: >-
Whether to pass PSD2 transaction parameters when starting a
verification.
skip_sms_to_landlines:
type: boolean
nullable: true
description: >-
Whether to skip sending SMS verifications to landlines. Requires
`lookup_enabled`.
dtmf_input_required:
type: boolean
nullable: true
description: >-
Whether to ask the user to press a number before delivering the
verify code in a phone call.
tts_name:
type: string
nullable: true
description: >-
The name of an alternative text-to-speech service to use in phone
calls. Applies only to TTS languages.
do_not_share_warning_enabled:
type: boolean
nullable: true
description: >-
Whether to add a security warning at the end of an SMS verification
body. Disabled by default and applies only to SMS. Example SMS body:
`Your AppName verification code is: 1234. Don’t share this code with
anyone; our employees will never ask for the code`
custom_code_enabled:
type: boolean
nullable: true
description: >-
Whether to allow sending verifications with a custom code instead of
a randomly generated one. Not available for all customers.
push:
nullable: true
description: >-
Configurations for the Push factors (channel) created under this
Service.
totp:
nullable: true
description: >-
Configurations for the TOTP factors (channel) created under this
Service.
default_template_sid:
type: string
minLen
# --- truncated at 32 KB (173 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/twilio/refs/heads/main/openapi/verify-openapi-original.yml