Telnyx DevelopersAPI v2
Sign inTelnyx Developers
Open Menu
DocsAPI ReferenceJoin Slack Community
Create an AccountSign in
Questions on setup? Talk to our experts
Open SidemenuAPI Reference
API Reference
Close Sidemenu

Verify

List all Verify profileslistVerifyProfiles

get https://api.telnyx.com/v2/verify_profiles

Gets a paginated list of Verify profiles.

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/verify_profiles?filter[name]=test&page[size]=25"
Parameters
In query
filter[name]
string
optional

Optional filter for profile names.

page[size]
integer
optional
Default: 25
page[number]
integer
optional
Default: 1
Responses
200

Expected Verify profile response to a valid request.

400

Unexpected error

Success Response
{
  "data": [
    {
      "created_at": "2020-09-14T17:03:32.965812",
      "default_timeout_secs": 300,
      "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
      "messaging_enabled": true,
      "messaging_template": "Hello, this is the Acme Inc verification code you requested: {code}.",
      "name": "Test Profile",
      "rcs_enabled": true,
      "record_type": "verify_profile",
      "updated_at": "2020-09-14T17:03:32.965812",
      "vsms_enabled": true
    }
  ],
  "meta": {
    "page_number": 2,
    "page_size": 25,
    "total_pages": 3,
    "total_results": 55
  }
}

Create a Verify profilecreateVerifyProfile

post https://api.telnyx.com/v2/verify_profiles

Creates a new Verify profile to associate verifications with.

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"name":"Test Profile","default_timeout_secs":300,"messaging_enabled":true}' \
  https://api.telnyx.com/v2/verify_profiles
Parameters
In body (application/json)
name
string
required

The human readable label for the Verify profile.

Example: "Test Profile"
default_timeout_secs
integer
optional

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
messaging_enabled
boolean
optional

Enables SMS text messaging for the Verify profile.

Default: true
Example: true
messaging_template
string
optional

Optionally sets a messaging text template when sending the verification code. Uses `{code}` to template in the actual verification code.

Default: null
Example: "Hello, this is the Acme Inc verification code you requested: {code}."
rcs_enabled
boolean
optional

Enables RCS messaging for the Verify profile.

Default: false
Example: true
Responses
200

Expected Verify profile response to a valid request.

400

Unexpected error

Success Response
{
  "data": {
    "created_at": "2020-09-14T17:03:32.965812",
    "default_timeout_secs": 300,
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    "messaging_enabled": true,
    "messaging_template": "Hello, this is the Acme Inc verification code you requested: {code}.",
    "name": "Test Profile",
    "rcs_enabled": true,
    "record_type": "verify_profile",
    "updated_at": "2020-09-14T17:03:32.965812",
    "vsms_enabled": true
  }
}

Retrieve a Verify profileretrieveVerifyProfile

get https://api.telnyx.com/v2/verify_profiles/{verify_profile_id}

Gets a single Verify profile.

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/verify_profiles/12ade33a-21c0-473b-b055-b3c836e1c292"
Parameters
In path
verify_profile_id
string (uuid)
required

The identifier of the Verify profile to retrieve.

Example: "12ade33a-21c0-473b-b055-b3c836e1c292"
Responses
200

Expected Verify profile response to a valid request.

400

Unexpected error

Success Response
{
  "data": {
    "created_at": "2020-09-14T17:03:32.965812",
    "default_timeout_secs": 300,
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    "messaging_enabled": true,
    "messaging_template": "Hello, this is the Acme Inc verification code you requested: {code}.",
    "name": "Test Profile",
    "rcs_enabled": true,
    "record_type": "verify_profile",
    "updated_at": "2020-09-14T17:03:32.965812",
    "vsms_enabled": true
  }
}

Update a Verify profileupdateVerifyProfile

patch https://api.telnyx.com/v2/verify_profiles/{verify_profile_id}

Update a Verify profile

curl -X PATCH \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"name":"Test Profile","default_timeout_secs":250,"messaging_enabled":false}' \
  https://api.telnyx.com/v2/verify_profiles/12ade33a-21c0-473b-b055-b3c836e1c292
Parameters
In path
verify_profile_id
string (uuid)
required

The identifier of the Verify profile to update.

Example: "12ade33a-21c0-473b-b055-b3c836e1c292"
In body (application/json)
name
string
required

The human readable label for the Verify profile.

Example: "Test Profile"
default_timeout_secs
integer
optional

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
messaging_enabled
boolean
optional

Enables SMS text messaging for the Verify profile.

Default: true
Example: true
messaging_template
string
optional

Optionally sets a messaging text template when sending the verification code. Uses `{code}` to template in the actual verification code.

Default: null
Example: "Hello, this is the Acme Inc verification code you requested: {code}."
rcs_enabled
boolean
optional

Enables RCS messaging for the Verify profile.

Default: false
Example: true
Responses
200

Expected Verify profile response to a valid request.

400

Unexpected error

Success Response
{
  "data": {
    "created_at": "2020-09-14T17:03:32.965812",
    "default_timeout_secs": 300,
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    "messaging_enabled": true,
    "messaging_template": "Hello, this is the Acme Inc verification code you requested: {code}.",
    "name": "Test Profile",
    "rcs_enabled": true,
    "record_type": "verify_profile",
    "updated_at": "2020-09-14T17:03:32.965812",
    "vsms_enabled": true
  }
}

Delete a Verify profiledeleteVerifyProfile

delete https://api.telnyx.com/v2/verify_profiles/{verify_profile_id}

Delete a Verify profile

curl -X DELETE \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  "https://api.telnyx.com/v2/verify_profiles/12ade33a-21c0-473b-b055-b3c836e1c292"
Parameters
In path
verify_profile_id
string (uuid)
required

The identifier of the Verify profile to delete.

Example: "12ade33a-21c0-473b-b055-b3c836e1c292"
Responses
200

Expected Verify profile response to a valid request.

400

Unexpected error

Success Response
{
  "data": {
    "created_at": "2020-09-14T17:03:32.965812",
    "default_timeout_secs": 300,
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    "messaging_enabled": true,
    "messaging_template": "Hello, this is the Acme Inc verification code you requested: {code}.",
    "name": "Test Profile",
    "rcs_enabled": true,
    "record_type": "verify_profile",
    "updated_at": "2020-09-14T17:03:32.965812",
    "vsms_enabled": true
  }
}

Trigger a verificationcreateVerification

post https://api.telnyx.com/v2/verifications

Trigger a verification

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"phone_number":"+13035551234","verify_profile_id":"12ade33a-21c0-473b-b055-b3c836e1c292","type":"sms"}' \
  https://api.telnyx.com/v2/verifications
Parameters
In body (application/json)
phone_number
string
required

+E164 formatted phone number.

Example: "+13035551234"
type
string
required

The verification request type.

Example: "sms"
Options: [ "sms" ]
verify_profile_id
string (uuid)
required

The identifier of the associated Verify profile.

Example: "12ade33a-21c0-473b-b055-b3c836e1c292"
timeout_secs
integer
optional

This is the number of seconds before the code of the request is expired. Once this request has expired, the code will no longer verify the user. Note: this will override the `default_timeout_secs` on the Verify profile.

Example: 300
Responses
200

Expected verifications response to a valid request.

400

Unexpected error

Success Response
{
  "data": {
    "created_at": "2020-09-14T17:03:32.965812",
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    "phone_number": "+13035551234",
    "record_type": "verification",
    "status": "accepted",
    "timeout_secs": 300,
    "type": "sms",
    "updated_at": "2020-09-14T17:03:32.965812",
    "verify_profile_id": "12ade33a-21c0-473b-b055-b3c836e1c292"
  }
}

Retrieve a verificationretrieveVerification

get https://api.telnyx.com/v2/verifications/{verification_id}

Retrieve a verification

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/verifications/12ade33a-21c0-473b-b055-b3c836e1c292"
Parameters
In path
verification_id
string (uuid)
required

The identifier of the verification to retrieve.

Example: "12ade33a-21c0-473b-b055-b3c836e1c292"
Responses
200

Expected verifications response to a valid request.

400

Unexpected error

Success Response
{
  "data": {
    "created_at": "2020-09-14T17:03:32.965812",
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    "phone_number": "+13035551234",
    "record_type": "verification",
    "status": "accepted",
    "timeout_secs": 300,
    "type": "sms",
    "updated_at": "2020-09-14T17:03:32.965812",
    "verify_profile_id": "12ade33a-21c0-473b-b055-b3c836e1c292"
  }
}

List verifications by phone numberlistVerifications

get https://api.telnyx.com/v2/verifications/by_phone_number/{phone_number}

List verifications by phone number

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/verifications/by_phone_number/+13035551234"
Parameters
In path
phone_number
string
required

+E164 formatted phone number.

Example: "+13035551234"
Responses
200

Expected verifications response to a valid request.

400

Unexpected error

Success Response
{
  "data": [
    {
      "created_at": "2020-09-14T17:03:32.965812",
      "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
      "phone_number": "+13035551234",
      "record_type": "verification",
      "status": "accepted",
      "timeout_secs": 300,
      "type": "sms",
      "updated_at": "2020-09-14T17:03:32.965812",
      "verify_profile_id": "12ade33a-21c0-473b-b055-b3c836e1c292"
    }
  ],
  "meta": {
    "page_number": 2,
    "page_size": 25,
    "total_pages": 3,
    "total_results": 55
  }
}

Submit a verification codeverifyVerificationCode

post https://api.telnyx.com/v2/verifications/by_phone_number/{phone_number}/actions/verify

Submit a verification code

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"code":"17686"}' \
  https://api.telnyx.com/v2/verifications/by_phone_number/+13035551234/actions/verify
Parameters
In path
phone_number
string
required

+E164 formatted phone number.

Example: "+13035551234"
In body (application/json)
code
string
required

This is the code the user submits for verification.

Example: "17686"
Responses
200

Expected verify response to a valid request.

400

Unexpected error

Success Response
{
  "data": {
    "phone_number": "+13035551234",
    "response_code": "accepted"
  }
}
Previous: Overview

Was this section helpful?