Mobile phone number serves as the ultimate user identity in digital universe. Digital applications whether on web or on mobile; verify mobile numbers of their users to ensure their authenticity. To address this growing need, U2opia has developed a reliable, quick and cost-effective mobile number verification service called Verify Now.
This document will give you an overview of APIs that can be used by website and mobile app developers to integrate Verify Now. These APIs will support accurate identification of end-users’ mobile numbers.
In order to align your applications with Verify Now interface, follow these steps:
1. Register as a User on Verify Now website. If you haven’t already registered, you can do so by selecting the “Sign Up” button on Verify Now site. Once registered, you will receive a unique “Customer ID” and“ App Key”.
2. Take note of the following items as they will be passed frequently during API calls:
3. Learn how to make Verify Now API calls. Once you have registered on the website, you are allowed up to ten free trial verifications.
There are simply two API calls to effect the aforementioned verification workflows:
i) Number Verification through SMS: Once you provide the number to be verified , Verify Now will send an OTP (one time password) via SMS. A verification ID will also be sent for future reference. Some requests might be rejected outright (e.g. invalid numbers or parameters).
ii) Verification Update Status: Look up a verification request in order to know its status (In progress, Successful, Failed or Expired) and many other attributes.
User mobile number verification cycle gets started with (i) & (ii). The complete time-interval of verification cycle is 180 seconds.
Once a verification cycle gets completed (either successful or Failure), the application can again request for number verification of same user. It will be taken care as new verification cycle.
All Verify Now requests must be submitted to the base URL. Responses will be made in JSON format.
Each API is covered in great detail below in the section "API Description".
Key Parameters:
1. Customer ID: Unique string that identifies each user with Verify Now.
2. appKey: Secret key specific to each app registered by Verify Now user.
3. msisdn: Mobile number of the end-user for which verification request is made.
4. verificationID: Unique ID generated for each verification request, right at the beginning of verification cycle.
5. smsCLI: Unique string that defines the service and the service provider. smsCLI denotes the sender that sends the SMS.
6. timeout: Time interval after which app can request for SMS delivery status.
7. assignedDID: DID number along with country code assigned to MSISDN that initiated a verification request.
8. code: OTP entered by end-user in application or website.
1. NUMBER VERIFICATION THROUGH SMS: This API may serve to initiate end-user verification request. This API enables sending of One-Time Password (OTP) via SMS on end users' mobile number.
This API entertains request over HTTP Post Method. GET request is discarded by Foneverify server. Several validations are incorporated at Foneverify server to sanitize upcoming parameters. Responses will be made in JSON format.
REQUEST
HEADERS
QUERY PARAMETERS
After submitting the request, you will receive a HTTP response. HTTP response will contain a JSON object. Response will contain the following keys and values:
If response is a valid failure or other error; error message INVALID_CUSTOMER_ID will be sent.
SAMPLE SUCCESSFUL RESPONSE
HTTP/1.1
Status: 200 OK
Content-Type: application/json; charset=utf-8
Content-Encoding: gzip
{"verificationId" :xxxxxxx, "mobileNumber": "9845678291, "smsCLI" :"VERIFY",, “responseCode” : 200, “timeout”:”90000”,“transactionId”:”xxxxx”}
Please be informed that initial request will remain active for 180 seconds to verify end-user msisdn by invoking update api with otp entered by user. Post 180 seconds, verification will get expired.
2.VERIFICATION UPDATE STATUS API: Once the API received verificationId along with timeout, it can request for status update of verification cycle using update API.
REQUEST
Use cases get invoked while calling this API:
Case I:
Requesting update status with OTP entered by user over application within stipulated (180 sec) timeout interval for initial request.
Requesting update status with OTP entered by user over application after timeout interval provided in SMS initial request.
HEADER
QUERY PARAMETERS
RESPONSE
When OTP entered by end-user matches the one shared with him/her; within the stipulated time; response will contain the following keys and values:
If response is a validation failure or other error; error message INVALID_CUSTOMER_ID will be sent.
Case II:
When user hasn't entered provided OTP within time (180 seconds) expired.
User needs to resend OTP. If response is a validation failure or other error; error message INVALID_CUSTOMER_ID will be sent
Sample Successful Response
HTTP/1.1
STATUS: 200 OK
Content-Type: application/json; charset=utf-8
Content-Encoding: gzip
{"verificationId" :xxxxxxx, ”mobileNumber”:”9xxxxxxxxx”, “responseCode” : “200”}