Right Party Verification User Guide
Right Party Verification Overview
Introduction
Digital Identity is enabling enterprises transform customers interactions. However fraudsters are also using new techniques such as synthetic and stolen digital identities to create fake accounts and access existing accounts.
Enterprises can protect themselves and their customers by using Right Party Verification and other Syniverse services such as Multi-Factor authentication, Phone Number Verification and Account Takeover Detection.
Service Overview
Right Party Verification enables Enterprises to reduce fraud during account registration and customer onboarding. Common use cases are during online bank account creation or loan approval, or during social network registration.
The Right Party Verification 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 can call this API to match end-user data such as name and address mapped to a phone number against Syniverse-sourced data originating from carriers and other authoritative third parties. The match results can be used to verify an identity during account registration to prevent registration with synthetic or stolen identities.
|
API Call |
Function |
|
Match |
This API call is used to obtain match scores related to the identity associated with the phone number by comparing the end-user identity to Syniverse-sourced data. |
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. IP Address Whitelisting: Enterprise system’s IP addresses are whitelisted before any API calls can be made to Syniverse’s production environment.
3. API Request Validation: Enterprise is assigned a Merchant ID, an optional submerchant ID and an API Secret. The Secret is an alphanumeric string and is shared with the Enterprise during the onboarding process. Enterprise must send the API Secret in the header for all API requests. Syniverse processes the request only if it comes with a valid API Secret. Please contact Syniverse’s Support team to know the validity of the API Secret – the Support team will issue a new one prior to the expiry of the current value.
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 |
|
match
|
API Secret |
Key to use in the request header (Authorization) of all APIs. Shared with Enterprise at onboarding. |
Up to 128 characters |
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 |
|
Accept |
Media type for the response. Only application/json is supported. Example Accept: application/json |
Yes |
|
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 |
|
RequestTime |
Current date time when request is sent. Request time in ISO 8601 format: YYYY-MM-DDThh:mm:ss.ffffff Example RequestTime: 2017-03-21T19:28:53+09:00 |
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
During implementation Syniverse will configure your account depending on whether you would like the identity to be verified against mobile network operator data or authoritative third parties or the best match across both.
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
Right Party Verification
Request URL
https://Syniverseserverurl/cigw/v2/match
The actual URL will be provided during onboarding.
Request parameter details
|
Parameter |
Description |
|
Required |
|
merchantId |
A A unique string assigned by Syniverse to identify the merchant. T This ID will be provided by Syniverse during the onboarding process. Max Length: 30 Example merchantId: 00DF00000015 |
Yes |
|
|
subMerchantId |
Resellers Only This unique ID is assigned to a reseller’s end merchant. This ID will be provided by Syniverse during the onboarding process. Max Length: 30 Example subMerchantId: 00DF00000016 |
No |
|
|
consentId |
Merchant passes a unique Id from capturing the consent from the end-user. It needs to be traceable back to the channel how the end-user had provided the consent. Max Length: 128 Example consentId: uyciydfoudqwg912863017 NOTE: When consentTimeStamp is passed, consentId must also be passed. |
Yes* |
|
|
consentTimeStamp |
Date and time when end-user consent was obtained. Format: yyyy-MM-ddTHH:mm:ss +00:00 Example consentTimeStamp: 2020-02-13T20:20:39+00:00 NOTE: When consentId is passed, consentTimeStamp must also be passed. |
Yes* |
|
|
msisdn |
The end-user’s mobile number to be used in E.164 international format. Example msisdn: +14444441111 |
Yes |
|
|
correlationId |
Enterprise’s transaction identifier that can uniquely identify this particular transaction. Min length: 8, Max Length: 80 Example correlationId: 1310881973286793 |
Yes |
|
|
firstName |
End-user first name Max Length: 128 characters Example firstName: Jane |
No** |
|
|
lastName |
End-user last name Max Length: 128 characters Example lastName: Smith |
No** |
|
|
address1 |
End-user address line 1 Max Length: 256 characters Example address1: 2833 Junction Ave |
No** |
|
|
address2 |
End-user address line 2 Max Length: 256 characters Example address2: Suite 202 |
No |
|
|
city |
End-user city Max Length: 128 characters Example city: San Jose |
No** |
|
|
state |
End-user state, province or locality as applicable in the country Max Length: 128 characters Example state: CA |
No** |
|
|
postalCode |
End-user billing postal zip code Max Length: 10 characters Example postalCode: 95134 |
No** |
|
|
countryCode |
2 letter ISO country code Example countryCode: FR |
No |
|
|
nationalId |
End-user national ID Max Length: 128 characters Example nationalId: YZ3456883 |
No |
|
|
dateOfBirth |
End-user date of birth in YYYYMMDD format Example dateOfBirth:19900101 |
No |
|
*consentId and consentTimeStamp are not mandatory for authoritative sources in the US
**Depending upon country; these fields maybe mandatory, Syniverse Account or Implementation Team can provide most up to date requirements.
Response parameter details, if API call is successful
|
Parameter |
Description |
|
results |
This JSON object encapsulates the API response. |
Response object details
|
Parameter |
Description |
|
correlationId |
Enterprise’s transaction identifier that can uniquely identify this particular transaction. Max Length: 80 Example correlationId: 1310881973286793 |
|
responseId |
Syniverse’s unique transaction response identifier. Max Length: 30 Example responseId: 568887569756956 |
|
firstNameScore |
Level of match for the First Name attribute assigned to the submitted mobile number from low to high – the higher the Match score*, the more accurate is the match. Example firstNameScore: 10 |
|
lastNameScore |
Level of match for the Last Name attribute assigned to the submitted mobile number from low to high – the higher the Match score*, the more accurate is the match. Example lastNameScore: 10 |
|
streetAddressScore |
Level of match for the Street Address attribute assigned to the submitted mobile number from low to high – the higher the Match score*, the more accurate is the match. Example streetAddressScore: 10 |
|
cityScore |
Level of match for the City attribute assigned to the submitted mobile number from low to high – the higher the Match score*, the more accurate is the match. Example cityScore: 10 |
|
stateScore |
Level of match for the State attribute assigned to the submitted mobile number from low to high – the higher the Match score*, the more accurate is the match. Example stateScore: 10 |
|
postalCodeScore |
Level of match for the Postal Code attribute assigned to the submitted mobile number from low to high – the higher the Match score*, the more accurate is the match. Example postalCodeScore: 10 |
|
countryCodeScore |
Level of match for the Country Code attribute assigned to the submitted mobile number from low to high – the higher the Match score*, the more accurate is the match. Example countryCodeScore: 10 |
|
nationalIdScore |
Level of match for the National ID attribute assigned to the submitted mobile number from low to high – the higher the Match score*, the more accurate is the match. Example nationalIdScore: 10 |
|
dateOfBirthScore |
Level of match for the Date of Birth attribute assigned to the submitted mobile number from low to high – the higher the Match score*, the more accurate is the match. Example dateOfBirthScore: 10 |
|
dataSource |
Returns the data source that the Enterprise data was compared against. Values can be “Carrier” or “Third-Party”. Example dataSource: Carrier |
|
identityScore |
A single score that indicates the overall level of match between Syniverse’s data sources and end-user data sent in the Enterprise request. It ranges from 0 – 100. 100 indicates strong match and 0 indicates complete mismatch. Example: identityScore: 100 |
*Match score definitions:
-1=Data not available for attribute
0=No Match
5= Partial Match
9=High Partial Match
10=Exact Match
Match scores will only be returned for attributes that were passed in the request.
Response parameter details, if API call is not successful
|
Parameter |
Description |
|
Error |
This is the object that encapsulates the API response. Included in place of the results object if the call is not successful |
|
correlationId |
Enterprise’s transaction identifier that can uniquely identify this particular transaction, if available. The value from the request is echoed back. Min length: 8, Max length: 80 Example correlationId: ABC0881973286793 |
|
responseId |
Syniverse’s transaction identifier than can uniquely identify this particular transaction, if available. Max length: 30 Example responseId: 20200325234640M163C264030 |
|
Code |
Indicates the reason the call failed. Example code: -5001 |
|
description |
Additional information regarding the error condition. Set only if error code is included in the response. Max Length: 256 Example description: Authentication failed |
Example request
POST https://serverurl/cigw/v2/match
Accept: application/json
Content-Type: application/json
Authorization: qPrOHV9HuUaicXrK9I9hM5pmR2QG
RequestTime: 2021-02-23T19:28:53+00:00
{
"merchantId":"00DF00000015",
"subMerchantId":"00DF00000016",
"consentId":"uyciydfoudqwg912863017",
"consentTimeStamp":"2021-01-03T12:30:23+00:00",
"correlationId":"ABC0881973286793",
"msisdn":"+14082321000",
"firstName":"Jane",
"lastName":"Smith",
"address1":"321 Main Street",
"address2":"Suite 22",
"city":"New York",
"state":"NY",
"postalCode":"10021",
"countryCode":"US",
"nationalId": "YZ3456883",
"dateOfBirth": "19901214"
}
Example successful response
HTTP/1.1 200 OK
Content-Type: application/json
{
"results": {
"correlationId": "ABC0881973286793",
"responseId": "568887569756956",
"firstNameScore": "10",
"lastNameScore": "10",
"streetAddressScore": "9",
"cityScore": "10",
"stateScore": "10",
"postalCodeScore": "10",
"countryCodeScore":"10".
"dateOfBirthScore": "10",
"nationalIdScore": "10",
"dataSource": "Carrier",
"identityScore": "100"
}
}
Example error response
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": {
"correlationId":"ABC0881973286793",
"responseId":"568887569756956",
"code":"-5003",
"description":"Required parameter missing"
}
}
Appendix A - Error Codes and Descriptions (Error Object)
|
Error Code |
Error Description |
Comments |
Recommended Action |
|
-5000 |
Access not allowed. |
Access not allowed for the requested API. |
Integration Issue. Contact Syniverse Support for help. |
|
-5001 |
Authentication failed. |
Enterprise authentication failed. Check the signature computation. |
Integration Issue. Contact Syniverse Support for help. |
|
-5002 |
Unsupported version. |
Unsupported version used for the API request. |
Integration Issue. Contact Syniverse Support for help. |
|
-5003 |
Retry with missing parameter. |
A required parameter is missing from the API request. |
Integration Issue. Contact Syniverse Support for help. |
|
-5004 |
An invalid parameter was passed. |
An invalid parameter was passed in the API request. |
Integration Issue. Contact Syniverse Support for help. |
|
-5005 |
An internal error occurred. |
An internal error has occurred. |
Retry. If error persists, Contact Syniverse. |
|
-5006 |
Retry with end-user identifier. |
An end-user identifier such as the mobile number, authentication key or association key is missing from the API request. |
Integration Issue. Contact Syniverse Support for help. |
|
-5009 |
This phone number is not whitelisted. |
Whitelisting is enabled and the phone number is not whitelisted. |
Contact Syniverse Support to whitelist number. |
|
-5010 |
Missing or Incorrect Submerchant Id. |
A valid sub-merchant id is required for reseller Enterprises. |
Integration Issue. Contact Syniverse Support for help. |
|
-5013 |
Exceeded time to perform end-user identification. |
The authentication key has expired before end-user identification could be completed. |
Do not retry. Terminate transaction and exit. |
|
-5017 |
Retry with passing consent in the input. |
User consent is needed to make this API call in the current configuration. |
Integration Issue. Contact Syniverse Support for help. |
|
-5018 |
Please retry with both consentId and consentTimeStamp |
Either consent id or consent timestamp was missing from the API request. |
Integration Issue. Contact Syniverse Support for help. |
|
-5020 |
Data is not available for this user |
Data is not available for this user from any of the configured data sources. |
Do not retry. Terminate transaction and exit. |
|
-5022 |
Invalid Enterprise. |
The Enterprise cannot be recognized. |
Integration Issue. Contact Syniverse Support for help. |
|
-5029 |
Data access not allowed. Please contact Customer Support. |
The Enterprise is not configured for this API or for the Attribute Groups being requested. |
Integration Issue. Contact Syniverse Support for help. |
|
-5030 |
Data access not allowed. Please contact Customer Support. |
Service providers are not configured for this Enterprise. |
Integration Issue. Contact Syniverse Support for help. |
|
-5033 |
Consumer identifier is invalid. |
The end-user identifier such as the mobile number, authentication key or association key is invalid. |
Do not retry. Terminate transaction and exit. |
|
-5035 |
This Authentication Key has expired. |
The authentication key has expired and cannot be used anymore. |
Do not retry. Terminate transaction and exit. |
|
-5037 |
Service provider error occurred. Please retry. |
An error occurred while communicating with a service provider. |
Retry. If error persists, Contact Syniverse Support. |
|
-5046 |
No value was passed for consumerMdn and carrier. |
No value was passed for consumerMdn and carrier. |
Please retry by passing both the values. |
|
-5049 |
No value was passed for consumerMdn or carrier. |
No value was passed for consumerMdn or carrier. |
Please retry by passing either of the values. |
|
-5050 |
Data access not allowed. Please contact Enterprise Support. |
Data access not allowed. Please contact Enterprise Support. |
Integration Issue. Contact Syniverse Support for help. |
|
-5053 |
Please retry with a valid MSISDN |
Please retry with a valid MSISDN |
Retry. If error persists, Contact Syniverse Support. |
|
-5054 |
Please retry with valid Consent |
Input consent parameters are not valid. |
Retry. If error persists, Contact Syniverse Support. |
|
-5055 |
Consent is no longer active |
Consent is no longer active. |
Please obtain new consent from the user and retry |
|
-5056 |
Please retry with valid Consent |
Consent is no longer active. |
Please obtain new consent from the user and retry |
|
-5057 |
Carrier not supported. |
Syniverse has not integrated with the carrier and there is no access to other authoritative data sources for the MSISDN |
Do not retry. Terminate transaction and exit. |
|
-5061 |
Insufficient information to determine response |
Syniverse did not obtain sufficient information from mobile carrier to determine a response. |
Do not retry. Terminate transaction and exit. |
|
-5062 |
Unable to identify carrier |
Syniverse could not identify the carrier associated with the phone number. nxx are two digits used for internal tracking. |
Do not retry. Terminate transaction and exit. |
Appendix B – Right Party Verification Logic Examples
This section describes examples of how match scores would be calculated in different scenarios at Syniverse.
|
Rule |
Attribute |
Enterprise Data |
Carrier/3rd Party Data |
Match Score |
|||
|
Exact first name |
First Name |
Robert |
Robert |
10 |
|||
|
Misspelling |
First Name |
Robere |
Robert |
9 |
|||
|
Common nickname |
First Name |
Bob |
Robert |
5 |
|||
|
Contains name |
First Name |
Rob |
Robert Floyd |
5 |
|||
|
First initial when last name is same |
First Name |
R |
Robert |
5 |
|||
|
Contains multiple words |
First Name |
Robert |
Robert Floyd |
9 |
|||
|
First name and last name swapped |
First Name |
First Name: Johnson |
First Name: Robert |
5 |
|||
|
Different first name |
First Name |
Stephen |
Robert |
0 |
|||
|
Same last name |
Last Name |
Johnson |
Johnson |
10 |
|||
|
Misspelling last name |
Last Name |
Johnsn |
Johnson |
9 |
|||
|
Contains multiple words |
Last Name |
Johnson |
Smith Johnson |
9 |
|||
|
First name and last name swapped |
Last Name |
First Name: Johnson |
First Name: Robert |
5 |
|||
|
Different last name |
Last Name |
Johnson |
Smith |
0 |
|||
|
Same street address |
Street Address |
565 Downtown Ave Suite 202 |
565 Downtown Ave Suite 202 |
10 |
|||
|
Missing street address line 2 |
Street Address |
565 Downtown Ave |
565 Downtown Ave Suite 202 |
9 |
|||
|
Misspelling address |
Street Address |
565 Donwtown Ave |
565 Downtown Ave Suite 202 |
9 |
|||
|
Missing street number |
Street Address |
Downtown Ave |
565 Downtown Ave Suite 202 |
5 |
|||
|
Numbers match |
Street Address |
565 Main Street Apt 202 |
565 Downtown Ave Suite 202 |
5 |
|||
|
Different street address |
Street Address |
123 Main Street |
565 Downtown Ave Suite 202 |
0 |
|||
|
Same City |
City |
San Jose |
San Jose |
10 |
|||
|
Different City |
City |
Los Angeles |
San Jose |
0 |
|||
|
Same State |
State |
CA |
CA |
10 |
|||
|
State abbreviation |
State |
California |
CA |
10 |
|||
|
Different State |
State |
NY |
CA |
0 |
|||
|
Same zip code |
Zip Code |
90210 |
90210 |
10 |
|||
|
Different zip code |
Zip Code |
90210 |
94086 |
0 |
|||