Mobile Number Verification Using Telecom Data API

FETCH VERIFIED TELECOM USER DATA USING MOBILE NUMBER

Introduction

Accessing verified user information for non main-stream users and masses have always been a challenge primarily because of their lower technology exposure and is one of the key barriers for their financial inclusion. By simply using the mobile number and the OTP based consent, this API helps to get the user information using verified telecom network data. This data can be used for auto-filling the forms which enhances the end user digital experience by reducing the information that the user needs to fill manually.

Get Free Trial

Create a free account Or “Talk to Us” for price information and other queries.

Talk to us Create free account

API Details

Step 1. Generate OTP

Type	URL
Post	`https://api.attestr.com`/api/{version}/public/checkx/mobile-telecom/otp

Input and Output Definitions

Request Body Parameters

Key	Type	Description	Required	Min Version	Max Version
number	String	10 digit mobile number without leading zero	Required	v1

Request Header Parameters

Type	Name	Value / Description	Optional	Min Version	Max Version
String	Content-Type	application/json	Required	v1
String	Authorization	Basic `{authToken}`	Required	v1

If you do not have the authentication token, please refer to Register App to generate one.

Sample Request

Generate OTP Sample
    
 
{  "number": "8888xxxx34"}
Copy

Response

Key	Type	Description	Min Version
valid	Boolean	Flag indicating if the OTP was generated successfully by the telecom network provider	v1
status	String	Status code describing the outcome of the operation. Possible values are SUCCESS, CARRIER__UNKNOWN,_ CARRIER__UNSUPPORTED,_ INVALID__TYPE,_ INVALID_NUMBER	v1
_id	String	Unique request Id to be used for validating the OTP later	v1
number	String	Unique human readable request number.	v1
data	Object	The generate OTP operation first validates the input mobile number for correctness and fetching the telecom provider information. The information so validated is returned in the data field. For more details on output of this field, refer to Phone Validation API	v1
metadata	Object	The telecom specific metadata which is relevant for the next set of APIs. Refer to the Metadata object definition below for details.	v1
mnp	Object	Mobile number portability information if the number was ported to a new supported carrier. Check MNP object below.	v1

Metadata Object

Key	Type	Description	Min Version
otpLength	Number	Different telecom providers use different length of the one time password. This returns the OTP length supported for the input mobile number.	v1
maxVerifyAttempts	Number	Maximum number of wrong OTP attempts before the request is discarded.	v1
maxResendAttempts	Number	Maximum number of resend OTP attempts before the request is discarded.	v1
expiry	Number	Number of milliseconds before the generated OTP expires	v1
resendAfter	Number	Number of milliseconds to wait for initiating a resend request	v1

MNP Object

Key	Type	Description	Min Value	Max Value
ported	Boolean	Flag indicating if the mobile number was ported	v1
portedProvider	String	Provider code as supported by Attestr platform. Possible values are AIRTEL, JIO and VI	v1

Sample Output

Sample response for the different cases. Toggle the tabs in the code block below for all possible scenarios.

Success Scenario
Invalid Type
Unsupported Telecom Provider
Unknown telecom provider
Invalid Number
    
 
{  "valid": true,  "status":"SUCCESS",  "_id": "AR02JE2ykCwseGRxzk",  "number": "3893-406361-7362",  "data": {    "valid": true,    "type": "MOBILE",    "localF": "08897565318",    "intlF": "+918897565318",    "prefix": "+91",    "code": "IN",    "country": "India (Republic of)",    "area": "Andhra Pradesh",    "carrier": "Bharat Sanchar Nigam Ltd (BSNL)"  },  "metadata": {    "otpLength": 4,    "maxVerifyAttempts": 2,    "maxResendAttempts": 1,    "expiry": 900000,    "resendAfter": 60000  },  "mnp": {    "ported": true,    "portedProvider": "AIRTEL"  }}
Copy

Error Response

Parameter	Type	Description
code	Number	Unique error codes for different errors. Always available.
message	String	Error message describing the error. Always Available.
details	String	Detail error message. Available only for certain types of errors.

Error Codes

HTTP Status	Error Code	Error Message
400	4001	Malformed data or missing required parameter values
400	4005	Operation could not be performed due to low credits balance
401	4016	Invalid client authorization
403	4031	Unauthorized access
403	4035	Requested service is not provisioned for your account
403	4039	Client's IP address is not whitelisted
403	4035	Requested service is not provisioned for your account
429	4291	Maximum account rate limit exceeded
429	4292	Maximum API rate limit exceeded
429	4293	Maximum account daily limit exceeded
429	4294	Maximum API daily limit exceeded
500	5001	Request could not be processed
504	5041	Telecom portal gateway timeout

Sample Error Response
    
 
{  "code": 4001,  "message": "Malformed data or missing required parameter values"}
Copy

Step 2. Verify OTP

Type	URL
Post	`https://api.attestr.com`/api/{version}/public/checkx/mobile-telecom/verify

Input and Output Definitions

Request Body Parameters

Key	Type	Description	Required	Min Version	Max Version
req	String	Unique request Id generated in the previous step	Required	v1
otp	String	OTP as generated by the telecom provider	Required	v1

Request Header Parameters

Type	Name	Value / Description	Optional	Min Version	Max Version
String	Content-Type	application/json	Required	v1
String	Authorization	Basic `{authToken}`	Required	v1

Sample Request

Verify OTP
    
 
{  "req": "AR02JE2ykCwseGRxzk",  "otp": "2275"}
Copy

Response

Key	Type	Description	Min Version	Max Version
valid	Boolean	Flag indicating if the OTP was verified successfully	v1
status	String	Status code indicating the outcome of the operation.	v1

Sample Responses

SUCCESS
OTP_LENGTH_MISMATCH
MAX_ATTEMPTS_EXCEEDED
REQUEST_EXPIRED
INVALID_REQUEST
INVALID_OTP
    
 
{  "valid": true,  "status": "SUCCESS"}
Copy

Error Response

Parameter	Type	Description
code	Number	Unique error codes for different errors. Always available.
message	String	Error message describing the error. Always Available.
details	String	Detail error message. Available only for certain types of errors.

Error Codes

HTTP Status	Error Code	Error Message
400	4001	Malformed data or missing required parameter values
400	4005	Operation could not be performed due to low credits balance
400	40015	Session expired
401	4016	Invalid client authorization
403	4031	Unauthorized access
403	4035	Requested service is not provisioned for your account
403	4039	Client's IP address is not whitelisted
403	4035	Requested service is not provisioned for your account
429	4291	Maximum account rate limit exceeded
429	4292	Maximum API rate limit exceeded
429	4293	Maximum account daily limit exceeded
429	4294	Maximum API daily limit exceeded
500	5001	Request could not be processed
504	5041	Telecom portal gateway timeout

Sample Error Response

Sample Error
    
 
{  "code": 4001,  "message": "Malformed data or missing required parameter values"}
Copy

Step 3. Fetch Verified Data

Type	URL
Post	`https://api.attestr.com`/api/{version}/public/checkx/mobile-telecom/fetch

Input And Output Definitions

Request Body Parameters

Key	Type	Description	Min Version	Max Version
req	String	Unique request Id as generated in step 1.	v1

Request Header Parameters

Type	Name	Value / Description	Optional	Min Version	Max Version
String	Content-Type	application/json	Required	v1
String	Authorization	Basic `{authToken}`	Required	v1

Sample Request

Sample Request
    
 
{  "req": "AR02JE2ykCwseGRxzk"}
Copy

Response

Key	Type	Description	Min Version
valid	Boolean	Boolean flag indicating if the data fetch was successful	v1
status	String	Status code for the operation	v1
name	String	Full name of the user as registered with the telecom company. Available for all operators.	v1
customerId	String	Customer Id as registered with the telecom company. Not available for a few cases.	v1
dob	String	Date of birth if available. Available for few operators only.	v1
type	String	Service type indicating prepaid, postpaid etc.	v1
activated	String	Date of activation if available. Date can be in different formats as supported by the telecom operator	v1
active	Boolean	Boolean flag indicating if the provided number is active / has any active plans.	v1
address	Array[String]	List of addresses as registered	v1
alternateContact	Array[String]	List of alternate contact numbers if any.	v1
email	String	Email address if available	v1

Sample Response

SUCCESS
INVALID_REQUEST
    
{  "valid": true,  "name": "GITANJALI RAHEJA",  "customerId": "1216636160",  "dob": null,  "type": "POSTPAID",  "activated": "11/Oct/15",  "active": true,  "address": [    "8-2-293/k/57 Plot No 57 Flat No 101 Saketh Residency Phase 3 Kamalapuri Colony In Srinagar Colony,HyderabadNear Green Brawachi Hotel Hyderabad Telangana 500073 India"  ],  "alternateContact": [    "9985XXXX58"  ],  "email": "gitanjali.x.raheja@gmail.com"}
Copy

Error Response

Parameter	Type	Description
code	Number	Unique error codes for different errors. Always available.
message	String	Error message describing the error. Always Available.
details	String	Detail error message. Available only for certain types of errors.

Error Codes

HTTP Status	Error Code	Error Message
400	4001	Malformed data or missing required parameter values
400	4005	Operation could not be performed due to low credits balance
401	4016	Invalid client authorization
403	4031	Unauthorized access
403	4035	Requested service is not provisioned for your account
403	4039	Client's IP address is not whitelisted
403	4035	Requested service is not provisioned for your account
429	4291	Maximum account rate limit exceeded
429	4292	Maximum API rate limit exceeded
429	4293	Maximum account daily limit exceeded
429	4294	Maximum API daily limit exceeded
500	5001	Request could not be processed
504	5041	Telecom portal gateway timeout

Optional Step 4. Re-send OTP

Type	URL
Post	`https://api.attestr.com`/api/{version}/public/checkx/mobile-telecom/resend

Input And Output Definitions

Request Body Parameters

Key	Type	Description	Min Version	Max Version
req	String	Unique request Id as generated in step 1.	v1

Request Header Parameters

Type	Name	Value / Description	Optional	Min Version	Max Version
String	Content-Type	application/json	Required	v1
String	Authorization	Basic `{authToken}`	Required	v1

Sample Request

Sample Request
    
 
{  "req": "AR02JE2ykCwseGRxzk"}
Copy

Response

Key	Type	Description	Min Version	Max Version
valid	Boolean	Boolean flag indicating if the data fetch was successful	v1
status	String	Status code for the operation	v1

Sample Response

Success
INVAID_REQUEST
MAX_ATTEMPTS_EXCEEDED
REQUEST_WAIT
REQUEST_EXPIRED
    
 
{  "valid": true,  "status":"SUCCESS"}
Copy

Error Response

Parameter	Type	Description
code	Number	Unique error codes for different errors. Always available.
message	String	Error message describing the error. Always Available.
details	String	Detail error message. Available only for certain types of errors.

Error Codes

HTTP Status	Error Code	Error Message
400	4001	Malformed data or missing required parameter values
400	4005	Operation could not be performed due to low credits balance
400	40014	Maximum attempts exceeded. Please try after sometime.
401	4016	Invalid client authorization
403	4031	Unauthorized access
403	4035	Requested service is not provisioned for your account
403	4039	Client's IP address is not whitelisted
403	4035	Requested service is not provisioned for your account
429	4291	Maximum account rate limit exceeded
429	4292	Maximum API rate limit exceeded
429	4293	Maximum account daily limit exceeded
429	4294	Maximum API daily limit exceeded
500	5001	Request could not be processed
504	5041	Telecom portal gateway timeout

Telecom Network Coverage

This products currently supports Airtel, Vodafone Idea and Jio subscribers only. These three together, roughly account for about 91% of the Indian mobile users population (Data source wikipedia).

BSNL and MTNL are currently not supported and may be added in future.

Get Free Trial

Create a free account Or “Talk to Us” for price information and other queries.

Talk to us Create free account

Last updated on