Send Two-Factor Authentication Messages
You can easily verify your customers using their phone numbers with the help of 2FA (better known as two-factor authentication) and protect against fraud, build trust, and increase conversions. There is a simple way to do this with an API call to a Textmagic endpoint. With the help of Textmagic API you can:
- Send two-factor authentication messages (2FA)
- Send one-time passwords (OTP)
- Integrate passwordless login into your app
- Protect your app from fraud
How does it work?
Step 1: Your server makes an API call to the Textmagic endpoint, and we send a text message (and later, as a fallback, a generate a text-to-speech voice call) with a verification code to the phone number supplied in the initial request.
Step 2: Once the code is received, the user enters it into the relevant input field in your app. This code needs to be passed to Textmagic in the second API call; if it is correct, the server will respond with the correct response code. This way, you can ensure that the recipient really owns the phone number entered into your app or form.
Step 1: Send a verification code
To send a verification code to the desired number, use:
POST
with the following parameters:
|
Name
|
Required?
|
Example
|
Description
|
|---|---|---|---|
| phone | Yes |
447860021130
|
Use the phone number in international E.164 format. If you need to pass phone numbers in the local format, please use them with the country parameter to specify the origin country of the phone number. |
| brand | Yes | Textmagic |
Alphanumeric string with up to 18 characters you can use to personalize the verification text message body, to help users identify your company or application name. For example: “Your Textmagic PIN is …” |
| codeLength | Yes | 4 |
The length of the verification code. The value can be 4 or 6 characters. |
| language | No | en-gb |
By default, the SMS or text-to-speech (TTS) voice message is generated in the locale that matches the number. For example, the text message or TTS message for a 33* number is sent in French. Use this parameter to explicitly control the language, accent, and gender used for the verification request.
Can be one of the following: de-de, en-au, en-gb, en-us, en-in, es-es, es-mx, es-us, fr-ca, fr-fr, is-is, it-it, ja-jp, ko-kr, nl-nl, pl-pl, pt-pt, pt-br, ro-ro, ru-ru, sv-se, tr-tr, zh-cn or zh-tw. |
| senderId | No | Textmagic |
One of the available sender settings on your Textmagic account. If specified sender setting type is not allowed for some destinations, a fallback default sender will be used to ensure the message delivery. More info about known restrictions can be found here. |
| country | No | US |
2-letter ISO country code for local phone number. |
| workflowId | No | 1 |
Workflows: 1. SMS -> TTS -> TTS 2. SMS -> SMS -> TTS 3. TTS -> TTS 4. SMS -> SMS 5. SMS -> TTS 6. SMS 7. TTS |
You will receive the following response:
|
Parameter
|
Example
|
Description
|
|---|---|---|
| verifyId |
123e4567-e89b-12d3-a456-426655440000
|
The ID of a verification request. This is required to finish the verification request in the next step. |
| price | 0.05 |
Amount of credit which will be deducted from your account balance when this verification is successfully completed. |
Step 2: Check the verification code
To check the verification code and finish the verification, use:
PUT
with the following parameters:
|
Name
|
Required?
|
Example
|
Description
|
|---|---|---|---|
| code | Yes |
1234
|
Verification code that was received by the user and entered into the form field. |
| verifyId | Yes | 123e4567-e89b-12d3-a456-426655440000 |
VerifyId from Step 1 to match both requests together. |
If the verification was successful you will receive the 204 HTTP response code (No content).
Verification workflow
Textmagic verification API sends PIN code by text messages or voice calls. Below you will find the description of the default workflow.
- Send a text message with a verification code.
- Wait for 60 seconds.
- If the correct code was not supplied, send the first text-to-speech voice call.
- Wait for 60 seconds.
- If the code was not supplied, send the second text-to-speech voice call.
- Wait for the verification. The verification code is valid for 5 minutes since the initial request.
Available workflows
Workflow 1 (Default Workflow): SMS -> TTS -> TTS
Send PIN code by text message, follow up with two subsequent voice calls if the request wasn’t already verified.
Send SMS to user with PIN code
Wait for 60 seconds
Call user and give TTS PIN code
Wait for 60 seconds Call user and give TTS PIN code
Request expires after 300 seconds
Workflow 2: SMS -> SMS -> TTS
Send PIN code by text message, follow up with a second text message and finally a voice call if the request has not been verified.
Send SMS to user with PIN code
Wait for 60 seconds
Send SMS to user with PIN code
Wait for 60 seconds
Call user and give TTS PIN code
Request expires after 300 seconds
Workflow 3: TTS -> TTS
Call the user and speak a PIN code, follow up with a second call if the request wasn’t already verified.
Call user and give TTS PIN code
Wait for 60 seconds
Call user and give TTS PIN code
Request expires after 300 seconds
Workflow 4: SMS -> SMS
Send PIN code by text message, follow up with a second text message if the code hasn’t been verified.
Send SMS to user with PIN code
Wait for 60 seconds
Send SMS to user with PIN code
Wait for 60 seconds
Request expires after 300 seconds
Workflow 5: SMS -> TTS
Send PIN code by text message, follow up with a voice call if the code hasn’t been verified.
Send SMS to user with PIN code
Wait for 60 seconds
Call user and give TTS PIN code
Request expires after 300 seconds
Workflow 6: SMS
Send PIN code by text message once only.
Send SMS to user with PIN code
Request expires after 300 seconds
Workflow 7: TTS
Call the user and speak a PIN code once only.
Call user and give TTS PIN code
Request expires after 300 seconds
Cancel a verification
You can cancel the verification not earlier than 30 seconds after the initial request. In case it is needed to cancel verification, use:
DELETE {verifyId}
where you should replace the verifyId that you received in Step 1. This command has no parameters.
When verification is successfully canceled, you will receive the 204 HTTP response code (No content).
