Common Rules

All requests to API methods must be sent to https://api.verifire.io

All responses are returned in JSON format.

All responses include conforming HTTP status code. All successful requests have codes HTTP 20X. All failed requests have codes HTTP 4XX/5XX.

In case of failure all responses contain errorCode and errorReason fields which can help you to define the reason of an error. See the Errors section.

Client Authorization

Client gets access to service by adding "X-Authorization" header with token into each request. To get your access token, please contact support.

Authentication HTTP header will look something like this:

X-Authorization: edb6fc4d446445a4df3495db62dda54f:92f06456fc680249216313055c292f0a

API Sections

Verification Process

The process of verification consists of two steps. On the first step you request verification by providing us user phone number and desired verification method. As response you get a requestId to follow the verification process. As a second step you provide us with verification code (PIN) received from user.
There are three verification methods available:

Verifire API HTTP Methods

Methods

POST /v1/verify

Send verification code to phone number

Param Required Description
number Yes User phone number that needs to be verified in the E.164 format
method Yes Method that will be used for verification. One of: sms, voice, call.
codeLength No Length of code, that will be generated. The default value is 4 (min: 4, max: 6).
Invalid codeLength value will be altered to closest allowed value.
senderId No Alphanumeric string to specify the SenderID for SMS sent by Verifire (used only for sms verification method).
Max senderId length is 11 symbols. By default sender is Verifire.
Your custom senderId's must be validated by our support before usage.
checkAttemptsAllowed No Number of attempts which can be done to confirm code (using /verify/check). After this amount of the failed attempts, the request itself will be considered as failed. The default value is 3 (min: 1, max: 10)
codeExpiry No Request TTL. The amount of time (in seconds) for the request to be automatically considered as failed if there were no successful verification attempts (using /verify/check). Default value is 300 (min: 60, max: 900)
ip No Optionally you can pass user IP address for more accurate fraud prevention.
language No Optionally you can pass user language for voice and sms methods. Default is en. More info in languages table.

Success Response

HTTP 201 Created or HTTP 200 Ok

{
    "requestId": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
    

We allow only one request with the same number within 30 seconds. But if you repeat the same request, we won't treat it as error, but return already existing requestId. This is done to prevent situation when verification request was successfully created, but you were unable to get or parse response for some reason. So repeated request (within 30 seconds) will just return the result of your previous request.
In that case the only difference in responses is in HTTP code. Newly created request returns HTTP 201 Created, while repeated request returns HTTP 200 Ok.

Error Response

HTTP 4XX/5xx

{
    "errorCode": 11,
    "errorReason": "Invalid number"
}

POST /v1/verify/check

Verify users phone number by providing verification code

Param Required Description
requestId Yes requestId from /verify request
code Yes Verification code that was received by sms, call, or voice method
ip No Optionally you can pass user IP address for more accurate fraud prevention.

Success Response

HTTP 201 Created or HTTP 200 Ok

{
    "number": "+188001234567",
    "method": "call",
    "verifiedAt": 1500998757,
}

For the same reason as in /verify method, response HTTP codes are split. First successful check returns HTTP 201 Created, while repeated attempts with valid code returns HTTP 200 Ok. Be aware that number of allowed repeated requests with valid code is also limited.

Error Response

HTTP 4XX/5xx

{
    "errorCode": 21,
    "errorReason": "Invalid code"
}

POST /v1/verify/info

Retrieve information about verification providing its requestId

Param Required Description
requestId Yes requestId from /verify request

Success Response

HTTP 200 OK

{
    "status": "verified",
    "number": "+188001234567",
    "method": "call",
    "verificationRequestedAt": 1499186255,
    "statusUpdatedAt": 1499186257,
    "checkAttempts": 1
}

Error Response

HTTP 4XX/5xx

{
    "errorCode": 20,
    "errorReason": "Verification request not found"
}

Errors

errorCode HTTP code errorReason Description
1 HTTP 401 Authentication required Wrong authentication token was provided in request header.
2 HTTP 400 Inactive account Your account is inactive. Please contact support.
4 HTTP 429 Too many requests You provided to many requests in a short period of time. Max allowed number of requests is 30 per second.
5 HTTP 401 Inactive token Token you are currently using for request is inactive.
10 HTTP 400 Invalid request Your request was formed incorrectly. Please see the documentation for details.
11 HTTP 400 Invalid number The number you provided is invalid or malformed. We accept phone numbers in international format (E.164). Please see the documentation for details.
12 HTTP 400 Invalid verification method Verification method you requested is not allowed. Please see the documentation for details.
13 HTTP 400 Blocked number The provided number is blocked by our antifraud system. Verification is prohibited.
14 HTTP 400 Verification initiation failed We were unable to initiate verification for provided number using method you requested.
20 HTTP 404 Verification request not found The value passed as a requestId is invalid.
21 HTTP 400 Invalid code The value passed as a code do not match the required one. Verification failed.
22 HTTP 400 Verification request expired Verification request with requestId you are trying to check is expired. Verification failed.
23 HTTP 400 Too many check attempts Check attempts limit exceeded for current requestId. Verification failed.
24 HTTP 400 Request already processed You are trying to check the request that already has been processed (has status failed or verified). Use /verify/info to retrieve request information.
99 HTTP 500 Internal server error We were unable to handle your request. Please try again.

If you do not want to use full verification cycle, you can use the transport layer of our API to deliver your verification code to end user.

Verifire Transport API HTTP Methods

Methods

POST /v1/transport/sms

Send sms message to users phone number

Param Required Description
number Yes User phone number that must receive your message.
text Yes Text of the message you want to send.
senderId No Alphanumeric string to specify the SenderID for SMS sent by Verifire. Max senderId length is 11 symbols. By default sender is Verifire.
Your custom senderId's must be validated by our support before usage.

Success Response

HTTP 200 OK

{
    "requestId": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

Error Response

HTTP 4XX/5xx

{
    "errorCode": 11,
    "errorReason": "Invalid number"
}

POST /v1/transport/voice_code

Initiates a voice (PIN-2-speech) call to provided user number in which our robot will dictate passed code

Param Required Description
number Yes User phone number that must receive a voice call.
code Yes Numeric code to dictate to user. Code length must be between 4 and 6 digits.
language No Optionally you can pass user language. Default is en. More info in languages table.

Success Response

HTTP 200 OK

{
    "requestId": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

Error Response

HTTP 4XX/5xx

{
    "errorCode": 11,
    "errorReason": "Invalid number"
}

POST /v1/transport/call_code

Initiates a phone call to provided user number. Trailing digits in a phone number will match the provided code.

Param Required Description
number Yes User phone number that must receive a call.
code Yes Numeric code that will be added to Caller ID. Code length must be between 4 and 6 digits.

Success Response

HTTP 200 OK

{
    "requestId": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

Error Response

HTTP 4XX/5xx

{
    "errorCode": 11,
    "errorReason": "Invalid number"
}

Errors

errorCode HTTP code errorReason Description
1 HTTP 401 Authentication required Wrong authentication token was provided in request header.
2 HTTP 400 Inactive account Your account is inactive. Please contact support.
4 HTTP 429 Too many requests You provided to many requests in a short period of time. Max allowed number of requests is 30 per second.
5 HTTP 401 Inactive token Token you are currently using for request is inactive.
10 HTTP 400 Invalid request Your request was formed incorrectly. Please see the documentation for details.
JSON response will probably contain some additional info about the reason of error.
11 HTTP 400 Invalid number The number you provided is invalid or malformed. We accept phone numbers in international format (E.164). Please see the documentation for details.
13 HTTP 400 Blocked number The provided number is blocked by our antifraud system. Initiation is prohibited.
40 HTTP 400 Transport initiation failed We were unable to initiate transport method for provided number.
99 HTTP 500 Internal server error We were unable to handle your request. Please try again.

Languages

List of languages that are supported by our pin-2-speech robot.

Code Language
en English
fa Farsi
de German
es Spanish
fr French
it Italian
pt Portugal
ja Japanese
ru Russian
sv Swedish