Verify (OTP) | touchSMS Developers

The Verify API sends a one-time code to a phone number by SMS and checks the code your user enters. Use it to confirm a number at sign-up, or as a second factor at login. We generate, send, store and expire the codes, so you don’t have to.

The Verify endpoints are under /v3, for example https://app.touchsms.com.au/api/v3/verify.

The flow

Create a verification

Call Create verification with the user’s number. We generate a code and send it by SMS.

curl -u "ACCESS_TOKEN:TOKEN_ID" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -X POST https://app.touchsms.com.au/api/v3/verify \
  -d '{ "destination": "+61412345678" }'

Store the returned id (a UUID) against the user’s session. You need it to check the code.

The user enters the code
Ask the user for the code they received.

Check the code

Call Check verification with the stored id and the code the user entered:

curl -u "ACCESS_TOKEN:TOKEN_ID" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -X POST https://app.touchsms.com.au/api/v3/verify/VERIFY_ID/verify \
  -d '{ "code": "123456" }'

Reading the result

The check always returns the verification. Use verify_success to decide whether the user passed:

{
  "data": {
    "id": "cb4d9527-1d3a-4def-85ba-f1fec9489c4f",
    "status": "verified"
  },
  "verify_success": true,
  "verify_error": null
}

When the check fails, verify_success is false and verify_error says why:

{
  "data": {
    "id": "cb4d9527-1d3a-4def-85ba-f1fec9489c4f",
    "status": "sent"
  },
  "verify_success": false,
  "verify_error": "Provided code does not match verify"
}

`verify_error`	Meaning
`Provided code does not match verify`	Wrong code. The user can try again until the verification expires.
`Verify expired before check request`	The code expired. Create a new verification.
`Verify cancelled before check request`	The verification was cancelled.
`Verify already used`	The code was already checked successfully. Each verification can be used once.

A verification’s status is one of created, sent, verified, expired, failed or cancelled.

Options

Create verification accepts optional fields to tailor the message and the code:

Field	Default	Notes
`source`	Your account’s default sender	Sender ID for the SMS. It must be a verified sender ID on your account.
`template`	`Your verification code is %code%`	Message text. Must contain `%code%`.
`expiry_seconds`	`300`	How long the code stays valid, from 10 to 3600 seconds.
`token_length`	`6`	Code length, from 6 to 10 characters.
`metadata`		Key/value pairs to store with the verification, such as the action the user was attempting. Same limits as message metadata.

Check or cancel by destination

You can also check a code by destination number instead of by id. This checks the most recent verification for that number.

To stop a code from being used, cancel the verification, or cancel every verification for a number. For example, cancel outstanding codes when a user asks for a new one.

Protect the flow

The API doesn’t limit how many times a code can be checked before it expires, so add your own limits:

Limit how many codes one user, number or IP address can request in a period.
Limit wrong guesses per verification, then cancel it and make the user request a new code.
Put a CAPTCHA or similar in front of the “send code” step on public forms.

See Security.