Important Notes
Every document post SHOULD include this header
Authorization: basic {base64 auth key}
Serialization formats supported:
json = Javascript Object Notation
Verification Request
Generate and send a PIN to your user. You use the verification_id in the response for the Verification_Check.
Request Parameters
| Post Body Fields | Description |
| from
( required ) |
String;
This is the VirtualShortCode provided by RT |
| to
( required ) |
String;
This is the MOBILE NUMBER of the user that requests for a PIN. *Mobile number must be in the following format:
|
| usagetype
( required ) |
String;
Application code for context and logging. This will be provided to you by RT. |
| template
( *optional ) |
String;
You may opt to include a customized message format to be sent to your users. By default the message would be sent as: {CODE} is your verification code. *note : {CODE} is the placeholder for the generated PIN Check message template setup section for more info. |
| expires_in
( *optional ) |
String;
You may opt to include an expiry period the generated pin. Format is in seconds. (300secs = 5 mins) By default the the period would be set into 300secs (5mins) |
Responses
| Response Status Reason | Output and Description |
| Success | HTTP/1.1 200 OK
{ } |
| Missing {Parameter}
[from,to,usagetype] |
HTTP/1.1 422 Unprocessable Entity Content-Type: application/json { “status”: false, “status_reason”: “Missing field: {parameter}” } |
| Empty {Parameter}
[from,to,usagetype] |
HTTP/1.1 422 Unprocessable Entity Content-Type: application/json { “status”: false, “status_reason”: “Empty field: {parameter}” } |
| Invalid expires_in value | HTTP/1.1 403 Forbidden Content-Type: application/json { “status”: false “status_reason”: “Invalid field value: expires_in” } |
| No Authorization Header | HTTP/1.1 400 Bad Request Content-Type: application/json { “status”: false, “status_reason”: “Authorization Header missing” } |
| No Request Body | HTTP/1.1 400 Bad Request Content-Type: application/json { “status”: false, “status_reason”: “Request Body missing” } |
Verification Check
Confirm that the PIN you received from your user matches the one sent by RisingTide as a result of your Verification Request.
Request Parameters
| Post Body Fields | Description |
| verification_id
( required ) |
String;
This is the response parameter from the Verification-Request. This will be used to match the pin in our database. |
| pin
( required ) |
String;
The provided PIN by the user. |
Response
| Response Status Reason | Output and Description |
| Success | HTTP/1.1 200 OK
{ } |
| Missing {Parameter}
[verification_id, pin] |
HTTP/1.1 422 Unprocessable Entity Content-Type: application/json { “status”: false, “status_reason”: “Missing field: {parameter}'” } |
| Empty {Parameter}
[verification_id, pin] |
HTTP/1.1 422 Unprocessable Entity Content-Type: application/json { “status”: false, “status_reason”: “Empty field: {parameter}” } |
| Expired PIN | HTTP/1.1 403 Forbidden Content-Type: application/json { “status”: false “status_reason”: “Expired pin” } |
| Invalid PIN | HTTP/1.1 403 Forbidden Content-Type: application/json { “status”: false “status_reason”: “Invalid pin” } |
| Invalid Verification ID | HTTP/1.1 403 Forbidden Content-Type: application/json { “status”: false, “status_reason”: “Invalid verification_id” } |
| No Authorization Header | HTTP/1.1 400 Bad Request Content-Type: application/json { “status”: false, “status_reason”: “Authorization Header missing” } |
| No Request Body | HTTP/1.1 400 Bad Request Content-Type: application/json { “status”: false, “status_reason”: “Request Body missing” } |
Message template setup
The API has the functionality to customize the message containing the PIN to be sent to your users. By default the message would be sent as: {CODE} is your verification code. “{CODE}” is the placeholder for the generated PIN to be sent to your users. Below is example message templates and its output.
Template:
Hi! This is your PIN for xyz.corp account activation: {CODE}
Output:
Hi! This is your PIN for xyz.corp account activation: 243756
