Get Started in less than a minute

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