By following the instructions below, you can have your OTP SMS verification service up and running in under 10 minutes.

1. From your SMS.CX Account Dashboard go to HTTP API and create a new application. Save the Application Id and Application Secret so that you can use them later in your code to authenticate and make API calls.

2. Edit the settings of the newly created application and navigate to the OTP tab. This tab contains the OTP default settings, which you can adjust to fit your situation.

   

   1. Text template - the text message that will be sent to the mobile number via SMS. The text must contain the {{pin}} placeholder, which will be replaced by the API with the generated PIN code. In addition to the general text template, you can also add text templates in different languages based on the phone's prefix.
   2. Originator - the sender ID (sender name) that will show on recipients' device as the message sender
   3. PIN type - the type of PIN code that will be generated and sent to the user via SMS: it can be letters (eg. GRNXQ), numbers (eg. 56421) and alphanumeric (eg. YT53M)
      
   4. PIN length - the character length of the code that will be generated. Can have values between 4 and 10 character length
   5. PIN TTL (time-to-live) - the PIN time to live (or lifetime). The OTP API returns status EXPIRED if the user tries to validate the PIN after the PIN TTL. The PIN's TTL begins immediatly after the OTP SMS request. Can have values between 1 and 30 minutes
   6. Maximum validation attempts - the number of times a user is allowed to try to enter an incorrect PIN code. After the maximum number of attempts the OTP API will return the status FAILED. Can have values between 1 and 10 attempts
   7. OTP status callback URL (Webhook) - a valid URL for getting real-time status updates on the OTP verification process.

   The default OTP settings will be overwritten if your OTP API request has one of the settings parameters in the body.

3. Perform a phone number verification by making an OTP API request:

   POST /otp HTTP/1.1
   Host: api.sms.cx
   Authorization: Bearer M2ZkOTcxNzZiZDdlMzZjMGU3GmJ...
   Content-Type: application/json
   
   {
       "to": "+336124241xx",
       "from": "Verify"
   }

   You need to get a bearer access token using application ID & secret and use that token in the request.

   The OTP API response will contain the otpId, which you will use to check the status of the phone verification:

   {
       "otpId": "f91536c1-2aff-43b4-b6fa-15e8ade52946",
       "phoneNumber": "+336124241xx",
       "countryIso": "FR",
       "status": "PENDING",
       "cost": 0.043,
       "parts": 1,
       "maxAttempts": 5,
       "attempts": 0,
       "ttl": 300,
       "otpCallbackUrl": "https://my-webhook/receive-otp-status",
       "dateCreated": "2022-10-18 09:01:47",
       "dateExpires": "2022-10-18 09:06:47"
   }

4. The user fills out your form using the code they received through SMS and submits it. After the form is submitted, your application performs a request to the OTP API with the otpId and the user's PIN to check the status of the verification, which can be VERIFIED, FAILED, EXPIRED, etc.

   POST /otp/f91536c1-2aff-43b4-b6fa-15e8ade52946 HTTP/1.1
   Host: api.sms.cx
   Authorization: Bearer M2ZkOTcxNzZiZDdlMzZjMGU3GmJ...
   Content-Type: application/json
   
   {
       "pin": "28822"
   }

   The OTP API response will contain the status of the OTP verification:

   {
       "status": "VERIFIED"
   }

Read more about the workflow of OTP SMS.

Check the list of OTP statuses for all available statuses and the flowchart diagram of transitions between OTP statuses.