Number Check API submit - nxtele/nxcloud-doc-en GitHub Wiki

Summary

Number Check Submission Interface

Request URL

http://api2.nxcloud.com/api/number/check

Request Method

Method: POST
Content-Type: application/json

Authentication Mechanism

Please refer to the following link for authentication rules: API Interface Calling Convention

Request Header

Parameter Name	Parameter Type	Required	Example	Parameter Description
accessKey	String	Yes	fme2na3kdi3ki	User identity identifier
ts	String	Yes	1655710885431	Timestamp of the current request (in milliseconds). The maximum time difference allowed between the client and the NXCLOUD server is 60 seconds.
bizType	String	Yes	1	[Business Type] Fixed value used to identify number check
action	String	Yes	numbercheck	Fixed value used to identify number check
sign	String	Yes	6e9506557d1f289501d333ee2c365826	API parameter signature, Signature Algorithm

Request Body

Parameter Name	Required	Type	Description
phone	Yes	string	Phone number to be checked, including country code, e.g., 852xxxxxxxxx, 8527xxxxxxx [Multiple numbers separated by commas; all numbers in the same batch must belong to the same country]
batchNo	No	string	Batch number that identifies different numbers in the same batch. If not provided, a 12-digit random code will be generated automatically. The length cannot exceed 64 characters.
checkLevel	No	integer	Check type. If not provided, the default is the Basic Version. 1: Basic Version; 4: Call Version; 5: HLR Version
drUrl	No	string	Callback URL for check results. If not provided, the callback URL configured for the corresponding appkey will be used. If the app is not configured with a callback URL, the check results will not be callbacked.
appkey	Yes	string	Application appkey

Request Example

{
    "phone": "234800001xxxxx",
    "batchNo": "20220901",
    "checkLevel": 1,
    "drUrl": "http://my.callback.url/test",
    "appkey": "a1b2c3d4"
}

Successful Response

{
    "msg": "success",
    "code": 0,
    "data": {
        "messageId": "301ef45b8de54d8aad95c5264c3756be",
        "batchNo":"20220901"
    }
}

Response Parameter Explanation

Parameter Name	Type	Description
data	json	Request result
messageId	string	Business ID that uniquely identifies the check task. The length should not exceed 64 characters.
batchNo	string	Batch number provided by the user or generated by the system
msg	string	Result description
code	integer	Result code

message = uuid[32 characters] or message = uuid[32 characters] + 6-digit random code The messageId returned in the request and the messageId returned in the receipt interface If there is only one number in a batch, the messageId returned in the request and the messageId returned in the receipt interface will be the same. If there are multiple numbers in a batch, the messageId returned in the request = uuid, and the messageId returned in the receipt interface = uuid-6-digit random code [connected by -]

Failed Response

{
    "msg": "Application not available or incorrect appkey",
    "code": 202,
    "data": {
        "messageId": "",
        "batchNo": ""
    }
}

Error Codes

code	msg
0	Success
201	Parameter error or empty
202	Application not available or incorrect appkey
203	Country operator information not recognized
204	Exception in customer deduction interface
205	No application pricing found
206	Exception in request check business interface
207	Invalid check type
210	Inconsistent customer information corresponding to the authentication mechanism and the customer information corresponding to the appkey
211	Insufficient customer balance
212	Batch number length cannot exceed 64 characters
288	Request failed
299	System error

Callback (Webhook)

After a successful request, NXCLOUD will queue the check and push the check result to the callback URL asynchronously. The callback URL can be specified through the submission API or configured uniformly on the platform. Please refer to the following link for the callback protocol:

Number Check Callback