Identity Onboarding

Entities hold the identity, business, risk, ownership, and verification information used to onboard an individual or business. Provider connections attach that entity to the payment providers it needs.

Requirements are provider-aware. Adding a provider can introduce new fields, documents, agreements, or actions, so clients should read the requirements endpoint instead of maintaining a fixed checklist.

Entity model

An entity has an entityType of INDIVIDUAL or BUSINESS and may include:

• an individual or business profile
• a risk profile and expected activity
• government IDs and supporting documents
• beneficial owners for businesses
• one or more provider connections

An organization can designate one entity as primary. Pass the entity id explicitly when a quote, transfer, or provider operation should run in another entity's context.

Onboarding workflow

1. Create or select the entity

Create an entity with POST /v1/entities, or use GET /v1/entities/primary when the organization's primary entity is the customer being onboarded. Update profiles with PATCH /v1/entities/{id}.

Start with accurate customer data. Do not submit invented values to satisfy a required field; provider review can request clarification or additional evidence.

2. Connect the required providers

Create a provider connection with POST /v1/entities/{id}/providers/{code}. Requested capabilities and account selection vary by provider, so use the provider catalog and API Reference for the connection payload.

Provider availability is environment-specific. A provider enabled in sandbox is not necessarily enabled for production traffic.

3. Read the live requirements

Call:

GET /v1/entities/{id}/requirements

Use the optional providers query parameter to scope the checklist. The response separates:

• fields: profile values and their validation state
• government_ids and government_id_clauses: identity-document requirements
• documents and document_clauses: supporting-document requirements
• actions: agreements, fiat-account registration, hosted KYC, or other user work
• isReady.global: whether the entity is globally ready
• isReady.providers: readiness for each connected provider

Treat field paths, action kind, and action code as machine-readable values. Display provider messages as supporting context rather than branching application logic on their wording.

4. Complete fields, ownership, documents, and actions

Use the entity, beneficial-owner, government-ID, and document endpoints to resolve missing items. For hosted actions, follow the typed resolution returned by the requirements endpoint.

An action may remain in the response with status VALID after completion even when it no longer has a clickable resolution. Provider-side pending or review state appears on the provider connection; it is not automatically another customer action.

5. Submit and track provider readiness

Use the provider sync endpoints documented in the API Reference when the integration needs to push the entity profile or documents, then read the provider connection and requirements response for the resulting state.

Subscribe to provider_entity.status_changed to receive provider onboarding changes. Webhook delivery is asynchronous, so retrieve the latest entity or provider connection before making a final workflow decision.

Integration guidance

• Re-read requirements after changing providers or requested capabilities.
• Keep uploaded identity material out of application logs and analytics events.
• Store Heron ids and provider-connection state separately from your own customer status.
• Expect review states to last longer than a single request and make the workflow resumable.
• Do not infer transfer readiness from profile completeness alone; use isReady and the selected provider connection.

For request and response schemas, see the entity and entity-provider sections of the API Reference.