Mobile Lookup API

The following document highlights details of the Mobile Lookup API.

API Description

Objective

The Mobile Lookup API verifies if a mobile number has registered accounts on various digital platforms and services. It can detect account presence on platforms like Amazon, Instagram, Facebook, Twitter, WhatsApp, Flipkart, Paytm, GitHub, and Apple's ecosystem services (iCloud, App Store, and other Apple ID-linked services). This verification helps establish a user's digital footprint across multiple online services.

Input	Output
The user's Country code and their Mobile number	Account detection status for each platform, indicating whether an account exists or not. Includes additional details like business status and profile information for WhatsApp

API URL

https://ind-thomas.hyperverge.co/v1/mobileLookup

API Endpoint

mobileLookup

Overview

The Mobile Lookup API is RESTful and uses standard HTTP verbs and status codes. The requests are in JSON format and responses are in JSON format.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

Parameter	Mandatory or Optional	Description	Allowed Values
Content-Type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table provides the details of the parameters required for the Mobile Lookup API's request body:

Parameter	Mandatory or Optional	Description
`countryCode`	Mandatory	The country code for the mobile number
`mobile`	Mandatory	The 10-digit valid mobile number of the user

Request

The following code snippet demonstrates a standard curl request for the Mobile Lookup API:

curl --location 'https://ind-thomas.hyperverge.co/v1/mobileLookup' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "countryCode": "<Enter_the_Country_Code>",
    "mobile": "<Enter_the_Mobile_Number>"
}'

Success Response

The following code snippet demonstrates a success response from the Mobile Lookup API:

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "status": "success",
        "message": "Detection Completed",
        "result": {
            "apple": {
                "registered": false,
                "message": "Account Not Detected"
            },
            "amazon": {
                "registered": true,
                "message": "Account Detected"
            },
            "instagram": {
                "registered": false,
                "message": "Account Not Detected"
            },
            "facebook": {
                "registered": true,
                "message": "Account Detected"
            },
            "twitter": {
                "registered": true,
                "message": "Account Detected"
            },
            "whatsapp": {
                "registered": true,
                "message": "Account Detected",
                "is_business": false,
                "business_name": "",
                "profile_picture": "",
                "whatsapp_status": ""
            },
            "flipkart": {
                "registered": true,
                "message": "Account Detected"
            },
            "paytm": {
                "registered": true,
                "message": "Account Detected"
            },
            "github": null
        }
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Success Response Details

The following table outlines the details of the success response from the API:

Parameter	Type	Description
status	string	The status of the detection request
message	string	The message describing the detection result
apple.registered	boolean	The flag indicating if an Apple account exists
apple.message	string	The message indicating if the Apple account is detected or not
amazon.registered	boolean	The flag indicating if an Amazon account exists
amazon.message	string	The message indicating if the Amazon account is detected or not
instagram.registered	boolean	The flag indicating if an Instagram account exists
instagram.message	string	The message indicating if the Instagram account is detected or not
facebook.registered	boolean	The flag indicating if a Facebook account exists
facebook.message	string	The message indicating if the Facebook account is detected or not
twitter.registered	boolean	The flag indicating if a Twitter account exists
twitter.message	string	The message indicating if the Twitter account is detected or not
whatsapp.registered	boolean	The flag indicating if a WhatsApp account exists
whatsapp.message	string	The message indicating if the WhatsApp account is detected or not
whatsapp.is_business	boolean	The flag indicating if the WhatsApp account is a business account
whatsapp.business_name	string	The name of the business if it is a business account
whatsapp.profile_picture	string	The profile picture URL if available
whatsapp.whatsapp_status	string	The WhatsApp status message if available
flipkart.registered	boolean	The flag indicating if a Flipkart account exists
flipkart.message	string	The message indicating if the Flipkart account is detected or not
paytm.registered	boolean	The flag indicating if a Paytm account exists
paytm.message	string	The message indicating if the Paytm account is detected or not
github.registered	boolean	The flag indicating if a GitHub account exists
github.message	string	The message indicating if the GitHub account is detected or not

Error Responses

The following are some error responses from the API:

Invalid Country Code
Invalid Mobile Number
Mobile Number Length Error

{
    "status": "failure",
    "statusCode": 400,
    "error": "Please provide valid country code",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

{
    "status": "failure",
    "statusCode": 400,
    "error": "Please provide valid mobile number",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

{
    "message": "Input Validation Error: does not meet minimum length of 10",
    "statusCode": 400,
    "status": "failure"
}

Missing/Invalid Credentials
Internal Server Error

{
    "status": "failure",
    "statusCode": 401,
    "message": "Missing/Invalid credentials"
}

{
    "status": "failure",
    "statusCode": 500,
    "message": "Internal server error"
}

Error Response Details

The following are some error responses from the API:

Status Code	Error Message	Description
400	Please provide valid country code	The request contains an invalid country code in the request body
400	Please provide valid mobile number	The request contains an invalid mobile number in the request body
400	Input Validation Error: does not meet minimum length of 10	The mobile number is empty or has less than 10 digits
401	Missing/Invalid credentials	The request is either missing the mandatory `appId` and `appKey` combination or has invalid values
500	Internal server error	An internal server error occurred during processing

API Description​

Objective​

API URL​

API Endpoint​

Overview​

Authentication​

Inputs​

Request​

Success Response​

Success Response Details​

Error Responses​

Error Response Details​