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 https://rest.textmagic.com/api/v2/verify

with the following parameters:

Name
Required?
Example
Description
phoneYes 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. 
brandYesTextMagicAlphanumeric 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 …”
codeLengthYes4The length of the verification code. The value can be 4 or 6 characters.
languageNoen-gbBy 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.
senderIdNoTextMagicOne 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.
countryNoUS2-letter ISO country code for local phone number.

You will receive the following response:

Parameter
Example
Description
verifyId 123e4567-e89b-12d3-a456-426655440000The ID of a verification request. This is required to finish the verification request in the next step.
price0.05Amount 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 https://rest.textmagic.com/api/v2/verify

with the following parameters:

Name
Required?
Example
Description
codeYes 1234 Verification code that was received by the user and entered into the form field.
verifyIdYes123e4567-e89b-12d3-a456-426655440000VerifyId 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 a PIN code by text message and follows up with two subsequent voice calls if the request wasn’t completed or canceled. Below you will find the description of the default workflow.

  1. Send a text message with a verification code.
  2. Wait for 60 seconds.
  3. If the correct code was not supplied, send the first text-to-speech voice call.
  4. Wait for 60 seconds.
  5. If the code was not supplied, send the second text-to-speech voice call.
  6. Wait for the verification. The verification code is valid for 5 minutes since the initial request.
Please note: Submitting another verification request for the same phone number before the original code has expired will result in a 409 error code. The new verification request can be submitted only once the previous code has expired (after 5 minutes) or canceled.

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 https://rest.textmagic.com/api/v2/verify/{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).