canonical: https://jentic.com/apis/binderr.com/binderr

# Binderr API

Jentic publishes the only available OpenAPI specification for Binderr API, keeping it validated and agent-ready. The Binderr API is the programmatic interface to the Binderr KYC, KYB, and client-onboarding platform, exposing 51 endpoints to manage entities (individuals and legal entities), upload and retrieve identity documents, model shareholder structures and involvements, send and receive onboarding forms, run screening and ongoing monitoring, and subscribe to webhooks. Authentication is OAuth-style: an access token is obtained from `/public/v1/oauth/access-token` and supplied as a JWT bearer token, refreshable via `/public/v1/oauth/refresh-token.`

## For AI agents

Onboard individuals and legal entities, upload and verify identity documents, model shareholders, and run screening through the Binderr KYC and KYB platform.

## Scope

Does not handle payment processing, accounting, or customer support ticketing - use for KYC, KYB, identity-document collection, screening, and ongoing monitoring only.

## Capabilities

- Create and search entities (individuals or legal entities) and link them via involvements and roles
- Model shareholder structures with POST `/v1/entity/{entityId}/shareholder` and retrieve the full structure
- Upload, retrieve, and delete identity and supporting documents per entity
- Send onboarding forms to an entity and process incoming form submissions
- Run AML and sanctions screening on entities and toggle ongoing monitoring
- Subscribe to webhooks for entity, document, and verification events
- Issue and refresh OAuth-style access tokens to authenticate subsequent requests

## Use cases

### Corporate Client Onboarding (KYB)

Regulated firms onboarding corporate clients need to capture the legal entity, its directors and shareholders, and supporting documents in a structured way. The Binderr API exposes POST `/v1/entity` for creation, POST `/v1/entity/{entityId}/shareholder` for ownership structure, POST `/v1/entity/{entityId}/involvements` for directors and signatories, and POST `/v1/document/for-entity/{entityId}` for incorporation and identity documents. Setup is typically one to two weeks for a full onboarding flow.

Example prompt: Create a legal entity for Acme Holdings Ltd via POST `/v1/entity`, add two directors via POST `/v1/entity/{entityId}/involvements`, and record a 60/40 shareholder split via POST `/v1/entity/{entityId}/shareholder.`

### AML Screening and Ongoing Monitoring

Compliance teams must screen new and existing entities against sanctions and PEP lists, then keep them under ongoing monitoring. The Binderr API exposes POST `/v1/verification/screening/entity/{entityId}` for one-off screening and POST `/v1/verification/screening/entity/{entityId}/ongoing-monitoring` to toggle continuous monitoring, plus GET `/v1/risk/entity/{entityId}/reviews` for the resulting review records. Setup is typically three to five days for a screening pipeline.

Example prompt: Run a fresh screening on entity ID 5544 via POST `/v1/verification/screening/entity/{entityId}`, then enable ongoing monitoring with the toggle endpoint.

### Form-Based Document Collection

Onboarding teams send structured forms to clients to collect information and documents. Binderr exposes POST `/v1/form/{formId}/to-entity/{entityId}` to send forms, POST `/v1/form/submit/{linkId}` to ingest submissions, and GET `/v1/form/sent` to track which clients still owe a response. This avoids stitching together a separate form vendor with a KYC tool. Setup is typically two days for a single form template.

Example prompt: Send form ID 12 to entity ID 5544 via POST `/v1/form/{formId}/to-entity/{entityId}`, then poll GET `/v1/form/sent` until the form is marked submitted.

### Webhook-Driven Compliance Workflow

Compliance ops teams want their case management to react instantly to verification and document events. The Binderr API exposes `/v1/rest/webhook` to list, subscribe, test, and unsubscribe webhooks per event type, so a downstream system can be notified the moment an entity's verification status or document changes. Setup is typically one day per event type.

Example prompt: Create a webhook subscription on the entity-verification-completed event via POST `/v1/rest/webhook/{event}/subscribe` pointing at the local case-management endpoint.

### AI Agent KYC Assistant via Jentic

An AI assistant for compliance teams can onboard entities, run screenings, and chase missing documents from natural-language requests routed through Jentic. The Binderr access token and refresh token sit in your Jentic One instance, so the agent never sees the raw credentials. Search-load-execute through Jentic gets the integration live in under an hour.

Example prompt: Search Jentic for 'run a Binderr screening', load the POST `/v1/verification/screening/entity/{entityId}` schema, and execute it for the supplied entity ID.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/entity` | Create a new entity (individual or legal entity) |
| POST | `/v1/document/for-entity/{entityId}` | Upload a document for an entity |
| POST | `/v1/entity/{entityId}/shareholder` | Add or update a shareholder on an entity |
| POST | `/v1/verification/screening/entity/{entityId}` | Run AML and sanctions screening on an entity |
| POST | `/v1/form/{formId}/to-entity/{entityId}` | Send an onboarding form to an entity |
| POST | `/v1/rest/webhook/{event}/subscribe` | Subscribe to a webhook event |
| POST | `/public/v1/oauth/access-token` | Request a new access token |
| POST | `/public/v1/oauth/refresh-token` | Refresh an expired access token |

## Key resources

- **Authentication** — Issue and refresh OAuth-style access tokens via `/public/v1/oauth` endpoints
- **Account** — Retrieve current user and team information
- **Entity** — Create, search, retrieve, update, and delete individuals and legal entities; manage industries, services, and relationships
- **Document** — Upload, retrieve, delete, and thumbnail documents per entity
- **Involvements and Shareholders** — Model directors, signatories, and ownership structure on legal entities
- **Form** — Send onboarding forms and process submissions
- **Verification and Risk** — Run screening, manage ongoing monitoring, and read entity reviews
- **Webhook** — List, subscribe, test, and unsubscribe webhooks per event

## Why Jentic

- **Setup:** Wiring the Binderr API by hand means running its OAuth access-and-refresh-token flow, choosing between the binderr.dev and binderr.com hosts, and refreshing tokens yourself across KYC and screening calls. Through Jentic you install once, import Binderr from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** Binderr puts the entity id in the URL path (`/v1/entity/{entityId}/...`), so a rule can pin your agent to one entity: it can collect documents and run screening for that entity and nothing else. You choose the operations it may call, so actions like webhook subscription are not included unless you add them.
- **Credential handling:** Your Binderr OAuth credentials are stored once, encrypted, by your own Jentic One instance, which mints and refreshes the tokens and injects them at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'run a Binderr screening' or 'add a shareholder to an entity', and Jentic returns the matching Binderr operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Onfido** — Identity verification platform focused on document and biometric checks
- **Sumsub** — Verification platform with KYC, KYB, and AML screening
- **Stripe** — Payments processor that pairs with Binderr after onboarding completes
- **Billsby** — Subscription billing platform that pairs with Binderr-verified customers

## FAQ

### Why is there no official OpenAPI spec for Binderr API?

Binderr does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Binderr API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Binderr API use?

The Binderr API uses HTTP bearer authentication with a JWT access token. Tokens are issued by POST `/public/v1/oauth/access-token` and refreshed by POST `/public/v1/oauth/refresh-token.` When called via Jentic, both tokens are held in your Jentic One instance, and refresh is handled server-side so the agent never sees the raw credentials.

### Can I onboard a corporate client and capture its shareholders through the Binderr API?

Yes. POST `/v1/entity` creates the legal entity, POST `/v1/entity/{entityId}/involvements` adds directors and signatories, and POST `/v1/entity/{entityId}/shareholder` records ownership. GET `/v1/entity/{entityId}/shareholder/structure` returns the full structure for review.

### What are the rate limits for the Binderr API?

The published Binderr documentation states all APIs are rate-limited to 100 requests per second. The Jentic SDK retries on 429 responses with back-off, so high-volume onboarding jobs do not have to handle this manually.

### How do I run a screening on an entity through Jentic?

Search Jentic for 'run a Binderr screening', which surfaces POST `/v1/verification/screening/entity/{entityId}.` Load the schema, supply the entity ID, and execute. The Python flow is: pip install jentic, then await client.search, await client.load, await client.execute.

### Can I receive webhooks for entity and verification events?

Yes. POST `/v1/rest/webhook/{event}/subscribe` creates a subscription for a specific event type, GET `/v1/rest/webhook` lists active subscriptions, and POST `/v1/rest/webhook/{event}/test-data` lets you send sample payloads when wiring up handlers. Subscriptions are removed via DELETE `/v1/rest/webhook/{event}/unsubscribe/{id}.`

### Can I limit what my agent is allowed to do with the Binderr API?

Yes. Because you run Jentic One yourself, your own rules decide which Binderr operations and credentials the agent may use. Binderr puts the entity id in the URL path (`/v1/entity/{entityId}/...`), so a rule can pin the agent to a single entity and let it only collect documents via POST `/v1/document/for-entity/{entityId}` and run screening via POST `/v1/verification/screening/entity/{entityId}` for that entity. You choose the operations it may call, so actions like subscribing to webhooks through POST `/v1/rest/webhook/{event}/subscribe` stay off unless you grant them.