Estimated reading time: 15-20 minutes

What will you learn from this guide?

That manual will teach you how to use the blackList's JAAKwith BlackList, you can check people and entities against different national and international databases and risk lists, and this is crucial to your "Know Your Customer" processes (KYC) and prevention of money laundering (AML) as well as helping to mitigate risks of abetting an identity.

No prior technical knowledge required - just follow the steps.

Before Start - Checks list

Be sure to have these data ready:

• API Key (Token Bearer): Your valid authentication key provided by JAAK. It's essential to get our services.
• Data of the person or entity to be investigated: Name, family name, identification (CURP, RFC, CIC, OCR of INE) and optionally, address and date of birth.
• Basic knowledge of APIs REST: familiarity with how HTTP (POST, GET) applications are made and JSON responses are processed.

Contents Index

1. What's BlackList Verification?

The Black List Verification (BlackList) system of JAAK It allows you to consult and verify information from individuals and entities about different risk databases. That includes government lists, international sanctions, wanted criminals and taxpayers with tax irregularities.

Purpose and Benefits

• Fraud prevention: It identifies individuals or companies that may represent a risk of fraud, money laundering or financing terrorism.
• Normative compliance: Help your company meet its Customer Know Regulations (KYC) and Anti Money Laundering (AML).
• Risk mitigation: It reduces the risk of association with entities or persons involved in illicit activity.
• Identity Validation: It complements identity checks by matching an individual's data with risk records.

2. Key functionality

Our BlackList product offers the following main capabilities:

• MultiService Consultation: It allows to simultaneously verify against several national and international blacklists in a single application.
• Integrated Services:
  • INE (Mexico): Verification of elector's credentials
  • INTERPOL (International) Consultation of international Red Lists
  • OFAC (USA): U.S. Office of Foreign Assets Control Sanctions list
  • RENAPO/CURP (Mexico): Verification of Unique Population Registration Key
  • SAT69B (Mexico): List of contributors with non-existent or simulated operations
  • CDC RccFico (Mexico): Development module for Credit Circle
• Detailed results: Provides if person was foundInService (found on the list), a score and message Research.
• Record of Events: Keep a complete and detailed record of each research conducted for audit and monitoring purposes.
• Input flexibility: It allows research using different person information: name, name, address and identifications (CURP, RFC, CIC, OCR).

3. Integration with API

The interaction with the BlackList system is performed through calls to our API.

3.1 Research endpoint

POST / api / v2 / blacklist / investigate

That's the main endpoint for an investigation into blacklists.

• Method: POST
• Base URL: https://api.sandbox.jaak.ai/api/v2/blacklist/investigate
• Required Headers:
  • Authorization: Bearer TU_API_KEY_AQUI (Your authentication key)
  • Content-Type: application/json
  • Language: (Optional) es or en for the language of error messages

Application body (JSON)

The request includes two main sections: services and payload.

1. services (Purpose - Required)

Here you define what blacklist services you wish to consult. At least one should be active (true).

2. payload (Purpose - Required)

It contains information about the person or entity to be investigated. You have to provide information relevant to the service (s) you activated.

• person(Purpose): Name, name, date of birth, nationality
• address(Purpose): Management details (street, number, colony, municipality, state, postal code)
• identifications(Purpose): Key identifiers as curp, rfc, socialSecurityNumber, electorKeyStop. INEincludes cic and ocr
• extras(Purpose): Additional fields as commonId or wantedIn

Example of application INE

{
  "services": {
    "ine": true
  },
  "payload": {
    "identifications": {
      "ine": {
        "cic": "1234567890123",
        "ocr": "1234567890123456789"
      }
    }
  }
}

Successful Response (HTTP Status: 200 OK)

The answer includes a eventId for monitoring, processTime (time in seconds), organization and service The object state It's crucial as it indicates:

• foundInService: true if a coincidence was found at the service referred to, false Otherwise
• message: A descriptive message about the research outcome
• result: Contains details of coincidence if foundInService It's true

Example of success (INE - Unfound)

{
  "eventId": "a9fd763a-f2b8-4908-8ded-ed81e27b4169",
  "processTime": 27.89,
  "organization": "ine",
  "service": "identification",
  "result": null,
  "state": {
    "message": "Investigation completed successfully",
    "foundInService": false,
    "mustBeFound": true
  }
}

Successful response example (SAT69B - Found)

{
  "eventId": "caf144b8-cca5-413c-b546-8a7ce5de8ed1",
  "processTime": 0.19,
  "organization": "sat",
  "service": "sat69b",
  "result": {
    "0": {
      "content": {
        "rfc": "PELJ721031GV0",
        "taxpayerName": "_",
        "taxpayerStatus": "Definitivo"
      }
    }
  },
  "state": {
    "message": "Investigation completed successfully",
    "foundInService": true,
    "mustBeFound": false
  }
}

3.2 Important Research Considerations

• Relevant data: Provides as much information as possible with precise information about payload to improve search accuracy.
• Active Services: It activates only the blacklist services you really need to optimize response time.
• Multiple Responses (SAT69B): Some services such as SAT69B can return multiple searches if they find several matches.

4. Monitoring of Events

The details of black list research for audit, results analysis and problem solving are available.

4.1 Consultation of Special Event by ID

NET / api / v2 / blacklist / event /: id

To get complete details of a specific research using the event ID as part of the URL.

• Method: GET
• Base URL: https://api.sandbox.jaak.ai/api/v2/blacklist/event/:id (where :id That's his eventId )
• Required Headers:
  • Authorization: Bearer TU_API_KEY_AQUI
  • Content-Type: application/json

Optional Consultation Parameters (Query Params)

• includePayload: boolean (optional). trueand the response shall include payload original of the application.
• includeAnalysis: boolean (optional). trueThe response shall include a detailed analysis of coincidences.

Successful response

The answer is a detailed JSON object that includes eventId, status Research and service consulted, processTimeand an item state with foundInService, confidence and riskLevel. Can also contain person (information of person consulted), analysis (details of matching and recommendation) and payload (if requested).

Example of response

{
  "success": true,
  "data": {
    "eventId": "evt_1234567890123456789",
    "status": "completed",
    "service": "ine",
    "state": {
      "foundInService": true,
      "confidence": 0.95,
      "riskLevel": "high"
    },
    "analysis": {
      "recommendation": "deny"
    }
  }
}

4.2 Consultation of Events

NET / api / v2 / blacklist / event

The endpoint allows you to filter and get a pawned list of all blacklist research.

• Method: GET
• Base URL: https://api.sandbox.jaak.ai/api/v2/blacklist/event
• Required Headers: Authorization: Bearer TU_API_KEY_AQUI, Content-Type: application/json

Consultation parameters (Query Params)

5. Common Problem Resolution

Here are some common problems and their solutions:

Error 400 - Invalid Application

Description: Input by error code BL02 or BL03. It happens if no service is active at the request, or if data required for a specific service are missing (e.g. INE without CIC/OCR). It can also indicate malformed JSON format.

solution:

1. Checkservices: Make sure at least one service is established at true
2. Checkpayload: includes all necessary data for activated service (e.g. for INE, CIC and OCR are required)
3. Check the JSON structure of your request

Error 403 - Failed Authentication

Description: The API Key's an invalid, expired, or you don't have the permission to have access to blacklist services. (Code: 0003)

solution:

1. Check API Key: Confirm that you API Key be right and be active on your dashboard JAAK
2. Format: Make sure the head Authorization be correctly formatted: Bearer TU_API_KEY_AQUI
3. Permissions: Contact support to check that your API Key have the necessary permission to Blacklist Product

Error 404 - Unfound event

Description: When viewing an ID-specific event, the system indicates that the event does not exist or belong to your company. (Code: BL_EVENT_NOT_FOUND)

solution:

1. Check ID: Make sure his eventId be right and have the format evt_[19 caracteres alfanuméricos]
2. Ownership: confirms that eventId corresponds to an investigation conducted under your account
3. Expiration: The events could expire; check more recent events if possible

Timeout at the Request

Description: The request is cancelled because the processing exceeds the time limit (recommended 30 seconds). That can occur if there are high load at service or at payload That's very complex.

solution:

1. Optimizes services: It activates only strictly necessary services
2. Reattempts: Implement a Retirement logic with an exponential waiting time (Reby with exponential backoff)
3. Support contact: If timeouts persist, there may be performance problems with the server

Error BL04 Invalid Service

Description: You have specified a service name that isn't supported by API.

solution:

1. Check the table of services supported by Section 3.1
2. Make sure that service names are correctly written (e.g. ine, interpol, ofac, renapo, sat, cdc)

6. Do you need some help?

Do not hesitate to contact our support team (support) if:

• The problem solving steps do not solve your drawback after multiple attempts
• Undocumented or unexpected errors
• Do you have to enable specific functionality for your company or require information about the status of services (e.g. INTERPOL, CDC RccFico)
• Experiments with persistent performance problems or data inconsistencies

Information to have ready at contact with support

• Special description of the problem
• Steps you followed before the mistake
• Event ID Failed request (if available)
• Full bug logs with timprints
• Current your request configuration (without including your API Full Key)
• The environment where the problem occurs (development, stacking, production)

7. Glossary of terms

Reference links

• Documentation API - POST / api / v2 / blacklist / investigate
• Documentation API - GET / api / v2 / blacklist / event
• Documentation API - GET / api / v2 / blacklist / event /: id
• RFC 7159 - Specification of JSON format
• ISO 8601 - Date and time format
• CURP - Official documentation of CURP in Mexico