# Business Holmes

Query official bureaus and Stark Infra's internal datasets to investigate a legal entity (CNPJ). Each request targets a specific bureau by `type` and returns that bureau's structured payload alongside a paging cursor.

Use Business Holmes to run KYB, judicial, anti-fraud, sanctions, QSA (corporate structure) and federal-revenue checks on a company before onboarding it, granting credit or releasing a high-risk operation.

Every call is synchronous, scoped to your workspace and logged on Stark Infra's side — there is no resource lifecycle to track.

NOTE: Read [Core Concepts](https://docs.starkinfra.com/get-started/core-concepts.md) before continuing this guide.

**RESOURCE SUMMARY**

**Business Holmes**Single GET endpoint that dispatches to one bureau per call and returns its raw, structured payload.

## Available Languages

Code samples on this page are in Python. The same content is available with samples in:

- [Python](https://docs.starkinfra.com/get-started/business-holmes-python.md)
- [Node.js](https://docs.starkinfra.com/get-started/business-holmes-node.md)
- [PHP](https://docs.starkinfra.com/get-started/business-holmes-php.md)
- [Java](https://docs.starkinfra.com/get-started/business-holmes-java.md)
- [Ruby](https://docs.starkinfra.com/get-started/business-holmes-ruby.md)
- [Elixir](https://docs.starkinfra.com/get-started/business-holmes-elixir.md)
- [.NET](https://docs.starkinfra.com/get-started/business-holmes-dotnet.md)
- [Go](https://docs.starkinfra.com/get-started/business-holmes-go.md)
- [Clojure](https://docs.starkinfra.com/get-started/business-holmes-clojure.md)
- [cURL](https://docs.starkinfra.com/get-started/business-holmes-curl.md)

## Setup

For each environment (Sandbox and Production):

1. Create an account at Stark Bank.

2. Get in touch with your account manager to enable Business Holmes on your workspace — each bureau is contracted independently, so let us know which `type` values you intend to use.

3. Have the CNPJ you want to investigate ready in unmasked or masked form — Stark Infra normalizes both before sending it to the bureau.

4. Generate your ECDSA credentials by following [How to Create ECDSA Keys](https://docs.starkinfra.com/how-to-create-ecdsa-keys.md) and authenticate every request with the `Access-Id`, `Access-Time` and `Access-Signature` headers.

## Business Holmes Overview

Business Holmes investigates a company (CNPJ) against an external bureau or an internal dataset. Every request targets a specific bureau by `type`; the response wraps the bureau's raw payload under a key named exactly after the `type` you queried.

All bureaus are queried through the same endpoint signature, with the same validation pipeline and the same paging contract. Only the two JusBrasil bureaus — `civil` and `criminal` — return a real `cursor`; every other bureau returns `null`.

### Query a Business Bureau

`GET /business-holmes/:taxId/:type`

Path params identify what to look up. The `taxId` is the company's CNPJ (14 digits, masked or unmasked); the `type` selects the bureau and the shape of the response.

Query params control paging. Only `civil` and `criminal` honour `cursor` — repeat the request with the returned cursor to fetch the next page.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `taxId` | REQUIRED | CNPJ of the company being investigated, masked or unmasked. Example: `20.018.183/0001-80`. |
| `type` | REQUIRED | Bureau to query. Options: `civil`, `criminal`, `kyc`, `frauds`, `data`, `dict`, `jointResolution6`, `federalRevenueRegistry`, `negativeMedia`, `qsa`. |
| `limit` | OPTIONAL | Maximum number of items per page for paginated bureaus. Integer in the `1..100` range. Defaults to `100`. |
| `cursor` | OPTIONAL | Opaque page token returned by the previous call. Only meaningful for `civil` and `criminal`; ignored by every other bureau. |

### Response Envelope

Every successful response carries the bureau's payload under a key named after the `type` queried, plus a `cursor` field. The concrete envelope for each bureau is shown in the sections below.

**Cursor semantics:** populated only for `civil`/`criminal`. `null` for every other bureau.

### Civil Lawsuits

Civil lawsuits sourced from JusBrasil. Paginated — repeat with the returned `cursor` until `null`. Returns a list of processes; `typification` is always `[]` for civil.

### Criminal Lawsuits

Same JusBrasil source as civil. Returns a list of processes with the same shape, but the `typification` field is populated with the criminal codes invoked.

### KYC

BigDataCorp `empresas/kyc` dataset. Not paginated. Empty result returns `{}`. The `history[]` is filtered to entries with `matchRate >= 80`.

**Note:** the legacy `sanctions` bureau is an alias for this one and returns the same payload. Prefer `kyc` in new integrations.

### Fraud Score

Quod anti-fraud score for the CNPJ. Not paginated.

### Business Data

BigDataCorp business profile, assembled from `ondemand`, `empresas/relationships` and (conditionally) `empresas/basic_data` when the legal nature matches MEI. Not paginated. Empty result returns `{}`.

**Note:** the legacy `activity` bureau is an alias for this one and returns the same payload. Prefer `data` in new integrations.

### Pix User

Looks the CNPJ up on Stark Infra's internal Dict (Pix directory) microservice. Returns the raw `user` object on success.

### Joint Resolution 6

Quod's RUFRA block, used to comply with Brazilian Joint Resolution 6 (BCB/CMN). Not paginated.

### Federal Revenue Registry

BigDataCorp `empresas/basic_data` dataset, used to confirm the CNPJ's status with the Receita Federal. Not paginated.

### Negative Media

BigDataCorp `empresas/media_profile_and_exposure` dataset. Not paginated. Empty result returns `{}`.

### Corporate Structure / QSA

BigDataCorp `empresas/dynamic_qsa_data` dataset, exposing the company's QSA — the list of partners and administrators (Quadro de Sócios e Administradores). Not paginated. Empty result returns `{}`.