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