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:

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.