SIM Swap Protection User Guide


Introduction

Fraudsters are increasingly using social engineering and techniques such as SIM Swap and SIM jacking to take over phone numbers belonging to legitimate customers. When successful this enables fraudsters to intercept SMS and other mobile channels, enabling them to access One Time PIN codes and other messages sent to customers.

Enterprises can protect themselves and their customers by using Account Takeover Detection and other Syniverse services such as Multi-Factor Authentication, Phone Number Verification and Right Party Verification.

Service Overview

Account Takeover Detection enables Enterprises to reduce fraud and increase security when communicating with their customers.  Common scenarios where Enterprises use ATO Detection are when authenticating end users using a SMS One Time PIN code or sending fraud alerts via SMS.

It also protects other channels / methods that use a mobile number, such as voice, WhatsApp and Rich Communication Services.

The ATO Detection API is a REST-like server-to-server API and requires Enterprises to host the end-user-facing user interface and obtain end-user consent.

Enterprises call this API to find out if an end-user’s mobile channel may be compromised before deciding to either let the end-user continue in the regular flow or to step up authentication using another channel (e.g. knowledge or additional factors). This is made possible by Syniverse analyzing phone signals around the end-user’s SIM and giving the Enterprise an indicator whether the mobile channel has any recent changes that violate a Enterprise’s pre-defined risk tolerance.

API Call

Function

ato

This API call is used to determine if the mobile channel of an end-user has had recent SIM changes indicating possible risk of an account takeover.

 

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

ato

 

Client ID, Client Secret, Bearer Token

Client ID and Client Secret are used to obtain a Bearer Token.

The Bearer Token must be included in the Authorization header of all API requests.

Client ID/Secret: Up to 128 characters

Bearer Token: variable length.

 

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 .

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

The security key to use for Syniverse APIs, which was shared during the onboarding process.

       Example Authorization: qPrOHV9HuUaicXrK9I9hM5pmR2QG

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.

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.

Service Configuration

Syniverse's Account Takeover Detect works by returning a True/False indicator to a timestamp challenge. Enterprise determines that they want to know if there has been an Account Takeover or SIM change within a pre-defined timeframe, for example the last 48 hours (SIM change is defined as a new association between a MSISDN and an IMSI or SIM Identifier). Syniverse will return a True or False response if a SIM change has taken place based on the time of the request.

 

Additionally, if the Enterprise plans to use voice OTP (One Time Passcode) as a method to verify device possession by an end-user, then Syniverse will also investigate whether call forwarding is enabled for the end-user’s phone number. The API response will still return only one T/F response to notify the Enterprise if the end-user’s mobile channel has seen one either a SIM change or call forwarding enabled, indicating a possible risk for the Enterprise if they continue to authenticate using this channel.

 

If data is not available for an end-user’s phone number, then Syniverse will return an error code (please refer to Appendix A) instead of True/False.

 

During implementation Syniverse will configure your account accordingly to set a pre-defined risk-tolerance timeframe in hours. Enterprises may have a range as short as 1 hour or a longer range of 3 days for example. If a range of 3 days is preferred by an Enterprise, then Syniverse would configure the Enterprise’s API with an Account Takeover range in the corresponding number of hours i.e., 72 hours. SIM change availability may vary per carrier.

 

The production URL will also be confirmed by Syniverse as part of the implementation. This is because there are different geographic deployments used depending on the country.

API Specification

Account Takeover Detection

Request URL

https://serverurl/v1/ato

The actual URL will be provided during onboarding.

Request parameter details

Parameter

Description

 

Required

phoneNumber

The end-user’s mobile number in E.164 international format.

Example phoneNumber: +14444441111

Yes

 

Response parameter details, if API call is successful

Parameter

Description

phoneNumber

This object contains details about the phone number input to the API. 

carrierName Name of the carrier currently in possession of the phone number.
mobileCountryCode Country code for the mobile number.
mobileNetworkCode Network code for the mobile number.
lastSimSwap This object contains information about the last sim change event.

phoneNumber object details

Parameter

Description

international

The international code tied to the phone number input.

Example international: +14155550123

nationalFormat

The national format of the phone number input.

Max Length: 20

Example nationalFormat: 415-555-0123

countryCode

The two-letter code representing the country the phone number belongs to.

Example countryCode: US

callingCountryCode

The country code tied to the phone number input.

Example callingCountryCode: 1

lastSimSwap object details

Parameter

Description

lastSimSwapAt

The date and time at which the last sim change event occurred for the phone number provided.

swappedPeriodSeconds

The defined set of time to look back to determine if a sim swap presents a risk of fraud in seconds.

If 3 days then swappedPeriodSeconds: 259200

swappedInPeriod

A Boolean value (true/false) to indicate if a sim change has occurred in the predefined period (swappedPeriodSeconds) since the api call was made.

Response parameter details, if API call is not successful

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

 

Example request

POST https://serverurl/v1/ato

Content-Type: application/JSON

Authorization: qPrOHV9HuUaicXrK9I9hM5pmR2QG

{

"phoneNumber":"+18134005000"

}

Example successful response 

HTTP/1.1 200 OK 

Content-Type: application/JSON 

{

    "phoneNumber": {

        "international": "+18134005000",

        "nationalFormat": "(813) 400-5000",

        "countryCode": "US",

        "callingCountryCode": "1"

    },

    "carrierName": "Carrier",

    "mobileCountryCode": "311",

    "mobileNetworkCode": "123",

    "lastSimSwap": {

        "lastSimSwapAt": "2024-07-11T12:34:41.533428283Z",

        "swappedPeriodSeconds": 259200,

        "swappedInPeriod": false

    }

}

 

 

Example error response 

HTTP/1.1 400 Bad Request 

Content-Type: application/JSON

{

    "errors": [

        {

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

            "type": "validation",

            "errorCode": 4010

        }

    ]

}

 

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 FA 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.