Silent Network Auth Retrieve EVURL Result API Endpoint

POST https://api-sbox.dnlsrv.com/cigateway/id/v1/phoneIdResult

API that allows a customer to obtain the result of Silent Network Auth. Note that the result of Silent Network Auth is available for one hour from the time the URL was used to start the Silent Network Auth process.

When testing this flow, you have to first execute the Create An EVURL API request. Copy the EVURL in the results and paste it into your browser's URL field and press enter. Once the EVURL is invoked, you should be able to get a successful call on Retrieve EVURL Result.

If the Silent Network Auth process on the device is not complete when calling Retrieve EVURL Result, the API results will indicate this in the error object with the code 5016. In this case, the Retrieve EVURL Result endpoint call should be retried.

Body parameters

Param Name	Type	Description
merchantId	string	Required. Your merchant ID that will be provided to you during onboarding.
subMerchantId	string	Optional. Used by resellers, an ID that is assigned to the end customer.
correlationId	string	Required. A nonce used by the customer that is unique to this transaction.
associationKey	string	Required. A unique ID used at the start of the Silent Network Auth process for this user session.
match	object	Optional. JSON object that provides the parameters to be matched.Object must contain key value `consumerMdn` which is defined as the MSISDN of the user that you want to check, number must be provided in E.164 format. Example:`"match": {` `"consumerMdn": "+14085040458"` `}`

Headers

Header Name	Type	Description
Authorization	string	Required. The security key to use for Twilio APIs.NOTE: This may be different than your Twilio Account Auth Token - please confirm with your Sales Specialist.
`Content-Type`	string	Required. Media type sent in the request. Only application/json is supported.
Accept	string	Required. Media type for the response. Only application/json is supported.
RequestTime	date-time	Required. Current date time when request is sent.

Responses

Successful response and authentication

A results JSON object will be returned with the following values. phoneIdResult will indicate whether the phone number matches or not.

Value Name	Type	Description
correlationId	string	A nonce used by the customer that is unique to this transaction. This value is echoed back from the request, if it was provided.
referenceId	string	Twilio's unique transaction identifier.
phoneIdResult	object	Object that encapsulates the results of the Silent Network Auth verification. Contains key values `associationKey` and `matchScores`.`associationKey`: String that is either the correlationId included in the EVURL payload or if using phoneIdUrl, the correlationId in the request, during the authentication process. The value from the request is echoed back.`matchScores`: JSON object that indicates the match result of the input match parameters to those detected by Twilio during the authentication process. Object contains key value `mdnMatchScore`.`mdnMatchScore`: String that indicates whether the customer provided MDN and Twilio detected MDN match or not. This field will be returned only if consumerMdn is provided in the request in the match object. 10 = Match, 0 = Does Not Match.

Sample response

1HTTP/1.1 200 OK
2Content-Type: application/json
3
4{
5    "results": {
6        "correlationId": "ABC0881973286793",
7        "referenceId": "20210203234640M163C264030",
8        "phoneIdResult": {
9            "associationKey": "XYZ78907qwer97873",
10            "matchScores": {
11                "mdnMatchScore": "10"
12            }
13        }
14    }
15}

Successful response and failed authentication

A results JSON object will be returned with the following values. code and description provide more details on the failure and if the customer should fail over to another authentication method.

Value Name	Type	Description
phoneIdResult	object	Object that encapsulates the results of the Silent Network Auth verification. Contains key values `code`, `description`, and `associationKey`.`code`: Indicates the reason the authentication failed. Refer to Error Codes and Descriptions for a complete list.`description`: Additional information regarding the error condition. Sent only if error code is included in the response.`associationKey`: String that is either the correlationId included in the EVURL payload or if using phoneIdUrl, the correlationId in the request, during the authentication process. The value from the request is echoed back.
correlationId	string	A nonce used by the customer that is unique to this transaction. This value is echoed back from the request, if it was provided.
referenceId	string	Twilio's unique transaction identifier.

Sample response

1HTTP/1.1 200 OK
2Content-Type: application/json
3
4{
5    "results": {
6        "correlationId": "ABC0881973286793",
7        "referenceId": "20210203234640M163C264030",
8        "phoneIdResult": {
9            "code": "-30 ",
10            "description": "Unsupported Carrier",
11            "associationKey": "XYZ78907qwer97873"
12        }
13    }
14}

Failed response

An error JSON object will be returned with the following values. code and description provide more details on the failure.

Value Name	Type	Description
code	string	Indicates the reason the API call failed. Refer to Error Codes and Descriptions for a complete list.
description	string	Additional information regarding the error condition. Sent only if error code is included in the response.
correlationId	string	A nonce used by the customer that is unique to this transaction. This value is echoed back from the request, if it was provided.
referenceId	string	Twilio's unique transaction identifier.

Sample response

1HTTP/1.1 400 Bad Request
2Content-Type: application/json
3
4{
5    "error": {
6        "correlationId":"ABC0881973286793",
7        "referenceId":"20210203234640M163C264030",
8        "code":"-5003",
9        "description":"Required parameter missing"
10    }
11}

HTTP status codes

HTTP Status Code	Description
200	Successful invocation, but the response will depend on the success of the Silent Network Auth process.
400	Malformed request submitted.
500	Internal system error.

Retrieve EVURL Result Example

1// Installation
2// npm install api --save
3
4// Request
5const sdk = require('api')('@boku/v4.4.1#1b5wc11kl6dx748s');
6
7sdk.postV1Phoneidresult({
8  merchantId: '02200013919FB4',
9  subMerchantId: '00DF00000016',
10  correlationId: '984681AFDB698C67',
11  associationKey: '244464DFCB537E56',
12  match: {consumerMdn: '+14085040458'}
13}, {
14  authorization: 'y5jBqXWLzEF4OgK61EbJ4jbEesmxE5No',
15  requesttime: '2022-08-01T09:33:43+00:00'
16})
17  .then(({ data }) => console.log(data))
18  .catch(err => console.error(err));

Output

1{
2  "results": {
3    "correlationId": "984681AFDB698C67",
4    "referenceId": "6496849684CBAF87A9",
5    "phoneIdResult": {
6      "associationKey": "9572041AFDB69VN45",
7      "matchScores": {
8        "mdnMatchScore": "10"
9      }
10    }
11  }
12}