Phone Verification
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.
Sending a PIN Code
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.1
Host: https://api.ringcaptcha.com
Content-Type: application/x-www-url-encoded; charset=utf-8
Parameters
Name | Description |
---|---|
app_key | Your application key |
api_key | Your API key |
phone | Phone number in international format as described in E.123. It also accepts a comma-separated list of phones for multiple verifications. |
service | Service to use when sending the PIN code. Availables are: SMS, Voice |
token (optional) | Should you have a token already created and valid, send it thru this parameter |
locale (optional) | The locale/language to send the SMS/Voice call in. Availables are: ar (Arabic), de (German), en (US English), en_gb (UK English), es (Spanish), fi (Finnish), fr (French), gr (Greek), it (Italian), ja (Japanese), nl (Dutch), pt (Portuguese), ru (Russian), sv (Swedish), tr (Turkish), zh Chinese |
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 }
Verifying the PIN code
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.1
Host: https://api.ringcaptcha.com
Content-Type: application/x-www-url-encoded; charset=utf-8
Parameters
Name | Description |
---|---|
app_key | Your application key |
api_key | Your API key |
phone | Phone number in international format as described in E.123. Either this parameter or token must be sent. |
code | The 4 digit PIN code to verify with the one sent in the code endpoint |
token | The token received by the code endpoint when requesting a PIN code to be sent. Either this parameter or phone must be sent. |
Response
Status: 200 OK
{ "id":"Transaction ID", "status":"SUCCESS or ERROR", "message":"Error code when Status is ERROR", "phone":"Cleansed phone number", "geolocation":"Information about the geo-location of the phone if possible and feature enabled", "threat_level":"an indicator detailing the transaction threat level (e.g.: low, medium or high)", "phone_type":"LANDLINE, MOBILE, VOIP, etc", "carrier":"name of carrier", "referer":"url of the widget where the user asked PIN code" }
Example:
curl --data-urlencode "phone=+1234567890" --data-urlencode "api_key={{ api_key }}" --data-urlencode "code=1234" https://api.ringcaptcha.com/{{ app_key }}/verify
{ "status":"SUCCESS", "id":"UUUUUUUUUUUUUUU", "phone":"+1234567890", "geolocation":0, "phone_type":"MOBILE", "carrier":"AT&T", "threat_level":"LOW", "referer":"http:\/\/localhost\/demo\/" }
Implementing SMS Deep-Linking
Every SMS link sent by RingCaptcha will deep-link the user to either the application store for onboarding or the installed application for verification. Ringcaptcha link will redirect to the configured scheme and host for the app whenever a user opens the SMS link in their browser, the following URL:
scheme://ringcaptcha/verified?token={TOKEN}&pin={PIN_CODE}
Whitelists
Whenever you want to bypass all blocks like allowing a specific VOIP number, or allowing the same number to verify X amount of times, checking the numbers that have been whitelisted or deleting a previously whitelisted number, you will need to use this endpoint.
Adding a Phone Number to the Whitelist
Request
POST /apps/${app_key}/whitelist HTTP/1.1
Host: https://api.ringcaptcha.com
Content-Type: application/x-www-url-encoded; charset=utf-8
Parameters
Name | Description |
---|---|
app_key | Your application key |
api_key | Your API key |
phone | Phone number in international format as described in E.123. to whitelist |
add_verifications | Amount of verifications to allow extra for this phone number |
Description | Any description you'd like to include. |
Response
Status: 200 OK
{ "phone_number":"1234567890", "max_verifications":"XX", "description":"description", "created_at":"2015-01-26 17:33:30", "updated_at":"2015-01-27 20:42:59" }
Example:
curl --data-urlencode "api_key={{ api_key }}" --data-urlencode "phone=+1234567890" --data-urlencode "add_verifications=2" --data-urlencode "description=whitelisting" https://api.ringcaptcha.com/apps/{{ app_key }}/whitelist
{ "phone_number":"1234567890", "max_verifications":"2", "description":"whitelisting", "created_at":"2015-01-27 20:42:59", "updated_at":"2015-01-27 20:42:59" }
Listing all whitelisted numbers
Request
GET /apps/${app_key}/whitelist/show HTTP/1.1
Host: https://api.ringcaptcha.com
Content-Type: application/x-www-url-encoded; charset=utf-8
Parameters
Name | Description |
---|---|
app_key | Your application key |
api_key | Your API key |
Response
Status: 200 OK
[{ "cleansed_number":"1234567890", "verifications_allowed":"XX", "description":"....", "created_at":"2015-01-27 20:42:59", "updated_at":"2015-01-27 20:42:59" },...]
Example:
curl https://api.ringcaptcha.com/apps/{{ app_key }}/whitelist?api_key={{ api_key }}
[{ "cleansed_number":"1234567890", "verifications_allowed":"2", "description":"whitelisting", "created_at":"2015-01-27 20:42:59", "updated_at":"2015-01-27 20:42:59" },{ "cleansed_number":"1234567890", "verifications_allowed":"100", "description":"Whitelisted", "created_at":"2015-01-27 20:42:59", "updated_at":"2015-01-27 20:42:59" }]
Removing a whitelisted number
Request
DELETE /apps/${app_key}/whitelist HTTP/1.1
Host: https://api.ringcaptcha.com
Content-Type: application/x-www-url-encoded; charset=utf-8
Parameters
Name | Description |
---|---|
app_key | Your application key |
api_key | Your API key |
phone | Phone number in international format as described in E.123. to whitelist |
Response
Status: 200 OK
{ "phone_number":"1234567890", "max_verifications":"XX", "description":"description", "created_at":"2015-01-26 17:33:30", "updated_at":"2015-01-27 20:42:59" }
Example:
curl -X DELETE --data-urlencode "api_key={{ api_key }}" --data-urlencode "phone=+1234567890" https://api.ringcaptcha.com/apps/{{ app_key }}/whitelist
{ "phone_number":"1234567890", "max_verifications":"XX", "description":"description", "created_at":"2015-01-26 17:33:30", "updated_at":"2015-01-27 20:42:59" }
Blacklist
Whenever you want to block all PIN requests for a specific number, edit or remove a previously blacklisted number, you will need to use this endpoint.
Adding a number to the blacklist
In order to block all requests for a sending a PIN code to a number, POST to this endpooint with the number and all subsequent requests for PIN codes will be denied.
Request
POST /apps/${app_key}/blacklist HTTP/1.1
Host: https://api.ringcaptcha.com
Content-Type: application/x-www-url-encoded; charset=utf-8
Parameters
Name | Description |
---|---|
app_key | Your application key |
api_key | Your API key |
phone | Phone number in international format as described in E.123. to whitelist |
Description | Any description you'd like to include. |
Response
Status: 200 OK
{ "phone_number":"1234567890", "description":"description", "created_at":"2015-01-26 17:33:30", "updated_at":"2015-01-27 20:42:59" }
Example:
curl --data-urlencode "api_key=TTTTTTTTTTTTTTTTTTT" --data-urlencode "phone=+1234567890" --data-urlencode "description=fraud number" https://api.ringcaptcha.com/apps/XXXXXXX/blacklist
{ "phone_number":"1234567890", "description":"fraud number", "created_at":"2015-01-27 20:42:59", "updated_at":"2015-01-27 20:42:59" }
Listing all blacklisted numbers
In order to GET all previously blacklisted numbers, send a GET request like below.
Request
GET /apps/${app_key}/blacklist/show HTTP/1.1
Host: https://api.ringcaptcha.com
Content-Type: application/x-www-url-encoded; charset=utf-8
Parameters
Name | Description |
---|---|
app_key | Your application key |
api_key | Your API key |
Response
Status: 200 OK
[{ "phone_number":"1234567890", "description":"description", "created_at":"2015-01-26 17:33:30", "updated_at":"2015-01-27 20:42:59" },...]
Example:
curl --data-urlencode "api_key={{ api_key }}" https://api.ringcaptcha.com/apps/{{ app_key }}/blacklist
[{ "phone_number":"1234567890", "description":"fraud number", "created_at":"2015-01-27 20:42:59", "updated_at":"2015-01-27 20:42:59" },...]
Removing a blacklisted number
Request
DELETE /apps/${app_key}/blacklist HTTP/1.1
Host: https://api.ringcaptcha.com
Content-Type: application/x-www-url-encoded; charset=utf-8
Parameters
Name | Description |
---|---|
app_key | Your application key |
api_key | Your API key |
phone | Phone number in international format as described in E.123. to whitelist |
Response
Status: 200 OK
{ "phone_number":"1234567890", "description":"description", "created_at":"2015-01-26 17:33:30", "updated_at":"2015-01-27 20:42:59" }
Example:
curl -X DELETE --data-urlencode "api_key=YYYYYY" --data-urlencode "phone=+1234567890" https://api.ringcaptcha.com/apps/XXXXXXX/blacklist
{ "phone_number":"1234567890", "description":"description", "created_at":"2015-01-26 17:33:30", "updated_at":"2015-01-27 20:42:59" }
SMS Gateway
In order to send direct customized SMS messages to your user base using Ringcaptcha solid infrastructure you need to execute a POST request as described below.
Request
POST /${app_key}/sms HTTP/1.1
Host: https://api.ringcaptcha.com
Content-Type: application/x-www-url-encoded; charset=utf-8
Parameters
Name | Description |
---|---|
app_key | Your application key |
api_key | Your API key |
phone | Phone number in international format as described in E.123. It also accepts a comma-separated list of phones for multiple SMS. |
message | The message to send inside the SMS content. The message will automatically be split in 160 chars of ASCII or 70 chars UTF-8 (7-byte encoding) |
Response
Status: 200 OK
{ "id":"Transaction ID", "status":"SUCCESS or ERROR", "message":"Error code when Status is ERROR or SMS message delivered", "phone":"Cleansed phone number", "message_count":"Number of SMS sent" }
Example:
curl --data-urlencode "api_key={{ api_key }}" --data-urlencode "phone=+1234567890" --data-urlencode "message=Hi there" https://api.ringcaptcha.com/{{ app_key }}/sms
{ "status":"SUCCESS", "id":"455bb75ca3dc0da9945f8e217079d9c2862050b1", "phone":"+1234567890", "message":"Hi there" }
Phone Number Information
To obtain the information on a phone number (e.g.: country, area, block, subscriber number, type of line, carrier name, etc) you can send the number to this API endpoint. The service will cleanse the number according to every country dialing plan and will output the information or will error out with ERROR_INVALID_NUMBER and its reason.
Request
POST /${app_key}/normalize HTTP/1.1
Host: https://api.ringcaptcha.com
Content-Type: application/x-www-url-encoded; charset=utf-8
Parameters
Name | Description |
---|---|
app_key | Your application key |
api_key | Your API key |
phone | Phone number in international format. |
Response
Status: 200 OK
{ "status":"SUCCESS", "phone":"+XXXXXXXXX", "country":"XX", "area":"XX", "block":"XXXX", "subscriber":"XXXX" }
Example:
curl --data-urlencode "api_key={{ api_key }}" --data-urlencode "phone=+1234567890" https://api.ringcaptcha.com/{{ app_key }}/normalize
{ "status":"SUCCESS", "phone":"+1234567890", "country":"US", "area":"234", "block":"567", "subscriber":"890", "type":"MOBILE" }
Metrics
To obtain the information of your metrics such as Success Rate, Total Spend, Latency and total number of transactions per country and date you can either use our dashboard or integrate with this endpoint.
Request
GET /metrics HTTP/1.1
Host: https://api.ringcaptcha.com
Content-Type: application/x-www-url-encoded; charset=utf-8
Parameters
Name | Description |
---|---|
api_key | Your API key |
apps | (optional) List separated by pipes of the applications to get the metrics from. (e.g.: re1234as|23trewsa|...). If not specified it will use all apps owned by the API key. |
from | (Inclusive) Start Date of timerange in ISO8601 format (e.g.: 2015-01-27). Will set start time to 0hrs |
to | (Not Inclusive) End Date of timerange in ISO8601 format (e.g.: 2015-01-28). Will use time of 23:59:59hrs |
Response
Status: 200 OK
{ "verification":{ "country":{ "us":{ "transactions":X, "spend":X (US), "rate":Y(%), "latency":Z(sec) } }, "timestamp":{ "1419638400":{ "transactions":X, "spend":X (US), "rate":Y(%), "latency":Z(sec) } }, "total":{ "transactions":X, "spend":X (US), "rate":Y(%), "latency":Z(sec) } }, "gateway":{ "country":{ "us":{ "rate":Y(%), "spend":X (US), "transactions":X } }, "timestamp":{ "1419638400":{ "rate":Y(%), "spend":X (US), "transactions":X } }, "total":{ "rate":Y(%), "spend":X (US), "transactions":X } } }
Example:
curl https://api.ringcaptcha.com/metrics?api_key={{ api_key }}&from=2014-12-27T20:00:00%2B00:00&to=2015-01-27T20:00:00%2B00:00
{ "verification":{ "country":{ "us":{ "transactions":6, "spend":0.06, "rate":"100.00", "latency":9.5 } }, "timestamp":{ "1419638400":{ "transactions":0, "spend":0, "rate":null, "latency":0 }, ... "1422230400":{ "transactions":0, "spend":0, "rate":null, "latency":0 } }, "total":{ "transactions":46, "spend":2.895, "rate":"88", "latency":19.5 } }, "gateway":{ "country":{ "us":{ "rate":"100.00", "spend":0.03, "transactions":3 } }, "timestamp":{ "1419638400":{ "rate": "95.00", "spend":0.01, "transactions":1 }, ... "1422230400":{ "rate": "98.00", "spend":0.02, "transactions":2 } }, "total":{ "rate":"100.00", "spend":0.03, "transactions":3 } } }
Apps
To create, edit, list and delete apps you can interact with our panel or use this endpoint.
Create an App
Request
POST /apps HTTP/1.1
Host: https://api.ringcaptcha.com
Content-Type: application/x-www-url-encoded; charset=utf-8
Parameters
Name | Description |
---|---|
api_key | Your API key |
Domain | Domain of any WEBSITE or ONBOARDING app where the widget will be placed |
Name | Mobile App name to identify on RingCaptcha and validate widgets with |
type | One of the following: WEBSITE, MOBILE, ONBOARDING, etc. |
sender_id | Sender Id that the SMS will be sent with whenever possible. Can be a number or alphanumeric up to 11 digits. |
custom_message | Custom SMS message template to use for verifications. You can include any locale that will be used here. Use %PIN% where you want us to input the PIN code |
service | Default service to use when nothing specified via API or widget. Values are SMS or VOICE. |
geolocation | Turn on/off geolocation of widgets |
whitelabel | true: Display ringcaptcha logo or false to hide it |
Response
Status: 200 OK
{ "app_key":"XXXXXXXX", "secret_key":"YYYYYYY", "name":[ "domain.com" ], "type":"WEBSITE", "service":"SMS", "sender_id":"sender", "custom_message":{ "en":"Enter %PIN% into the app to verify." } }
Example:
curl -X POST https://api.ringcaptcha.com/apps --data-urlencode "api_key={{ api_key }}" --data-urlencode "name=app" --data-urlencode "type=MOBILE" --data-urlencode "sender_id=SENDER" --data-urlencode "custom_message={\"en\":\"Enter %PIN% into the app to verify.\"}" --data-urlencode "service=sms"
{ "app_key":"XXXXXXXX", "secret_key":"YYYYYY", "name":[ "app" ], "type":"MOBILE", "service":"SMS", "sender_id":"SENDER", "custom_message":{ "en":"Enter %PIN% into the app to verify." } }
List an App
Request
GET /apps/XXXXXXXX HTTP/1.1
Host: https://api.ringcaptcha.com
Content-Type: application/x-www-url-encoded; charset=utf-8
Parameters
Name | Description |
---|---|
api_key | Your API key |
app_key | Application Key for the app you want to list |
Response
Status: 200 OK
{ "app_key":"XXXXXXXX", "secret_key":"YYYYYYY", "name":[ "domain.com" ], "type":"WEBSITE", "service":"SMS", "sender_id":"sender", "custom_message":{ "en":"Enter %PIN% into the app to verify." } }
Example:
curl -X GET https://api.ringcaptcha.com/apps/{{ app_key }}?api_key={{ api_key }}
{ "app_key":"XXXXXXXX", "secret_key":"YYYYYY", "name":[ "app" ], "type":"MOBILE", "service":"SMS", "sender_id":"SENDER", "custom_message":{ "en":"Enter %PIN% into the app to verify." }, "geolocation":true, "unicode_support":false, "white_label":true }
Edit an App
Request
PUT /apps/XXXXXXXX HTTP/1.1
Host: https://api.ringcaptcha.com
Content-Type: application/x-www-url-encoded; charset=utf-8
Parameters
Name | Description |
---|---|
api_key | Your API key |
app_key | Application Key for the app you want to list |
Domain | Domain of any WEBSITE or ONBOARDING app where the widget will be placed |
Name | Mobile App name to identify on RingCaptcha and validate widgets with |
type | One of the following: WEBSITE, MOBILE, ONBOARDING, etc. |
sender_id | Sender Id that the SMS will be sent with whenever possible. Can be a number or alphanumeric up to 11 digits. |
custom_message | Custom SMS message template to use for verifications. You can include any locale that will be used here. Use %PIN% where you want us to input the PIN code |
service | Default service to use when nothing specified via API or widget. Values are SMS or VOICE. |
geolocation | Turn on/off geolocation of widgets |
whitelabel | true: Display ringcaptcha logo or false to hide it |
Response
Status: 200 OK
{ "app_key":"XXXXXXXX", "secret_key":"YYYYYYY", "name":[ "domain.com" ], "type":"WEBSITE", "service":"SMS", "sender_id":"sender", "custom_message":null }
Example:
curl -X PUT https://api.ringcaptcha.com/apps/{{ app_key }} --data-urlencode "api_key={{ api_key }}" --data-urlencode "custom_message={\"es\":\"Ingresa: %PIN% para completar el proceso.\",\"en\":\"Enter %PIN% into the app to verify.\"}"
{ "app_key":"XXXXXXXX", "secret_key":"YYYYYY", "name":[ "app" ], "type":"MOBILE", "service":"SMS", "sender_id":"SENDER", "custom_message":{ "es":"Ingresa: %PIN% para completar el proceso.", "en":"Enter %PIN% into the app to verify." }, "geolocation":true, "unicode_support":false, "white_label":true }
Delete an App
Request
DELETE /apps/XXXXXXXX HTTP/1.1
Host: https://api.ringcaptcha.com
Content-Type: application/x-www-url-encoded; charset=utf-8
Parameters
Name | Description |
---|---|
api_key | Your API key |
app_key | Application Key for the app you want to list |
Response
Status: 200 OK
{ "app_key":"XXXXXXXX", "secret_key":"YYYYYYY", "name":[ "domain.com" ], "type":"WEBSITE", "service":"SMS", "sender_id":"sender", "custom_message":{ "en":"Enter %PIN% into the app to verify." } }
Example:
curl -X DELETE https://api.ringcaptcha.com/apps/{{ app_key }}?api_key={{ api_key }}
{ "app_key":"XXXXXXXX", "secret_key":"YYYYYY", "name":[ "app" ], "type":"MOBILE", "service":"SMS", "sender_id":"SENDER", "custom_message":{ "en":"Enter %PIN% into the app to verify." }, "geolocation":true, "unicode_support":false, "white_label":true }
Error Codes
Error Code | Description | Suggested Action |
---|---|---|
ERROR_INVALID_SECRET_KEY | Using incorrect keys or domain/application name | Retrieve correct keys and domain/application name from site for specified application |
ERROR_INVALID_APP_KEY | Using incorrect keys or domain/application name | Retrieve correct keys and domain/application name from site for specified application |
ERROR_INVALID_DOMAIN | Using incorrect keys or domain/application name | Retrieve correct keys and domain/application name from site for specified application |
ERROR_INVALID_API_KEY | Using incorrect keys or domain/application name | Retrieve correct keys and domain/application name from site for specified application |
ERROR_INTERNAL_SERVER_ERROR | Unknown error | Retry again |
ERROR_DIRECT_API_ACCESS_NOT_AVAILABLE | Trying to access an inactive feature or API incorrectly | Follow the docs on the features and API accordingly |
ERROR_WEB_ACCESS_NOT_AVAILABLE | Trying to access an inactive feature or API incorrectly | Follow the docs on the features and API accordingly |
ERROR_MOBILE_ACCESS_NOT_AVAILABLE | Trying to access an inactive feature or API incorrectly | Follow the docs on the features and API accordingly |
ERROR_INSTANT_VALIDATION_NOT_AVAILABLE | Trying to access an inactive feature or API incorrectly | Follow the docs on the features and API accordingly |
ERROR_SERVICE_NOT_AVAILABLE | Trying to access an inactive feature or API incorrectly | Follow the docs on the features and API accordingly |
ERROR_INVALID_SERVICE | Trying to access an inactive feature or API incorrectly | Follow the docs on the features and API accordingly |
ERROR_INVALID_NUMBER | Phone number is incorrect, either the area code is missing or it contains invalid numbers | Retry with a valid number |
ERROR_WAIT_TO_RETRY | Retrying more often than “retry_in” field allows | Wait “retry_in” seconds before trying again |
ERROR_MAX_ATTEMPTS_REACHED | Retrying more times with the same active token or more frequently than expected | Complete verification process successfully or wait until token expires |
ERROR_MAX_VALIDATIONS_REACHED | Retrying more times with the same active token or more frequently than expected | Wait until token expires |
ERROR_INVALID_SESSION | Token is incorrect or has already expired/been verified | Request a new token if available |
ERROR_INVALID_PIN_CODE | PIN code is incorrect | Retry with the correct PIN code |