Phone Check API

Objective

The Phone Check API retrieves the basic details associated with a user's phone number including the first name, the last name and the date of birth.

Input	Output
The phone number of the user.	The response consists of the registered user's: First name Middle name Last name Date of birth

API URL

https://zaf.thomas.hyperverge.co/v1/getNameFromPhone

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format, and you should upload all images and files as form-data through a POST request.

Authentication

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

API Request Details

Method - POST

Headers

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	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 fields required for the API's request body.

Parameter	Mandatory or Optional	Description
number	Mandatory	The user's phone number. Caution The phone number should always start with zero(0).

Sample Request

The following code shows a standard curl request for the API.

curl --location --request POST 'https://zaf.thomas.hyperverge.co/v1/getNameFromPhone' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "number": "<Enter_the_phone_number>"
}'

Success Response Sample

The following is a sample of a success response from the API.

Success Response

{
  "statusCode": 200,
  "status": "success",
  "result": {
    "data": {
      "surname": "<Last_Name_of_the_User>",
      "firstName": "<First_Name_of_the_User>",
      "middlename": "<Middle_Name_of_the_User>",
      "phoneNumber": "<Phone_Number>",
      "dateOfBirth": "<YYY-MM-DD>"
    }
  },
  "metaData": {
    "requestId": "fa4e60e2-855c-4cc0-b4d6-f2ba385b876c"
  }
}

Success Response Details

The following table provides the details of the fields in a success response.

Parameter	Type	Description
phoneNumber	string	The phone number in the request used for retrieving the registered user's information.
surname	string	The last name of the registered user.
firstName	string	The first name of the registered user.
middlename	string	The middle name of the registered user.
dateOfBirth	string	The date of birth of the registered user in the YYYY-MM-DD format.

Error Response Sample

The following are some sample error responses from the API.

Invalid Phone Number

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

Invalid Input Pattern

{
  "statusCode": 400,
  "status": "failure",
  "message": "This value does not match the required pattern.",
  "metaData": {
      "requestId": "16cdd5f8-91eb-4ea8-a437-0d1517d13eea"
  }
}

Failure and Error Response Details

A failure or error response from the module contains a failure status, with a relevant status code and error message. The following table lists all error responses.

Status Code	Error Message	Error Description
400	Missing required request parameters.	The request has some mandatory parameters missing. Please check if the request has the number parameter.
400	Invalid input	The phone number in the request does not match the required pattern
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values.
403	Access Denied	Please contact the HyperVerge team for resolution.
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution.