Add reliable and efficient security to web applications by authenticating users with one-time passcodes delivered through SMS or Voice Calls.
Use the Verify API to create user Verifications that deliver a one time passcode (OTP) to a specified phone number through either SMS or a voice call. Each verification uses a simple, templated message, optimized for conversion, in which developers can optionally insert a Brand name of their choosing. The code returned by the recipient is then asserted against the Verification and is either verified or rejected.
Note: Brand can only be used if the Verification is sent from a phone number provisioned to your Voxology application.
pending
until a code is verified, the maximum number of assert attempts is reached, or it times out. {
"verification_id": "ce66e293-c921-46ea-a085-e186f681d24c",
"verify_no": "+15558701034",
"api_no": "+15553246897",
"channel": "sms",
"brand": "Company Name",
"status": "pending",
"reason": null,
"code_length": 6,
"time_to_live": 10,
"assert_attempts": 0,
"created_on": "2024-01-01T00:00:00.000Z",
"updated_on": "2024-01-01T00:00:00.000Z"
}
Verifications can be sent through either SMS or Voice. All calls and messages initiated through the Verify API have their service
property set to verify
. Use this to filter logs and view usage for the Verify API.
To send a OTP through SMS, set the channel
property to "sms"
. All Verifications sent through SMS use a default, templated message.
To send an OTP with a voice call, set the channel
property to "voice"
. All Verifications sent through voice use a default text-to-speech message.
Once a code has been returned by the authenticating user, it can be asserted against the Verification by ID. The Verify API will return either a verified
or failed
status in response to an assert request. Each Verification has a maximum of 3 assert attempts before its status changes to failed
. Once the time-to-live on the Verification expires a code cannot be asserted.
{
"verification_id": "ce66e293-c921-46ea-a085-e186f681d24c",
"status": "verified"
}
This tutorial is a step-by-step guide to using the Verify API.
In order to use a branded message for your Verification, you must provision a unique phone number to your Voxology application. For help provisioning numbers, see our Provision Phone Number tutorial.
Note: to send Verifications through SMS using a unique number, the number must also be a Long Code registered to an approved 10DLC Campaign, a Toll-Free number verified for SMS, or an approved Short Code.
To start a new Verification, use the Initiate Verification request. In the request body, define the phone number to send the OTP to, the phone number to use as the sender, the channel to use, the Brand to include in the message, the length of the code and the time-to-live for the Verification.
curl -X POST \
https://api.voxolo.gy/v1/Verifications \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR_API_KEY' \
-d '{
"verify_no": "+15558701034",
"api_no": "+15553246897",
"channel": "sms",
"brand": "Company Name",
"code_length": 6
"time_to_live": 10
}'
Once a OTP has been returned by the recipient, use the Assert Verification request to either verify or fail the authenticating user. Verifications can be asserted 3 times before the status updates to failed
. Only Verifications with status pending
can be asserted.
curl -X POST \
https://api.voxolo.gy/v1/Verifications/ce66e293-c921-46ea-a085-e186f681d24c/Assert \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR_API_KEY' \
-d '{
"code": "639469"
}'
If you wish to cancel a Verification while it’s still pending
, use the Cancel Verification request. Canceling a verification updates its status to canceled
.
curl -X DELETE \
https://api.voxolo.gy/v1/Verifications/ce66e293-c921-46ea-a085-e186f681d24c \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR_API_KEY'
Congratulations! You can now verify users in your own application.