External Identifiers

External IDs give you a stable bridge between Embarc records and your upstream
systems (CRM, underwriting, payment processors). Almost every major entity including
customers, loans, documents etc. supports an externalId field.

Why Use External IDs?

Alignment with your source system: Reference an Embarc loan as LOAN- 12345 or a customer as CRM-9987 without storing internal IDs.
Simplified lookups: Many APIs let you fetch or update records purely by
external ID (e.g., GET /api/v1/clients/external-id/{externalId}).
Deduplication guard: Because Embarc enforces uniqueness per entity type,
External IDs help prevent you from creating the same record twice.

Where They Appear

Entity	Example fields	API shortcuts
Customers	`externalId` on create/update	`GET /api/v1/clients/external-id/{externalId}`
Loans	`externalId` on application; passes through lifecycle	`GET /api/v1/loans/external-id/{externalId}`
Documents & attachments	`externalDocId` when uploaded	Fetch/upload by external doc ID for easier referencing

Best Practices

Make them unique per entity type. Embarc rejects duplicates under the
same tenant.
Treat them as immutable identifiers. You can update external IDs, but
do so sparingly to avoid breaking links in downstream systems.
Use your own namespace. Prefix or structure IDs so they’re clearly
sourced (e.g., CRM-CUST-1234, CORE-LOAN-765).
Fallback to internal IDs when necessary. Internal numeric IDs never
change and exist in every response; log them alongside your external IDs.

Example: Creating a Loan with External ID

POST /api/v1/loans
{
  "clientId": 9876,
  "productId": 5,
  "principal": 10000,
  "externalId": "LOAN-2025-001",
  "submittedOnDate": "15 March 2025",
  "dateFormat": "dd MMMM yyyy",
  "locale": "en"
}

Later you can fetch it with:

GET /api/v1/loans/external-id/LOAN-2025-001

and use the same identifier in your accounting or CRM systems.

External IDs keep your integrations clean: you control the naming, Embarc
guarantees uniqueness, and the API gives you first-class support for create,
update, and lookup operations across the platform.