Decision Maker
This API provides a solution for identity fraud detection. Using machine learning models, cross-references user information with extensive internal data, enriching and assessing it for potential risks. The end goal is to equip you with actionable insights, enabling informed decisions to mitigate identity fraud.
The API generates a fraud score using data points like email, phone number, CURP, and geospatial information. This score is dynamically adjusted based on the available data, ensuring a tailored and accurate assessment of the fraud risk. The explainability module accompanying the score provides clear insights into the risk level and the rationale behind it.
Request ID
To optimize the validation process, each API call generates a unique request ID. This ID is crucial for tracking and validating data across different stages without incurring additional charges for duplicate information. Our system dynamically combines rules and data for accurate fraud detection, enhancing decision-making efficiency.
Rule Engine
Our decision-making model leverages data enrichment and a sophisticated rule engine to identify and flag potential threats. These rules are continually updated based on new insights and cover various aspects such as email threats, phone abuse, geospatial anomalies, document validity, and more. The following table outlines some key rules used in our analysis:
Data Point | Rule |
---|---|
Selfie + Document | The user's face and the user's face in the document do not match |
Selfie + CURP | The user's identity was flagged as fraud by a company on the Trully network |
Selfie + CURP | The gender of the CURP does not correspond to that of the person on the document |
Selfie + CURP | The gender of the CURP does not correspond to the gender of the person in the selfie |
Selfie | The user's face was flagged as identity fraud by a company on the Trully network |
Selfie | The user has been using different personal information, which may suggest identity theft |
Selfie | The user's face was found in the company database with another external_id |
Selfie | The user's face is covered and cannot be analyzed correctly |
SDK | The face couldn't be verified to be real |
RFC | The RFC appears as 'invalid' at the government registry |
Phone number | Phone number linked to fraudulent internet activity |
Phone number | Number not found on WhatsApp |
Phone number | Phone number reported as fraud in Trully network |
Location | The user's location is less than 50 meters from a prison |
Location | The user's location is inside a prison |
Location | The current location of the user is outside the Mexican territory. Location information cannot be enriched |
Location | The user is located in a high-fraud area |
IP | IP reported as fraud in Trully network |
IP | The user's IP comes from a country on the Gafi list |
Email reported as fraud in Trully network | |
Invalid email | |
Email linked to fraudulent internet activity | |
Document + CURP | The gender of the CURP does not correspond to the gender indicated in the document |
Document + CURP | The user's CURP and document's CURP are not the same |
Document + CURP | The identity of the document was flagged as fraud by another company on the Trully network |
Document | The validity date of the provided document is less than the current date |
Document | The document's CURP is associated with multiple faces |
Document | The user document appears manipulated |
Document | The user in the document has been using different personal information, which may suggest identity theft |
Document | The user's face on the document was found in the company database with another external_id |
Document | The gender indicated on the document does not correspond to the gender of the person in the document |
Document | Please provide a valid document |
Document | The user's face on the document was flagged as identity fraud by a company on the Trully network |
Document | The user document appears to be taken from a screen |
Document | The document's name does not correspond to the name associated with the document's CURP |
Document | The CURP in document user's appears as 'invalid' at the government registry |
CURP o Complete Name | The user has been found in a sanction list (Name match >=85%) |
CURP | The person has been sanctioned by the CNBV |
CURP | The user's CURP is associated with multiple faces |
CURP | The CURP does not exist in Renapo |
Complete Name or CURP | The user has been found in the CSONU list (Name match >=85%) |
Complete Name + CURP | The name of the person does not correspond to the name associated with the CURP |
Complete Name + CURP | The name of the document does not correspond to the name associated with the CURP |
Address + Location | The user's address and location are more than 100 km apart |
Address | The user's stated address is in a high-fraud area |
Address | The address of the user is outside the Mexican territory. Location information cannot be enriched |
Address | The user's address is less than 50 meters from a prison |
Address | The user's address is inside a prison |
Dive into the details on how to make a request in our API reference section.
Request and Response
The provided structure serves as a reference to link the keys in the JSON response with their corresponding meanings or data enrichment types.
We are working on a system enhancement to simplify the JSON response structure, aiming to improve readability and comprehension, with a release announcement and documentation forthcoming.
Data Scope Clarification
All the information referenced on this document pertains exclusively to the data encapsulated within the "raw_data" key.
Location and Address Input
You have the flexibility to enter data into the 'location' and 'address' key in two ways: an address string or inserting a dictionary for the coordinates.
Data Request Example
{
"address": "Lote 12, México D.F. CP 01234 México",
"location": {
"lat": 19.428437,
"lng": -99.157011
},
"curp": "TEST890919HNLNSR03",
"rfc": "TEST8305281H0",
"email": "[email protected]",
"phone_number": "+521234567890",
"ip": "192.0.0.1",
"device": "Apple iPhone 12 Pro Max",
"image": "iVBORw0KGg...",
"document_image": "/9j/4AAQSk...",
"document_image_back": "dAAQdsSk..."
}
Data Response Example
{
"data": {
"raw_data": {
"enrichment": {
"geospatial": {
"criminal_incidence": {...},
"summary": {...},
"high_risk_locations": {...},
"real_estate": {...},
"restaurants": {...},
"hotels": {...},
"airbnb": {...},
"demographic_access": {...},
"geo_stats": {...}
},
"background_record": {
"studies": {...},
"government_positions": {...},
"missing_report": {...},
"financial_sanctions": {...},
"association_partner": {...},
"expanded_report": {...}
},
"rfc": {
"blacklist": {...},
"validation": {...}
},
"ip": {
"tor": {...},
"vpn": {...},
"blacklisted": {...}
},
"phone_number": {...},
"curp": {...},
"device": {...},
"external_fraud_service": {
"email": {...},
"phone_number": {...},
"ip": {...}
},
"social_media": {...},
"whatsapp": {...}
},
"address_enrichment": {
"geospatial": {
"criminal_incidence": {...},
"summary": {...},
"high_risk_locations": {...},
"real_estate": {...},
"restaurants": {...},
"hotels": {...},
"airbnb": {...},
"demographic_access": {...},
"geo_stats": {...},
"address_validation": {...}
}
},
"listed_weeks": {
"employment_summary": {...},
"salary_summary": []
},
"face_recognition": {...},
"face_comparison": {...},
"document_ocr": {
"image_quality": {...},
"document_ocr": {...},
"true_document": {...},
"data_enrichment": {
"curp": {...},
"geospatial": {
"address_validation": {...}
},
"rfc": {...}
},
"face_recognition": {...},
"document_id": 287829
},
"identity_fraud_score": {
"score": 64,
"probability": 0.6467000246047974,
"explainability": {...}
}
},
"label": "Potential Threat",
"reason": [
"IP linked to fraudulent internet activity",
"The user's identity was flagged as fraud by a company on the Trully network"
],
"request_id": "example2r01eomhc718oojdg"
},
"version": "v1.51.0",
"status": "ok",
"status_code": 200,
"request_date": "2024-01-17T19:42:06+0000",
"request": {...}
}
Structure according to each input data
-
Request example: "Lote 12, México D.F. CP 01234 México"address- Where to find the response keys?
- address_enrichment ->> geospatial
- Where to find the response keys?
-
Request example: {"lat": 19.428437, "lng": -99.157011}location- Response keys:
- enrichment ->> geospatial
- Response keys:
-
Request example: "TEST890919HNLNSR03"curp- Response keys:
- curp
- listed_weeks
- background_record
- Response keys:
-
Request example: "MELM8305281H0"rfc- Response keys:
- rfc
- Response keys:
-
Request example: "[[email protected]]"email- Response keys:
- social_media
- external_fraud_service
- Response keys:
-
Request example: "+521234567890"phone_number- Response keys:
- phone_number
- external_fraud_service
- Response keys:
-
Request example: "192.0.0.1"ip- Response keys:
- ip
- external_fraud_service
- Response keys:
-
Request example: "Apple iPhone 12 Pro Max"device- Response keys:
- device
- Response keys:
-
Request example: "iVBORw0KGg..."image- Response keys:
- face_recognition
- face_comparison
- Response keys:
-
Request example: "/9j/4AAQSk..."document_image- Response keys:
- document_ocr
- Response keys:
-
Request example: "dAAQdsSk..."document_image_back- Response keys:
- document_ocr
- Response keys:
Response structure
data
-
*See full raw_data in API reference:raw_data
https://docs.trully.ai/reference/api-responses
The raw data used behind the decision-making. -
Example: "Potential Threat" (String)label
A string label associated with the decision outcome.
Possible values:- "Potential Threat": The fraud engine considers the user as a potential threat.
- "No Threat": The fraud engine considers the user not to be a threat.
- "Review": The fraud engine considers that the user should be reviewed in detail.
-
Example: [] (Array)reason
Provides an array of reasons or explanations contributing to the decision outcome.
Full list of possible reason are attached in the Rule Engine: -
Example: "co25naa4sfqc701teds0" (String)request_id
A unique identifier for this request that can be used to lookup the request details or send a postback conversion notice.
request
Example: "{'curp': 'HAEC890919HNLNSR03'}"
The original request object that was sent.
request_date
Example: "2024-03-27T17:13:09" (String)
The date and time when the request was made.
status
Example: "Bad Request" (String)
The status message following the HTTP status code of the response.
status_code
Example: 200 (Integer)
The HTTP status code of the response.
version
Example: "1.0.0" (String)
The version of the API being used.
Image Quality Guidelines for Optimal Platform Performance
To ensure the optimal functioning of the platform, adhering to specific image quality guidelines is crucial. Clear images with good quality, minimal shadows, and proper framing are essential for the system to accurately process and analyze the data. Below are detailed recommendations for both facial images and document images to meet these requirements.
Facial Image Requirements
- Clarity and Quality: Use clear, high-quality images without excessive shadows.
- Positioning: The subject's face should be centered and unobscured by objects such as glasses, hats, or face masks. The entire face must be visible.
- Compatibility: Trully can integrate seamlessly with images meeting the quality standards of digital onboarding platforms like Jumio, Incode, Mati, etc. There is no need to capture a new photograph; simply providing the photograph submitted to these platforms suffices.
Format Requirements
For optimal results, please adhere to the following image format guidelines:
- Format: Images should be in .jpeg or .png format, encoded in base64.
- Color: Use RGB images.
- Dimensions:
- Minimum width: 750 pixels
- Minimum height: 750 pixels
- Size: Recommended image weight is between ~250 KB and 2 MB.
- Document Coverage: The document area should comprise at least 70% of the total image area.
Image Quality for Facial Recognition
Maintaining a high standard for facial images is critical for the effective functioning of the recognition algorithm:
- Coverage: The entire face must be within the frame; ensure only one face per image.
- Orientation: The face should have a vertical orientation, looking straight ahead.
- Accessories: Remove any obstructive accessories like dark glasses, face masks, or hats.
Document Image Quality
Similarly, the quality of the document images is paramount for the recognition algorithm to function correctly:
- Coverage: The entire identification document must be within the image frame; only one document per image.
- Orientation: The document should be in a landscape orientation, facing front.
Following these guidelines will help ensure that your submissions are processed efficiently and accurately by the platform.
Updated 2 months ago