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.