Identity Onboarding

Entities hold the identity, business, risk and ownership information used to onboard an individual or business. Provider connections track verification and payment readiness for each provider.

Read the requirements endpoint instead of maintaining a fixed checklist: each provider can require different fields, documents, agreements and actions.

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 use another entity.

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}.

Use accurate customer data. Provider review can require clarification or additional evidence.

2. Connect the required providers

Create a connection with POST /v1/entities/{id}/providers/{code}. Use the provider catalog and API Reference for requested capabilities and provider-account selection. Providers using customer-owned credentials require an appropriate provider account before linking.

Provider availability differs between sandbox and production. A provider code in the API reference does not guarantee that the provider is available for your environment or route.

3. Read the live requirements

GET /v1/entities/{id}/requirements

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

• fields: profile values and validation state
• government_ids and government_id_clauses: identity-document requirements
• documents and document_clauses: supporting-document requirements
• actions: agreements, hosted verification or other customer actions
• followUpRequirements: additional requests from connected providers
• isReady.global and isReady.providers: readiness for the entity and each provider

Use field paths and action kind and code for application logic. Display provider messages as context rather than matching their wording in code.

4. Complete the requirements

Use entity, beneficial-owner, government-ID and document endpoints to provide missing information. Follow the typed resolution for hosted actions. A completed action can remain in the checklist with status VALID and no clickable resolution.

Government-ID metadata uses isRequired to distinguish mandatory fields from optional ones. For a front-and-back ID request, both images must belong to the same government-ID record. Where a request accepts alternative documents, choose one accepted alternative rather than uploading every listed type.

5. Submit and track readiness

Use the provider sync endpoints in the API Reference to submit the profile and documents. Re-read the provider connection and requirements afterward. Saving profile edits alone does not submit corrections to a provider.

Heron refreshes readiness for supported providers in the background. Updates are asynchronous: submitting documents or completing the checklist does not itself mean the provider approved the customer. Check the provider connection as well as isReady before offering payments.

Subscribe to provider_entity.status_changed for onboarding status changes. A provider can request more information without changing its overall status, so re-read requirements when resuming an onboarding flow. Webhooks are not a complete replacement for reading the current requirements.

Profile declarations

Source of funds and source of wealth

These are separate declarations:

• sourceOfFundsCode / sourceOfFundsDescription: the origin of money used for transactions.
• sourceOfWealthCode / sourceOfWealthDescription: how the customer accumulated their wealth.

sourceOfWealthCode accepts EMPLOYMENT, INVESTMENTS, SAVINGS, INHERITANCE, LOANS, FAMILY_SUPPORT or OTHER. Follow provider requirements for mandatory fields and supported choices; include a description when OTHER requires explanation. PATCH accepts null to clear a wealth field. Do not infer wealth from funds: salary can fund a transaction even when wealth came from inheritance.

For Due individual KYC, the checklist requires account purpose, expected monthly USD volume, occupation/job title and primary source of wealth. Complete the returned fields and submit the profile again; Due still makes the verification decision.

U.S. business EINs

businessProfile.taxIdentifier.value accepts nine digits (123456789) or the hyphenated form (12-3456789). Heron validates the format and assigned prefix and returns a normalized value. This does not verify issuance by the IRS or ownership by the business. Non-U.S. identifiers retain their country-specific punctuation.

Beneficial ownership

Provide accurate ownership percentages and representative roles. Where supported by the selected provider, corporate shareholders use entityType: "BUSINESS"; individuals use INDIVIDUAL. parentOwnerId identifies the corporate shareholder through which an owner holds shares, and ownershipPercent is relative to that parent. A parent must belong to the same business; ownership cycles and deleting a parent with children are not allowed. Provider support for corporate or nested ownership varies.

To clear a person's occupation, send occupationCode: null to PATCH /v1/entities/{id}/beneficial-owners/{ownerId}. Omitting the field leaves it unchanged.

Correcting provider-reported field issues

fields[].issues can include a stable code, message, providerCode and owner subjectId. Review the entire address when address feedback points to one component; the optional sourcePath identifies the affected address.

Save the correction, then explicitly submit it through:

POST /v1/entities/{id}/providers/{code}/sync/profile

hasPendingFieldCorrections indicates corrections still need submission. Saving a correction can remove the old field error without establishing provider acceptance. Unrelated or whitespace-only edits do not resolve a rejection. Removing an owner may require support if the provider cannot remove a previously submitted owner.

fieldIssueWarnings and hasUnattributedFieldIssues indicate feedback that cannot be assigned to one field confidently. Review the profile and use Resubmit profile when ready.

Follow-up requests and document delivery

followUpRequirements contains current provider requests (OPEN, SUBMITTED and REJECTED). Each has a requirement ID, instructions and known accepted document types. SUBMITTED means awaiting review, not accepted. Generic requests may arrive with instructions by email; do not assume they identify an exact document type.

Upload and categorize the file, then check eligible provider destinations:

GET /v1/entities/{id}/documents/{documentId}/provider-submission-eligibility

This returns available and disabled choices with a reasonCode. Provider support, document type, owner, format, size, connection readiness and existing deliveries can affect eligibility. If requiresRequirement is true, select a returned requirementOptions ID.

Submit the existing file with:

POST /v1/entities/{id}/document-submissions
Idempotency-Key: <stable request key>
Content-Type: application/json

{
  "assignments": [
    {
      "documentId": "<document id>",
      "providerCode": "<provider code>"
    }
  ]
}

Include requirementId on an assignment when sending against a specific request or when eligibility requires it. Otherwise, providers accepting unbound documents can receive an out-of-band submission. The connection's documentSubmissionMode reports INCREMENTAL or UNSUPPORTED.

A document categorized as OTHER needs a meaningful description. It can be sent without a specific document type only when the provider permits generic documents; it does not bypass a request's accepted types. In the dashboard, select the file and provider in the send dialog and review the listed files before confirming.

Interpret results and retry safely

The endpoint returns HTTP 200 with one result per assignment. Inspect every result: a successful HTTP response does not mean all files were delivered or accepted. Invalid request shapes, ownership or requirement links produce request-level 4xx errors.

• SUBMITTED means delivered to the provider, not approved.
• For an in-progress or retryable result, retain the original body and idempotency key. Check history and retry that same request rather than creating a new batch for unresolved files.
• For a terminal failure, inspect the error and correct the problem. A corrected assignment needs a new request and key; replaying the old key returns its original terminal result.
• If eligibility reports previous_submission_rejected or replacement_document_required, select an eligible replacement file. A new request does not necessarily mean the previous file was rejected; follow the provider's instructions.
• provider_document_submission_blocked means collection is not currently permitted. It does not by itself mean a replacement is needed. Wait until the provider permits collection before retrying.

Heron can retry interrupted delivery, but clients should retain their original request and key for their own recovery. If the provider account changes, review the destination before creating another submission. Do not assume a previous submission applies to the new account.

Retrieve delivery results and attempts through:

GET /v1/entities/{id}/document-submissions?latestOnly=true
GET /v1/entities/{id}/document-submissions/{submissionId}

The collection supports document, provider, requirement and status filters. Eligibility is advisory; the submit operation checks current readiness again. A provider's decision can change between the two calls.

Dashboard document workflow

Supporting Documents groups files by type and owner. Open a row to view requests, instructions, files and delivery history. A newer upload is not necessarily the file delivered to a provider. Files retained for submission history cannot be deleted.

Follow-up tasks offer a matching existing file or a new upload. A file can remain eligible for one provider while another is reviewing it. For a multi-sided ID request, sending one side does not complete the whole request. Continue tracking the provider decision after submission.

Integration guidance

• Re-read requirements after changing providers or capabilities.
• Keep identity documents and personal information out of application logs and analytics.
• Keep Heron IDs and provider readiness separate from your own customer status.
• Make onboarding resumable; review can take longer than one request.
• Never treat profile completeness, document upload or delivery as provider approval.

See the API Reference for request and response schemas.