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 | RULE |
---|---|
Phone number | Número de teléfono vinculado a actividad fraudulenta en internet |
Phone number | Número de teléfono reportado como fraude en red Trully |
Phone number | Número no encontrado en WhatsApp |
Correo electrónico no válido | |
Email vinculado a actividad fraudulenta en internet | |
Email reportado como fraude en red Trully | |
IP | IP vinculada a actividad fraudulenta en internet |
IP | IP reportado como fraude en red Trully |
IP | La dirección IP está usando TOR |
Location | La ubicación del usuario está dentro de una prisión |
Location | La ubicación actual del usuario se encuentra fuera del territorio mexicano. La información de ubicación no se puede enriquecer |
Location | La ubicación del usuario está a menos de 50 metros de una prisión |
Address | La dirección del usuario está dentro de una prisión |
Address | La dirección del usuario se encuentra fuera del territorio mexicano. La información de ubicación no se puede enriquecer |
Address | La dirección del usuario está a menos de 50 metros de una prisión |
Address/Location | La dirección y la ubicación del usuario están separadas por más de 100 km de distancia |
Selfie | El rostro del usuario fue marcado como fraude de identidad por una empresa en la Red Trully |
Selfie | El rostro del usuario está cubierto y no se puede analizar correctamente |
Selfie/Document | El rostro del usuario y el rostro del usuario en el documento no coinciden |
Selfie | El rostro del usuario fue encontrado en la base de datos de la empresa con otro external_id |
Document | El rostro del usuario en el documento fue marcado como fraude de identidad por una empresa en la Red Trully |
Document | El rostro del usuario en el documento fue encontrado en la base de datos de la empresa con otro external_id |
Document | La fecha de validez del documento proporcionado es anterior a la fecha actual |
Document | El nombre en el documento no corresponde con el nombre asociado al CURP del documento |
Document | El CURP en el documento del usuario aparece como 'inválido' en el registro gubernamental. |
Document | El RFC calculado con el documento del usuario aparece como 'inválido' en el registro gubernamental |
Document | Por favor, proporcione un documento válido |
FaceDocument/Selfie | El género de la persona en el documento no corresponde al género de la persona en la selfie |
Document/Selfie | El género indicado en el documento no corresponde al género de la persona en la selfie |
Document/FaceDocument | El género indicado en el documento no corresponde al género de la persona en el documento |
CURP/Selfie | El género del CURP no corresponde al género de la persona en la selfie |
CURP/FaceDocument | El género del CURP no corresponde al de la persona en el documento |
CURP/Document | El género del CURP no corresponde al género indicado en el documento |
CURPDocument/Selfie | El género del CURP en el documento no corresponde al género de la persona en la selfie |
CURPDocument/FaceDocument | El género del CURP en el documento no corresponde al género de la persona en el documento |
CURPDocument/Document | El género del CURP en el documento no corresponde al género indicado en el documento |
Name | El nombre de la persona no corresponde con el nombre asociado al CURP |
Name | El nombre del documento no corresponde con el nombre asociado al CURP |
CURP | El CURP no existe en Renapo |
RFC | El RFC aparece como 'no válido' en el registro de gobierno |
CURP/CURPDocument | El CURP del usuario y el CURP del documento no son los mismos |
PEP | El usuario ha sido identificado como posible PEP (Coincidencia de nombre >=85%) |
Sanctions | El usuario ha sido encontrado en una lista de sanciones (Coincidencia de nombre >=85%) |
CNBV | La persona ha sido sancionada por la CNBV |
Identity | El usuario ha estado usando información personal diferente, lo que puede sugerir de robo de identidad |
Identity | El CURP del usuario está asociado con distintos rostros |
Identity | La identidad del usuario fue marcada como fraude por una empresa en la Red Trully |
Identity | La identidad del documento del usuario tiene un reporte de fraude |
Identity | El usuario del documento ha estado usando información personal diferente, lo que puede sugerir de robo de identidad |
Identity | El CURP del documento del usuario está asociado con distintos rostros |
Identity | The identity fraud model considers that the user should be reviewed in detail / The identity fraud model considers the user as a potential threat |
SDK | El nombre de la persona no corresponde al nombre en el código mrz del documento |
SDK | El nombre del documento no corresponde al nombre en el código mrz del documento |
SDK | El documento no es auténtico |
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 4 months ago