Customer Identities

Embarc lets you record multiple identity documents for each customer like
passports, national IDs, tax numbers, business registrations etc., so onboarding and
compliance processes stay centralised.

Step 1: Define Identity Types

Before you capture documents, create the allowable identity types. Typical
examples include “Passport,” “Driver Licence,” “National ID,” “Business
Registration.”

POST /codes/client_identification
{
  "name": "Passport",
  "description": "Government-issued passport"
}

You can manage these types through the Codes APIs. Every identity you capture
references one of these values.

Step 2: Attach an Identity to a Customer

Use the identifiers endpoint to record the document.

POST /clients/{clientId}/identifiers
{
  "documentTypeId": 42,
  "documentKey": "A12345678",
  "description": "Passport issued by US Department of State",
  "validity": "14 July 2030",
  "dateFormat": "dd MMMM yyyy",
  "locale": "en"
}

documentTypeId maps to the identity type you defined.
documentKey stores the unique number or reference printed on the document.
validity is optional; use it for expiration dates when applicable.

Update or delete identities via:

PUT /clients/{clientId}/identifiers/{identifierId}
DELETE /clients/{clientId}/identifiers/{identifierId}

Step 3: Store Supporting Files (Optional)

Each identity can hold supporting documents (scans, photos). Upload them with
the document APIs:

POST /clients/{clientId}/identifiers/{identifierId}/documents

Attach files as multipart form data. You can later fetch or update them if
regulations require periodic refresh.

Retrieval

List all identities for a customer: GET /clients/{clientId}/ identifiers
Fetch a specific identity: GET /clients/{clientId}/identifiers/ {identifierId}

The response includes type metadata, document keys, validity dates, and
references to any uploaded files.

Best Practices

Standardise identity types: Align document types with your compliance
policies to avoid free-form labels.
Capture validity dates: Track expiry so you can prompt customers for
renewals.
Secure attachments: Treat uploaded files as sensitive; restrict role
permissions accordingly.
Audit compliance: Identity creation, updates, and deletions
automatically appear in the audit log (/audits), making reviews
straightforward.

By combining identity types, the identifiers API, and optional document
uploads, Embarc keeps customer verification data centralized and audit-ready.