Introduction

Fraudsters are increasingly using social engineering and techniques such as phishing and sim swapping to access the accounts of individuals. When successful this can enable fraudsters to view private records, initiate money transfers, and impersonate individuals.

Enterprises can protect themselves and their customers by using Silent Network Authentication and other Syniverse services such as Phone Number Verification and SIM Swap Protection.

Service Overview

Silent Network Authentication enables Enterprises to reduce risk of phishing attacks during authentication and lower the frictions customers experience on sign in. Common use cases are integration into a mobile app for login, or an additional authentication step for high risk/value transactions.

The SNA APIs are a REST-like server-to-server APIs and requires Enterprises to host the end-user-facing user interface and obtain end-user consent.

Enterprises can call these APIs to authenticate end-users utilizing their handheld device against carrier data. The authentication results can be used to ensure that the device the end user is accessing a mobile app or web app from belongs to the phone number they have provided.         

 

API Call	Function
fa	This API call is used to initiate an authentication session with Syniverse and obtain a callback URL for the mobile carrier who owns the device.
callbackUrl	A url that is required to be accessed via the end-users mobile device over carrier data for authentication.
status	This API call is used to obtain the current status of the authentication session.

 

 

Integration

Security and Encryption

Since Syniverse’s Mobile Identity platform handles sensitive end-user information, utmost care is taken to safeguard this information at all times. Syniverse implements multiple layers of security between the Enterprise system and Syniverse’s system.

1.     Secure Communication Channel: All communication between the Enterprise’s system and Syniverse’s system takes place over HTTPS (TLS version 1.2 or above).

2.     OAuth 2.0 Authentication: Enterprises are provisioned with a Client ID and Client Secret during onboarding. To access APIs, the Enterprise system must obtain an OAuth 2.0 Bearer Token by authenticating with Syniverse’s authorization server using the Client ID and Client Secret.

The Bearer Token must be included in the Authorization header of all API requests. Syniverse processes the request only if it comes with a valid Bearer Token. Please contact Syniverse Support to manage credential lifecycle or resolve authentication issues.

 

Security Credentials

The following lists all possible credentials provided by Syniverse to ensure authentication of APIs, security and privacy of the end-user information.

 

API Call	Security Values	Utilization	Key Length
fa	Client ID, Client Secret, Bearer Token	Client ID and Client Secret are used to obtain a Bearer Token.	Client ID, Client Secret, Bearer Token
status	Client ID, Client Secret, Bearer Token	Client ID and Client Secret are used to obtain a Bearer Token.	Client ID, Client Secret, Bearer Token

 

Constructing Requests

Syniverse exposes easy-to-use REST-like APIs and requests should be sent as JSON objects. Enterprises can use standard libraries to create the requests. Below table shows the request header details for each JSON API.

 

Request header details

Parameter	Description	Required
Content-Type	Media type sent in the request. Only application/json is supported.        Example Content-Type: application/json	Yes
Authorization	OAuth 2.0 Bearer Token obtained using your Client ID and Client Secret.        Example Authorization: Bearer token eyJhbGciOiJSUzI1NiIsInR5cCI6...	Yes

 

Processing Response

The Syniverse Mobile Identity platform returns response values as JSON objects. Enterprises should use a JSON parser to extract the information. Below table shows Response header details for each JSON API.

Response header details

Parameter	Description
Content-Type	Media type sent in the response.        Example Content-Type: application/json

 

Sandbox

During integration the Enterprise will use the Mobile Identity sandbox to develop and test against. The sandbox provides dummy data to simplify testing of different scenarios and test cases.

 

Access details & credentials for the sandbox will be provided by Syniverse during onboarding. 

 

API Specifications

Silent Network Authentication

Create Session URL

https://serverurl/v1/fa

The actual URL will be provided during onboarding. Separate URLs will be provided for the Sandbox and Production systems.

 

Request parameter details

Parameter	Description		Required
phoneNumber	The end-user’s mobile number to be used in E.164 international format. Example msisdn: +14444441111		Yes

 

Response parameter details, if API call is successful

Parameter	Description
callbackUrl	A url that is required to be accessed via the end-users mobile device over carrier data for authentication.

 

Response parameter details, if API call is unsuccessful

Parameter	Description
error	A brief explanation of the error that occurred.        Example error: Invalid phone number +100020003000
type	The type of error that occurred. This can provide more information about where in the process the error occurred.        Example type: validation
errorCode	Indicates the reason the call failed.        Example errorCode: 4010

 

Handset connection to URL

The callbackUrl needs to be accessed via handset for there to be a change in status for the Check Session call.

 

Check Session

https://serverurl/v1/fa/status

The actual URL will be provided during onboarding. Separate URLs will be provided for the Sandbox and Production systems.

 

Request parameter details

Parameter	Description		Required
phoneNumber	The end-user’s mobile number to be used in E.164 international format. Example msisdn: +14444441111		Yes

 

Response parameter details, if API call is successful

Parameter	Description
status	The status of the authentication session for the provided phone number. Example status: pending
createdAt	The time at which the authentication session for the provided phone number was created.
updatedAt	The time at which the authentication session for the provided phone number was last updated.

 

Response parameter details, if API call is unsuccessful

Parameter	Description
error	A brief explanation of the error that occurred.        Example error: Invalid phone number +100020003000
type	The type of error that occurred. This can provide more information about where in the process the error occurred.        Example type: validation
errorCode	Indicates the reason the call failed.        Example errorCode: 20404

 

Example Calls

Example Session Creation

POST https://serverurl/v1/fa

Content-Type: application/json

Authorization: qPrOHV9HuUaicXrK9I9hM5pmR2QG

{

"phoneNumber":"+18134005000",

}

 

Example successful response 

HTTP/1.1 200 OK

Content-Type: application/json

{

  "callbackUrl": "https://serverurl/v1/fac?data=C6/lRCBaRAacPHKdfC10oDKsn5vBI8lDY1GM0nMr5D7poueOBk92YRxPaPW/xxt..."

}

 

Example error response  

HTTP/1.1 400 Bad Request

Content-Type: application/json

{

  "errors": [

    {

      "error": "Invalid phone number +181340005000",

      "type": "validation",

      "errorCode": 4010

    }

  ]

}

 

Example Status Check

POST https://serverurl/v1/fa/status

Content-Type: application/json

Authorization: qPrOHV9HuUaicXrK9I9hM5pmR2QG

{

"phoneNumber":"+18134005000",

}

 

Example successful response 

HTTP/1.1 200 OK

Content-Type: application/json

{

  "status": "pending",

  "createdAt": "2024-08-23T12:48:41.429Z",

  "updatedAt": "2024-08-23T12:48:41.429Z"

}

 

Example error response  

HTTP/1.1 400 Bad Request

Content-Type: application/json

{

  "errors": [

    {

      "error": "The requested resource does not exist",

      "type": "other",

      "errorCode": 20404

    }

  ]

}

 

 Appendix A - Error Codes and Descriptions (Error Object)

 

Error Code	Error Description	Comments	Recommended Action
4001	JSON Parsing Error Code.	Invalid JSON body in the request.	Please retry with JSON matching the schema.
4002	JSON Decode Error Code.	Invalid JSON body in the request.	Please retry with JSON matching the schema.
4003	Decode Error Code.	Internal error.	Integration Issue. Contact Syniverse Support for help.
4010	Invalid Phone Number Error Code.	Phone number cannot be recognized.	Integration Issue. Contact Syniverse Support for help.
4040	Auth Invalid JWT Error Code.	Authentication failed.	Integration Issue. Contact Syniverse Support for help.
4041	Auth Authorization Failed Error Code.	Authentication failed.	Integration Issue. Contact Syniverse Support for help.
4042	Auth Non-Prod Account Rejected Failed Error Code.	Account cannot be recognized.	Integration Issue. Contact Syniverse Support for help.
4051	Invalid SNA Callback Data Query Parameter.	Query parameter cannot be recognized.	Integration Issue. Contact Syniverse Support for help.
4400	Generic Client Error.	Generic client error.	Integration Issue. Contact Syniverse Support for help.
4404	Generic Not Found.	Generic error.	Integration Issue. Contact Syniverse Support for help.
4510	Generic Twilio Server Error.	Generic error.	Integration Issue. Contact Syniverse Support for help.
5001	Auth Exception Error Code.	Authentication failed.	Integration Issue. Contact Syniverse Support for help.
5002	Logic Exception Error Code.	Unsupported version.	Integration Issue. Contact Syniverse Support for help.
5013	Twilio Server Not Available Error Code.	Exceeded time to perform end-user identification.	Do not retry. Terminate transaction and exit.
5024	Timeout Error Code.	Timeout Error.	Integration Issue. Contact Syniverse Support for help.
20404	Not Found.	Generic error.	Integration Issue. Contact Syniverse Support for help.
60006	Invalid Phone Number.	Invalid Phone Number.	Integration Issue. Contact Syniverse Support for help.
60008	Unsupported Carrier.	Unsupported Carrier.	Integration Issue. Contact Syniverse Support for help.
60607	Lookup Unsupported Country.	Lookup Unsupported Country.	Integration Issue. Contact Syniverse Support for help.
60620	Lookup Sim Swap Info Incomplete from Carrier.	Lookup Sim Swap Info Incomplete from Carrier.	Integration Issue. Contact Syniverse Support for help.
60419	SNA Verification Result Pending.	SNA Verification Result Pending.	Integration Issue. Contact Syniverse Support for help.