This is a standard REST + JSON over HTTPS. This API does a series of things on top of just sending the PIN code: it cleanses the phone number, throttle the requests not to overload the phone, detects if its an authentic transaction, generates the pin code and smart routes it to the phone number.
Every time one of your users requests for a PIN code, we need to throttle future requests to the same phone number since Carriers may detect the same SMS being sent and block them for SPAM. We do this based on the PHONE NUMBER. To understand when you are allowed to send another PIN code, please check retry_at field on every HTTP response.
You start by requesting a PIN code to be sent using any enabled service for the application key such as SMS or VOICE. This endpoint is streamlined to ensure deliverability of the PIN code to the desired phone number. Logic includes dynamically determining the best route based on latency and delivery rates, phone number normalization based on 200+ dialing plans, blacklists and others.
Request
POST /${app_key}/code/${service} HTTP/1.1Host: <https://api.ringcaptcha.com>
Content-Type: application/x-www-url-encoded; charset=utf-8
Parameters
Response
Status: 200 OK{
"id":"Transaction ID",
"token":"Transaction token",
"status":"SUCCESS or ERROR",
"message":"Error code when Status is ERROR",
"phone":"Cleansed phone number",
"service":"Service used to send PIN code",
"expires_in":"Seconds this token is still active",
"retry_in":"Seconds you need to wait until a new request can be made"
}
Example:
curl --data-urlencode "phone=+1234567890" --data-urlencode "api_key={{ api_key }}" <https://api.ringcaptcha.com/>{{ app_key }}/code/sms{
"status":"SUCCESS",
"token":"XXXXYYYYZZZZAAAABBBB",
"id":"UUUUUUUUUUUUUUU",
"phone":"+1234567890",
"service":"SMS",
"retry_in":60,
"expires_in":900
}
After the user has received the code, you will need to execute one last HTTP request with the PIN code the user received to close the verification loop. This step ensures the transactions is authentic and verifies the PIN code inserted by the user matches the one sent via SMS/Voice. This endpoint will also return available information of the phone number, like the carrier, type, normalized phone number, etc.
Request
POST /${app_key}/verify HTTP/1.1Host: <https://api.ringcaptcha.com>
Content-Type: application/x-www-url-encoded; charset=utf-8
Parameters
Response