KYC Info Match User Guide
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 KYC Info Match and other Syniverse services such as Phone Number Verification, SIM Swap Protection, and authentication methods.
Service Overview
KYC Info Match 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 KYC 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 |
|
rpv |
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 always safeguard this information. 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 |
|
rpv
|
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 |
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.
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
KYC Info Match
Request URL
https://serverurl/v1/rpv
The actual URL will be provided during onboarding.
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 |
|
|
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* |
|
|
addressCountryCode |
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 |
|
*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 |
|
phoneNumber |
This JSON object encapsulates information about the phone number. |
| verificationMatch |
This JSON object encapsulates the result of the API call. |
phoneNumber object details
|
Parameter |
Description |
|
international |
The international code tied to the phone number input. Example international: +434766383947771 |
|
nationalFormat |
The national format of the phone number input. Max Length: 20 Example nationalFormat: 04766 383947771 |
|
countryCode |
The two-letter code representing the country the phone number belongs to. Example countryCode: AT |
|
callingCountryCode |
The country code tied to the phone number input. Example lastNameScore: 43 |
verificationMatch object details
|
Parameter |
Description |
|
summaryScore |
The evaluation score of the user data input to the API. Max Score: 100 Example summaryScore: 75 |
|
details |
The details about each component input into the API. These details were used to derive the summaryScore. |
details object details
|
Parameter |
Description |
|
firstName |
End-user first name score. Will return one of five results [ exactMatch, highPartialMatch, partialMatch, noMatch, noDataAvailable ]. |
|
lastName |
End-user last name score. Will return one of five results [ exactMatch, highPartialMatch, partialMatch, noMatch, noDataAvailable ]. |
|
addressLines |
End-user address lines score. Will return one of five results [ exactMatch, highPartialMatch, partialMatch, noMatch, noDataAvailable ]. |
|
city |
End-user city score. Will return one of three results [ exactMatch, noMatch, noDataAvailable ]. |
|
state |
End-user state, province or locality as applicable in the country score. Will return one of three results [ exactMatch, noMatch, noDataAvailable ]. |
|
postalCode |
End-user billing postal zip code score. Will return one of three results [ exactMatch, noMatch, noDataAvailable ]. |
|
addressCountryCode |
End-user 2 letter ISO country code score. Will return one of three results [ exactMatch, noMatch, noDataAvailable ]. |
|
nationalId |
End-user national ID score. Will return one of three results [ exactMatch, noMatch, noDataAvailable ]. |
|
dateOfBirth |
End-user date of birth score. Will return one of three results [ exactMatch, noMatch, noDataAvailable ]. |
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 |
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/rpv
Content-Type: application/json
Authorization: qPrOHV9HuUaicXrK9I9hM5pmR2QG
{
"phoneNumber":"+14082321000",
"firstName":"Jane",
"lastName":"Smith",
"addressLine1":"321 Main Street",
"addressLine2":"Suite 22",
"city":"New York",
"state":"NY",
"postalCode":"10021",
"addressCountryCode":"US"}
Example successful response
HTTP/1.1 200 OK
Content-Type: application/json
{
"phoneNumber": {
"international": "+14082321000",
"nationalFormat": "4082321000",
"countryCode": "US",
"callingCountryCode": "1"
},
"verificationMatch": {
"summaryScore": 75,
"details": {
"firstName": "exactMatch",
"lastName": "exactMatch",
"addressLines": "exactMatch",
"city": "exactMatch",
"state": "noMatch",
"postalCode": "noMatch",
"addressCountryCode": "exactMatch",
} }
}
Example error response
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"errors": [
{
"error": "Unsupported carrier",
"type": "other",
"errorCode": 60008
}
]
}
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. |
Appendix B – KYC Info Match Logic Examples
This section describes examples of how match scores would be calculated in different scenarios at Syniverse.
|
Match Level |
Description |
Example |
|
exactMatch |
Exact match |
"Robert" matches "Robert". |
|
highPartialMatch |
Misspelling |
"Robere" is a high partial match for "Robert". |
|
partialMatch |
Abbreviation |
"Bob", "Rob", or "R" are partial matches for "Robert". |
|
noMatch |
No match |
"John" doesn't match "Robert". |
|
noDataAvailable |
No data for match |
“Robert” was searched but no data is available to compare it to. |
Appendix C – KYC Info Match Summary Score Examples
|
First Name Score |
Last Name Score |
Street Address Score |
Identity Score |
|
|
Any positive match |
Any positive match |
Any positive match |
100 |
|
|
Positive |
No match/no data |
Positive |
80 |
|
|
Positive |
No match/no data |
No data |
70 |
|
|
Positive |
Positive |
No match/no data |
40 |
|
|
No match/no data |
Positive |
Positive |
20 |
|
|
No match/no data |
Positive |
No match/no data |
20 |
|
|
No match/no data |
No match/no data |
No match/no data |
0 |
|
|
No match/no data |
No match/no data |
Positive |
0 |
|
|
No match/no data |
No match/no data |
No match/no data |
0 |
|