Skip to main content

Universal API Core Concepts

Welcome to the Universal API documentation from Blacktrust. To interact with our API correctly, it is essential to understand the entity hierarchy and how the information returned by the system is structured.

System Hierarchy​

Our architecture is based on three main interconnected components:

1. Client​

The Client represents the business entity that consumes the API. Each client has access credentials that validate its identity and restrict access to only the data and settings that belong to it.

2. Package​

A Package works as a strategic grouping. It acts as a container for business rules, custom validations, and a set of specific Processes (for example: "VIP Operations Package"). A single client can have multiple packages configured according to its needs. Security validates that a packageId belongs to the authenticated clientId.

3. Process​

Processes are the individual, modular validations that make up a package (Example: Identity Validation, BGC Legal, Credit Report).

Note: Throughout our documentation and architecture, we refer to these atomic services exclusively as Processes.

Interpreting Results​

The Universal API exposes different levels of detail to optimize performance and fit your asynchronous workflows. The response structure evolves from a surface-level status to complex technical data.

Request Overview​

This is the default response when querying the status of a uuid. It represents the overall status of the package and breaks down the list of individual Processes included, with their respective progress statuses.

  • Use: Determine whether an entire request is Pending, In Process, or Completed, and check the granular progress of each process.

Process Summary​

Provides the friendly, executive interpretation of a process once it is completed.

  • Use: Make direct business decisions (e.g. "No criminal record", "BC Score: 720").

Extended Technical Data​

Obtained exclusively by using the ?detail=true parameter. Returns 100% of the original payload provided by the scraping engine or integrated service, including all paginated records.

  • Use: Display a highly detailed visual interface or perform in-depth security audits.
Pagination required

Keep in mind that when querying the Process Summary or the Extended Technical Data, some processes (such as BGC Legal) may return extensive lists. You must prepare your UI to handle paginated information in alphabetical order.