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
Document	The validity date of the provided document is less than the current date.
Document	Further analysis is needed. Validity has not been confirmed.
Document	The user's document appears to be a picture of a screen.
Document	The user's document appears to be manipulated.
Document	The user is requested to provide a valid document.
Document	The document appears to be a photocopy instead of an original.
Document + CURP	The user's CURP and the CURP on the document are not the same.
RFC	The RFC is listed as 'invalid' in the government registry.
Document	The name on the document does not correspond to the name associated with the document's CURP.
Selfie + Document	The person is associated with multiple identities.
Selfie	The user's face is covered and cannot be analyzed correctly.
Selfie + Document	The user's face in the selfie and the face in the document do not match.
Document	The user was found with different data across different documents.
Document	The face on the document was found with different data in other documents.
SDK	The face could not be verified as real.
Selfie + Document	Gender inconsistencies were found between the applicant's face and their CURP.
CURP or Document	The CURP does not match the information on the document.
CURP	The CURP is invalid according to the National Population Registry (RENAPO).
Selfie + Document	The applicant's face was found in the company with another external ID.
Selfie + Document	The person has been identified as an identity theft risk in the digital fraud bureau.
Address + Location	The location is within a designated risk zone.
IP	The IP address is linked to fraudulent internet activity.
IP	The IP address is reported as fraud in the Trully network.
Email	The email is linked to fraudulent internet activity.
Email	The email is reported as fraud in the Trully network.
Email	The provided email address is invalid.
Phone	The phone number is reported as fraud in the Trully network.
Phone	The number was not found on WhatsApp.
Phone	The phone number is linked to fraudulent internet activity.
Full Name or CURP	The user has been found on the CSONU list (Name match >=85%).
CURP or Full Name	The user has been identified as a possible Politically Exposed Person (PEP) (Name match >=85%).
IP	The user's IP originates from a country on the FATF (GAFI) list.
CURP or Full Name	The user has been found on a sanctions list (Name match >=85%).
CURP	The person has been sanctioned by the National Banking and Securities Commission (CNBV).

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

address
Request example: "Lote 12, México D.F. CP 01234 México"
- Where to find the response keys?
  - address_enrichment ->> geospatial
location
Request example: {"lat": 19.428437, "lng": -99.157011}
- Response keys:
  - enrichment ->> geospatial
curp
Request example: "TEST890919HNLNSR03"
- Response keys:
  - curp
  - listed_weeks
  - background_record
rfc
Request example: "MELM8305281H0"
- Response keys:
  - rfc
email
Request example: "[[email protected]]"
- Response keys:
  - social_media
  - external_fraud_service
phone_number
Request example: "+521234567890"
- Response keys:
  - phone_number
  - whatsapp
  - external_fraud_service
ip
Request example: "192.0.0.1"
- Response keys:
  - ip
  - external_fraud_service
device
Request example: "Apple iPhone 12 Pro Max"
- Response keys:
  - device
image
Request example: "iVBORw0KGg..."
- Response keys:
  - face_recognition
  - face_comparison
document_image
Request example: "/9j/4AAQSk..."
- Response keys:
  - document_ocr
document_image_back
Request example: "dAAQdsSk..."
- Response keys:
  - document_ocr

Response structure

data

raw_data
*See full raw_data in API reference:
https://docs.trully.ai/reference/api-responses
The raw data used behind the decision-making.
label
Example: "Potential Threat" (String)
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.
reason
Example: [] (Array)
Provides an array of reasons or explanations contributing to the decision outcome.
Full list of possible reason are attached in the Rule Engine:
- https://docs.trully.ai/docs/decision-maker#rule-engine
request_id
Example: "co25naa4sfqc701teds0" (String)
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.