Silent Mobile Verification

Resource

https://api.infobip.com/mi/verification/1/verify

Body Params

Property name Type Description
phoneNumber string Phone number (MSISDN) to verify. The number must be in international format (example: 41793026727).
callbackUrl string Your URL will be called when verification is complete. Must contain '{result}' and '{token}' placeholders in the query parameter to specify where will result and token values be inserted.
consentGranted boolean (false) Indicates whether you have consent from the phone number's owner to perform silent mobile verification. All requests that do not have this property set to "true" will be rejected.
returnUrl string A URL to which the device will be redirected to when verification is complete.
deviceIp string The IP address of the device that will be verified with the operator.
devicePort int Port of the device that will be verified with the operator. Can be used only when 'deviceIp' is also provided

Request Example 

					POST /mi/verification/1/verify
Host: api.infobip.com
Autorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
Accept: application/json

{
	"phoneNumber": "41793026727",
	"callbackUrl": "https://www.my_company.com/mi/verify/result?result={result}&token={token}",
	"consentGranted": true,
	"deviceIp": "170.16.10.10"
}

Response 

					{
    "status": "OK",
    "token": "697d3bff-03c3-434b-80ec-413ca18aa554"
}
					
				
					{
    "error": {
        "id": 202,
        "name": "EC_CONSENT_NOT_GRANTED",
        "description": "User consent not granted"
    },
    "status": "ERROR",
    "token": "56693a53-4174-4e81-8e9c-b8863a7ad827"
}
					
				
					{
    "status": "REDIRECT",
    "token": "6a31ccca-ceba-4998-a3b0-16ae5e182ab0",
    "deviceRedirectUrl": "https://api.infobip.com/mi/verification/1/complete?token=6a31ccca-ceba-4998-a3b0-16ae5e182ab0"
}

Authentication

For authentication, header details see [Security and Authorization] (https://dev.infobip.com/getting-started/security-and-authorization).

Response description:

Property name Type Description
error object Request error.
status string Request status.
deviceRedirectUrl string URL to perform a redirect to.
token string Request identifier.

 

Response status parameter description:

 

Status value Description
OK The request is successfully accepted and will be processed.
ERROR An error occurred while processing requests. Additional information is provided in the 'error' object.
REDIRECT The mobile device should be redirected to the URL provided in 'deviceRedirectUrl' in order to complete the verification.

REDIRECT response status explanation

If response status is ‘REDIRECT’ the response will contain ‘deviceRedirectUrl’ field. That means that end-user device should be redirected to that URL in order to complete verification process (e.g. ‘deviceIp’ is not set in the verification request, therefore end-user should be redirected to Infobip’s endpoint in order to discover device’s public IP address, or mobile network operator is using header enrichment verification method).

Device IP and device port

For certain silent mobile verification requests, mobile network operators require the user device’s public IP address and/or port information to be able to perform verification matching. Device’s IP address and/or port has to be collected while the user is connected to the internet using mobile network operator data connection (i.e. the user’s device is not connected to WiFi, not using tethered/shared connection, VPN connection, etc.). In case when mobile network operator verification process requires device’s public IP address and/or port, and that information is not already provided in your verification request, you’ll receive response with “REDIRECT” status, and user’s device has to be redirected to URL specified in “deviceRedirectUrl”, where we’ll try to collect devices public IP address and/or port in order to be able to complete the verification process.

Request example: 

  • JSON
GET https://api.infobip.com/mi/verification/1/complete?token=6a31ccca-ceba-4998-a3b0-16ae5e182ab0
Host: api.infobip.com
Content-Type: application/json
Accept: application/json

Redirect response example:

200 Success

  • JSON
{
    "token": "7b564f4b-0f92-4af6-b6ee-021f9bc439f6",
    "returnUrl": null
}

400 Failure

  • JSON
{
    "error": {
        "id": 201,
        "name": "EC_INVALID_TOKEN",
        "description": "Token is invalid or does not exist"
    },
    "status": "ERROR",
    "token": "56693a53-4174-4e81-8e9c-b8863a7ad827"
}

Return URL

Return URL will be set if you sent it in your first silent mobile verification request.

Verification Result

The verification result for silent mobile verification requests will be sent to the URL provided in the 'callbackUrl'. The 'callbackUrl' has to contain '{result}' and '{token}' placeholders which will be swapped for the actual result of the verification process and token, respectively. Token will match the token provided in the silent mobile verification response.

 

Final callback response:

  • JSON
GET /mi/verify/result?result=VALID&token=697d3bff-03c3-434b-80ec-413ca18aa554
Host: https://www.my_company.com
Content-Type: application/json

Final callback response with the error

  • JSON
GET /mi/verify/result?result=ERROR-202&token=56693a53-4174-4e81-8e9c-b8863a7ad827
Host: https://www.my_company.com
Content-Type: application/json
Query parameter Placeholder Description
result {result} Verification result. Value can be either: 'VALID', 'INVALID' or 'ERROR' (check error code table for more information).
token {token} Request identifier.

 

 

 
Callback 'result' value Description
VALID 'phoneNumber' and 'deviceIp'/'devicePort' are matched
INVALID 'phoneNumber' and 'deviceIp'/'devicePort' are not matched
ERROR An error occurred during the verification process, error code will be appended to the error result (e.g. 'ERROR-202' result means that error occurred and error code is '202')

 

  • End-user initiates an action on Application which triggers the Silent Mobile Verification process
  • Application sends the Silent Mobile Verification request to Infobip, filling in the mandatory information
  • Infobip evaluate requests parameters, generates token for the request, and returns a response with appropriate “status” parameter
  • If the response “status” parameter was “REDIRECT”, user’s mobile device has to be redirected to provided URL so that verification process can be completed (e.g. the device’s public IP address and/or port are required but not provided by Application, or the mobile network operator requires redirection to header enrichment endpoint).
  • Once all required data are collected, Infobip initiates Silent Mobile Verification request towards the corresponding mobile network operator
  • The mobile network operator responds with verification result
  • Infobip submits Silent Mobile Verification result to the Application, thus completing the verification process

NOTE:

The verification steps 4, 5 and 6 are conditional, depending on the mobile network operator verification process. E.g. if the mobile network operator requires devices public IP address and/or port, or if the mobile network operator is using header enrichment method, those steps would be required in order to complete the verification process.