🔌 API Introduction

This page has a quick introduction to our API reference specifications, with some details on the reports states and outcomes and the person/folder’s status.

Complete API Documentation 📚

For the full interactive API documentation with all endpoints, request/response examples, and the ability to test API calls directly, visit our BGC API Documentation.

Authentication 🔒

Authentication requires only the X-Api-Key header set up to your API key.

How to get an API Key 🔑

The API Key is the token you will need to authenticate at our systems. If you still need to get one, please contact us.

Reports states and outcomes

Every report executed goes through a series of states until completion. Possible state values are PENDING, PENDING_MANUAL_REVIEW (if enabled), COMPLETED, ERROR and INCOMPLETE. Each state might have an outcome PASSED, FAILED or INFO.

For a deeper insight on how the reports work, you can check the Reports States Workflow diagram in our guides.

States 📌

PENDING or PENDING_MANUAL_REVIEW

We are building the report details and outcome for you, waiting for sources to return with the checks results and reviewing the ones that requires human intervention from our experts team.

COMPLETED

Awesome! All checks were performed successfully and you should have your final outcome.

INCOMPLETE

Check the message inside the details of your report. Use Get reports details endpoint.

ERROR

Uh oh! Something went wrong while processing this report. You can try triggering a reports update or contacting our support team.

State	Description
PENDING	The first state of all reports when a person is created, updated or reports update is triggered. It means that the checks are being performed.
PENDING_MANUAL_REVIEW	Report is queued for Manual Review. It happens when automated checks have been performed, but the report needed a Manual Review (usually when there is a FAILED outcome from the automated checks).
COMPLETED	This state represents the report has completed all checks and should include a final outcome (PASSED or FAILED) or only the data requested (for reports with outcome BODY - no decision making).
INCOMPLETE	It means that the report was not able to complete for some reason: input provided was not valid or not found in the sources/databases, the data found was not enough to reach a final outcome under the rules provided.
ERROR	This state means something went wrong with the check: sources may have been down for too much time or an internal error at Emptor’s API has happened.

Outcomes ✅

Outcome	Description
PASSED	This outcome means that, under the rules provided by the customer (previously agreed upon or provided within the Create a Person request), no data was found to result in a FAILED outcome (e.g. no criminal records found).
FAILED	It means that, under the rules provided by the customer (previously agreed upon or provided within the Create a Person request), enough information was found to result in a FAILED outcome (e.g. criminal records found).
INFO	This outcome means that the report was requested as informational only and will be limited to return a set of data, not a decision making outcome like PASSED or FAILED.

Folder Status 🧾

The folder is, basically, the aggregate of all the reports enabled for a given Person. Unlike the reports, which have state and outcome, the folder only has a status which includes values both from the reports states and outcomes as described below.

The folder status is the same as the Person status, which you can retrieve by making a request to the Get a Person Status endpoint.

For a deeper insight on how the Folders work, you can check the Folders Status Workflow chart in the Guides.

Status	Description
PENDING	When all reports are in state PENDING.
PENDING_MANUAL_REVIEW	When there are reports in PENDING_MANUAL_REVIEW state.
PASSED	When all reports are in state COMPLETED and at none of them resulted in a FAILED outcome.
FAILED	When all reports are in state COMPLETED and at least one of them resulted in a FAILED outcome.
INCOMPLETE	When there are no reports in ERROR state, but at least one of them is in state INCOMPLETE.
ERROR	When at least one report is in ERROR state or if there was a problem computing the status.

Report Status Flow

For every report executed, it passes through a series of states until completion. Those states are PENDING, PENDING_MANUAL_REVIEW (if enabled), COMPLETED, ERROR and INCOMPLETE. Each state might have an outcome PASSED, FAILED or INFO. You can see the transition between states in the following diagram.

Folder Status Flow

After creating a person, updating a person, or triggering reports update, the folder status logic can be determined with the following diagram.

We’re here to help! 🙋‍♂️

If you have any questions, you can still contact us at support@emptor.io 📧.