Overview
With the Query API, members can send queries and receive identity validations via a REST API.
Depending on the use case, different parameters are used in the Query API request. After the verification query is handled by the Identiq network, an event score is returned.
Score
Each use case has a main ‘score’ and additional sub-scores and signals that are returned in the response.
Score provides a “bottom line” user verification score, during an online event such as signup or payment. Scores range from 0-1, with 1 being the strongest verification.
Available options include Signup, Guest Payment, and account payment.
A high result will be obtained when the scoring model predicts the lowest probability of risk while weighing all the feature components of the network evidence, the member's own data, and the query field values included.
Field Sub-scores provide match strength and potential risk level, related to each queried element. The risk level is calculated based on recent fraudulent events, such as a fraudulent chargeback, associated with this field value across the network, including returning users' scans.
Field scores range from 0-1, with 1 being the strongest verification of Match Score, and the highest risk level for Risk Score.
Query Parameters
The Query API may differ for every member, as we release new versions and tailor functionality for each members' available data.
Example Request
POST https://int-your-edge-url.identiq.cloud/v2.1/verifications
PAYLOAD
{
"queryParameters": {
"scores": [
"signup"
]
},
"entity": {
"account": {
"email": {
"address": "[email protected]"
},
"address": {
"phone": {
"number": "+1-701-592-0496",
"country": "US"
},
"firstName": "Stephaine",
"lastName": "Deckow",
"postCode": "06402",
"country": "US"
},
"ip": "163.205.127.88",
"device": "7643008f-302e-4653-85fc-8aa4f3fd8cbe"
}
}
}
Response
{
"requestId": "28e48105-53a8-445d-bc73-9e258ebca184",
"scores": {
"signup": {
"score": 0.3,
"status": 0
}
},
"fields": {
"account": {
"address": {
"phone": {
"fieldScores": {
"score": 0.7,
"riskScore": 0.0
},
"valid": true
},
"firstName": {
"fieldScores": {
"score": 0.8,
"riskScore": 0.0
},
"valid": true
},
"lastName": {
"fieldScores": {
"score": 0.8,
"riskScore": 0.0
},
"valid": true
},
"postCode": {
"fieldScores": {
"score": 0.0,
"riskScore": 0.0
},
"valid": true
},
"email": {
"fieldScores": {
"score": 0.7,
"riskScore": 0.0
},
"valid": true
}
},
"ip": {
"fieldScores": {
"score": 0.2,
"riskScore": 3.0
},
"valid": true
},
"device": {
"fieldScores": {
"score": 0.0,
"riskScore": 0.0
},
"valid": true
}
}
}
}
In the example above, a query of type “New Account Creation” was triggered.
The response includes the ‘signup’ score generated by the scoring model, following a comprehensive scan of evidence, across the Identiq network as well as the member's local data, and the inquiry elements.
In the example, the score indicates a relatively low verification of the user.
The fields sub-scores indicate that the email, names, and phone provided in the query, were identified as a strong network match, with a low risk associated with it. The IP of the user inquiry on the other hand, indicates a high level of risk.
Query Parameters
Each query must include at least the email address or phone number of the user in question.
Optional parameters further optimize the score returned by Identiq. If they are known, we recommend that you include them in the requests. Those may be:
- Personal information
- Online information
- Transaction Information
- Custom per member (optional) - Identiq develops a customized score model, tailored and optimized for each member's specific needs, and data. During the solution customization, Identiq and the member will map the potential parameter, identify and determine the optimal set of features, and custom-scoring model tuning. This may include additional members' unique parameters.
| Event Score | Required | Increases Score Accuracy |
|---|---|---|
| Signup | Signup Email or Signup Phone | Signup IP and/or Device ID, First Name, Last Name, Address, Phone, Email and optional custom properties |
| GuestPayment | Transaction Billing Email or Transaction Billing phone | Credit Card BIN and last 4 digits, Transaction IP and/or Device ID, Billing First Name, Billing Last Name, Billing Address, Shipping First Name, Shipping Last Name, Shipping Address and optional custom properties |
| AccountPayment | Account Email or Account phone | Credit Card BIN and last 4 digits, Transaction IP and/or Device ID, Billing First Name, Billing Last Name, Billing Address, Shipping First Name, Shipping Last Name, Shipping Address and optional custom properties |
Increase score accuracy
Optional parameters further optimize the score returned by Identiq. If they are known, we recommend that you include them in the requests.
Key Concepts
Identiq scoring models, provide the strength of the user verification and predict the lowest probability of risk, by weighing all the feature components from the following:
The network evidence - Consensus within the network, how long the query details have been known to the network, how strongly they match, any fraudulent activities associated with the inquiry details, and other statistical calculations.
For example, the ‘Guest Transaction’ Event Score assesses the overall fraud risk of a transaction by combining several indicators such as the link between the email/phone, and provided identity details (e.g. First and Last name), the link between the credit card and the identity and the link between the session parameters (IP and/or device ID) and both the credit card and the identity. In this way, we assess the likelihood of the identity details representing one real person in the world, the likelihood of the transacting user being that person, and the likelihood of this person being an authorized user of the card.
The member's user database - Considering returning good users, repeating offenders, and additional analysis of the member's user patterns and internal connections.
The query data element - Identifying risky data patterns and information within the inquiry details. For example Geographical inconsistencies, risky email domains, and more.
Using Query Scores in Business Logic
The actual implementation of business logic based on the use cases and scores is up to the Risk decision maker - who should decide what to do according to the evidence provided by the network.
The way in which you utilize the scores is entirely in your control, and you can tailor your approach depending on your business logic and applications.
For example, you might decide that when a new sign-up receives a high score, that user can continue through their onboarding process without the need for additional verification. On the other hand, if no evidence of the queried property is found, perhaps you will require an additional form of verification (for example, two-factor authentication).
Identiq will perform, along with your risk professionals, an in-depth analysis process of current and historical scenarios, in order to determine the recommended score implementation that will produce maximum value for your specific environment.
Updated 10 months ago