Two-Factor Authentication REST API

Response

Home » API » Two-Factor Authentication REST API » Response

Response

Request Code – Response Description

Once the Request code API processes the request, it will generate a response. An example of such a response:

{
  "api_job_id": "0c6ccf37-dd15-49ff-a12f-ffad8f2655a6",
  "result_info": {
    "status_code": 0,
    "description": "Success"
  },
  "result": {
    "message_id": "14466445287300014003"
  }
}

 

All responses will come with the appropriate HTTP status code. Also an extra status_code is used to show the resolution of the request. Only when a request is successful the code will be 0 otherwise, if an error occurs it can be identified with its specific code.

 

Request Code – Outer Response

Key Type Optional Description
api_job_id String N A unique identifier generated per request. This can be used to track a specific request.
result_info ResultInfo N Holds details about the resolution of the request. Always available.
result Result Y If available, holds the result to the request.

 

Request Code – Result_info item

Key Type Optional Description
status_code Integer N Holds a an integer value of the response status. i.e.:

0 = success, -50 = not authorized (Described in Section Error/Success Messages)
description String N Holds a text description of the response status.

 

Request Code – Result item

Key Type Optional Description
message_id String N The unique ID for the SMS message sent.

 

Validate Code – Response Description

Once the Validate code API processes the request, it will generate a response. An example of such a response:

{
  "api_job_id": "0c6ccf37-dd15-49ff-a12f-ffad8f2655a6"",
  "result_info": {
    "status_code": 0,
    "description": "Valid"
  }
}

All responses will come with the appropriate code. These are described in Section Error/Success Messages.

 

Validate Code – Outer Response

Key Type Optional Description
api_job_id String N A unique identifier generated per request. This can be used to track a specific request.
result_info Integer N Holds details about the resolution of the request. Always available.

 

Validate Code – Result_info item

Key Type Optional Description
status_code Integer N Holds a an integer value of the response status. i.e.:

0 = success, -50 = not authorized (Described in Section Error/Success Messages)
description String N Holds a text description of the response status.

 

Error/Success Messages

When responding, the REST API will reply with an HTTP status, response code and a self explanatory message.

The following are the currently available messages.

Response Message Response Code HTTP Status Description
Your authorization token is invalid. -50 401 When the Authorization token found in the header is not valid.
Authorization token not provided. -51 401 When the Authorization token is missing from the header.
Client ref provided already exists. Please provide a different one. -52 422 When requesting a new code and the client ref provided has already been used with the Authorization token provided.
Invalid -53 200 When the code being validated has expired.
Declined -54 422 When the code being validated cannot be found. i.e. it was incorrectly entered by the client.
The code for the provided client ref. and authorization token, was not found. -55 422 The code provided does not match the authorization token and client_ref
No code was provided. -56 422 The code was not provided in request.
Code length too short. -57 422 When the code_length provided is smaller than the minimum.
Code length too long. -58 422 When the code_length provided is bigger than the maximum.
Phone number format is incorrect. -59 422 When format of the phone_number is not a valid mobile number.
No phone number provided in request -60 422 When phone number is missing in the request body.
Callback URL is invalid -61 422 When a non valid URL is provided as callback_url.
No client ref provided in request -62 422 When no client_ref is provided in the request body.
Sender ID is too long. Maximum numeric is 15 & maximum alphanumeric is 11. -63 422 When the sender_id provided in request body is bigger than 15 characters if numeric or is bigger than 11 characters if alphanumeric.
System error – Request data provided was invalid. -64 400 When the request data is in a malformed manner or is not recognizable by the endpoint.
Something went wrong. Make sure data provided is valid and please try again. -65 400 When an error occurred in the system’s back end due to system failure or due to some incorrect data provided.
List of allowed IPs contains one or more invalid IP addresses. -66 400 When the list of IPs available with the authorization token has one or more IPs malformed.
The request IP is not in your list of allowed IP addresses. -67 400 When request IP does not match any one form the list of allowed IP addresses available for the authorization token.
Message template must contain placeholder {#TFA_CODE}. -68 422 When the message template is specified however it does not contain the required placeholder.
Message template exceeds the length of one SMS. -69 422 When the total length of the message (message template + code) is longer than 1 SMS.
Success 0 201 When the request for a new code has been completed successfully.
Valid 0 200 When the code is valid.

 

Description of the HTTP statuses

HTTP Status Code Description
200 All OK
201 Created OK.
400 Bad Request – The request is invalid and was not understood by the API.
401 Unauthorized – Header “Authorization” missing, invalid, or revoked; and/or, your host IP is not in the authorized IPs list.
403 The request contains invalid or illegal values.
404 Not Found – The endpoint on which the request was sent to, does not exist, or does not implement the API requested.
405 Method Not Allowed – If the endpoint received a request using an HTTP method (ex. GET instead of POST) that is not allowed by that endpoint.
413 Request entity was too large. Maximum size of X bytes allowed.
415 Unsupported Media Type – If the request was in a content-type not supported by the endpoint (ex. text/plain instead of application/json).
422 Unprocessable Entity  – If a validation error occurs on the endpoint.
429 Too many requests (Throttling)
500 Internal Server Error

 

Get Started