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": [
    {
      "call": {
        "default_call_timeout_secs": 30,
        "default_verification_timeout_secs": 300,
        "speech_template": "Hello, this is the Acme Inc verification code you requested: {code}."
      },
      "created_at": "2020-09-14T17:03:32.965812",
      "flashcall": {
        "default_verification_timeout_secs": 300
      },
      "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
      "name": "Test Profile",
      "psd2": {
        "default_verification_timeout_secs": 300
      },
      "record_type": "verification_profile",
      "sms": {
        "default_verification_timeout_secs": 300,
        "messaging_enabled": true,
        "messaging_template": "Hello, this is the Acme Inc verification code you requested: {code}.",
        "rcs_enabled": true,
        "vsms_enabled": true
      },
      "updated_at": "2020-09-14T17:03:32.965812",
      "webhook_failover_url": "http://example.com/webhook/failover",
      "webhook_url": "http://example.com/webhook",
      "whatsapp": {
        "app_name": "Example Secure App",
        "default_verification_timeout_secs": 300
      }
    }
  ],
  "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
Example: "Test Profile"
call
object
optional
flashcall
object
optional
psd2
object
optional
sms
object
optional
webhook_failover_url
string
optional
Example: "http://example.com/webhook/failover"
webhook_url
string
optional
Example: "http://example.com/webhook"
whatsapp
object
optional
Responses
200

Expected Verify profile response to a valid request.

400

Unexpected error

Success Response
{
  "data": {
    "call": {
      "default_call_timeout_secs": 30,
      "default_verification_timeout_secs": 300,
      "speech_template": "Hello, this is the Acme Inc verification code you requested: {code}."
    },
    "created_at": "2020-09-14T17:03:32.965812",
    "flashcall": {
      "default_verification_timeout_secs": 300
    },
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    "name": "Test Profile",
    "psd2": {
      "default_verification_timeout_secs": 300
    },
    "record_type": "verification_profile",
    "sms": {
      "default_verification_timeout_secs": 300,
      "messaging_enabled": true,
      "messaging_template": "Hello, this is the Acme Inc verification code you requested: {code}.",
      "rcs_enabled": true,
      "vsms_enabled": true
    },
    "updated_at": "2020-09-14T17:03:32.965812",
    "webhook_failover_url": "http://example.com/webhook/failover",
    "webhook_url": "http://example.com/webhook",
    "whatsapp": {
      "app_name": "Example Secure App",
      "default_verification_timeout_secs": 300
    }
  }
}

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": {
    "call": {
      "default_call_timeout_secs": 30,
      "default_verification_timeout_secs": 300,
      "speech_template": "Hello, this is the Acme Inc verification code you requested: {code}."
    },
    "created_at": "2020-09-14T17:03:32.965812",
    "flashcall": {
      "default_verification_timeout_secs": 300
    },
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    "name": "Test Profile",
    "psd2": {
      "default_verification_timeout_secs": 300
    },
    "record_type": "verification_profile",
    "sms": {
      "default_verification_timeout_secs": 300,
      "messaging_enabled": true,
      "messaging_template": "Hello, this is the Acme Inc verification code you requested: {code}.",
      "rcs_enabled": true,
      "vsms_enabled": true
    },
    "updated_at": "2020-09-14T17:03:32.965812",
    "webhook_failover_url": "http://example.com/webhook/failover",
    "webhook_url": "http://example.com/webhook",
    "whatsapp": {
      "app_name": "Example Secure App",
      "default_verification_timeout_secs": 300
    }
  }
}

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)
call
object
optional
flashcall
object
optional
name
string
optional
Example: "Test Profile"
psd2
object
optional
sms
object
optional
webhook_failover_url
string
optional
Example: "http://example.com/webhook/failover"
webhook_url
string
optional
Example: "http://example.com/webhook"
whatsapp
object
optional
Responses
200

Expected Verify profile response to a valid request.

400

Unexpected error

Success Response
{
  "data": {
    "call": {
      "default_call_timeout_secs": 30,
      "default_verification_timeout_secs": 300,
      "speech_template": "Hello, this is the Acme Inc verification code you requested: {code}."
    },
    "created_at": "2020-09-14T17:03:32.965812",
    "flashcall": {
      "default_verification_timeout_secs": 300
    },
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    "name": "Test Profile",
    "psd2": {
      "default_verification_timeout_secs": 300
    },
    "record_type": "verification_profile",
    "sms": {
      "default_verification_timeout_secs": 300,
      "messaging_enabled": true,
      "messaging_template": "Hello, this is the Acme Inc verification code you requested: {code}.",
      "rcs_enabled": true,
      "vsms_enabled": true
    },
    "updated_at": "2020-09-14T17:03:32.965812",
    "webhook_failover_url": "http://example.com/webhook/failover",
    "webhook_url": "http://example.com/webhook",
    "whatsapp": {
      "app_name": "Example Secure App",
      "default_verification_timeout_secs": 300
    }
  }
}

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": {
    "call": {
      "default_call_timeout_secs": 30,
      "default_verification_timeout_secs": 300,
      "speech_template": "Hello, this is the Acme Inc verification code you requested: {code}."
    },
    "created_at": "2020-09-14T17:03:32.965812",
    "flashcall": {
      "default_verification_timeout_secs": 300
    },
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    "name": "Test Profile",
    "psd2": {
      "default_verification_timeout_secs": 300
    },
    "record_type": "verification_profile",
    "sms": {
      "default_verification_timeout_secs": 300,
      "messaging_enabled": true,
      "messaging_template": "Hello, this is the Acme Inc verification code you requested: {code}.",
      "rcs_enabled": true,
      "vsms_enabled": true
    },
    "updated_at": "2020-09-14T17:03:32.965812",
    "webhook_failover_url": "http://example.com/webhook/failover",
    "webhook_url": "http://example.com/webhook",
    "whatsapp": {
      "app_name": "Example Secure App",
      "default_verification_timeout_secs": 300
    }
  }
}

Trigger a SMS verificationcreateVerificationSMS

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

Trigger a SMS 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"}' \
  https://api.telnyx.com/v2/verifications/sms
Parameters
In body (application/json)
phone_number
string
required

+E164 formatted phone number.

Example: "+13035551234"
verify_profile_id
string (uuid)
required

The identifier of the associated Verify profile.

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

The number of seconds the verification code is valid for.

Example: 300
Responses
200

Expected verifications response to a valid request.

400

Unexpected error

Success Response
{
  "data": {
    "call_timeout_secs": 299,
    "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,
    "updated_at": "2020-09-14T17:03:32.965812",
    "verification_type": "sms_verification",
    "verify_profile_id": "12ade33a-21c0-473b-b055-b3c836e1c292"
  }
}

Trigger a PSD2 verificationcreateVerificationPSD2

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

Trigger a PSD2 verification

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"amount":"99.99","currency":"USD"}' \
  https://api.telnyx.com/v2/verifications/psd2
Parameters
In body (application/json)
amount
string
required
Example: "99.99"
currency
string
required

The supported currencies.

Example: "USD"
Options: [ "USD", "EUR", "GBP", "AUD", "CAD" ]
payee
string
required
Example: "Acme Corp Inc. LTD"
phone_number
string
required

+E164 formatted phone number.

Example: "+13035551234"
verify_profile_id
string (uuid)
required

The identifier of the associated Verify profile.

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

The number of seconds the verification code is valid for.

Example: 300
Responses
200

Expected verifications response to a valid request.

400

Unexpected error

Success Response
{
  "data": {
    "call_timeout_secs": 299,
    "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,
    "updated_at": "2020-09-14T17:03:32.965812",
    "verification_type": "sms_verification",
    "verify_profile_id": "12ade33a-21c0-473b-b055-b3c836e1c292"
  }
}

Trigger a Call verificationcreateVerificationCall

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

Trigger a Call 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"}' \
  https://api.telnyx.com/v2/verifications/call
Parameters
In body (application/json)
phone_number
string
required

+E164 formatted phone number.

Example: "+13035551234"
verify_profile_id
string (uuid)
required

The identifier of the associated Verify profile.

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

Must be less than the profile's default_verification_timeout_secs or timeout_secs, whichever is lesser.

Example: 30
timeout_secs
integer
optional

The number of seconds the verification code is valid for.

Example: 300
Responses
200

Expected verifications response to a valid request.

400

Unexpected error

Success Response
{
  "data": {
    "call_timeout_secs": 299,
    "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,
    "updated_at": "2020-09-14T17:03:32.965812",
    "verification_type": "sms_verification",
    "verify_profile_id": "12ade33a-21c0-473b-b055-b3c836e1c292"
  }
}

Trigger a Flash call verificationcreateVerificationFlashcall

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

Trigger a Flash call 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"}' \
  https://api.telnyx.com/v2/verifications/flashcall
Parameters
In body (application/json)
phone_number
string
required

+E164 formatted phone number.

Example: "+13035551234"
verify_profile_id
string (uuid)
required

The identifier of the associated Verify profile.

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

The number of seconds the verification code is valid for.

Example: 300
Responses
200

Expected verifications response to a valid request.

400

Unexpected error

Success Response
{
  "data": {
    "call_timeout_secs": 299,
    "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,
    "updated_at": "2020-09-14T17:03:32.965812",
    "verification_type": "sms_verification",
    "verify_profile_id": "12ade33a-21c0-473b-b055-b3c836e1c292"
  }
}

Trigger a Whatsapp verificationcreateVerificationWhatsapp

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

Trigger a Whatsapp 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"}' \
  https://api.telnyx.com/v2/verifications/whatsapp
Parameters
In body (application/json)
phone_number
string
required

+E164 formatted phone number.

Example: "+13035551234"
verify_profile_id
string (uuid)
required

The identifier of the associated Verify profile.

Example: "12ade33a-21c0-473b-b055-b3c836e1c292"
app_name
string
optional

The name that identifies the application requesting 2fa in the verification message.

Example: "Example Secure App"
timeout_secs
integer
optional

The number of seconds the verification code is valid for.

Example: 300
Responses
200

Expected verifications response to a valid request.

400

Unexpected error

Success Response
{
  "data": {
    "call_timeout_secs": 299,
    "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,
    "updated_at": "2020-09-14T17:03:32.965812",
    "verification_type": "sms_verification",
    "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": {
    "call_timeout_secs": 299,
    "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,
    "updated_at": "2020-09-14T17:03:32.965812",
    "verification_type": "sms_verification",
    "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": [
    {
      "call_timeout_secs": 299,
      "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,
      "updated_at": "2020-09-14T17:03:32.965812",
      "verification_type": "sms_verification",
      "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?