Customer Management

Every borrower and co-borrower lives in Embarc as a customer. Understanding the customer lifecycle and how it relates to loans helps you design onboarding, servicing, and reporting workflows that align with the platform.

Lifecycle Diagram

flowchart TD
    A[Draft] -->|submit| B[Submitted]
    B -->|activate| C[Active]
    B -->|withdraw| D[Closed – Withdrawn]
    B -->|reject| E[Rejected]
    C -->|close| F[Closed]
    C -->|deactivate| B
    D -->|reopen| B
    E -->|reapply| B

Customer Lifecycle

Draft (optional)
- Capture intake data while the record remains private.
- Handy when you gather documents or approvals before exposing the profile to downstream users.
Submitted
- Created via POST /api/v1/clients.
- At this stage you can attach documents, KYC information, and initiate loan applications.
Active
- Achieved through activation commands (for example POST /api/v1/clients/ {id}?command=activate).
- From here you can attach multiple loans, schedule repayments, and assign loan officers.
- Updates to demographics, contact details, and identifiers can happen at any time.
Closed / Withdrawn / Rejected
- Closed: customer exited the programme and holds no active facilities.
- Withdrawn: onboarding stopped before activation.
- Rejected: onboarding denied; the record stays for audit but cannot initiate new loans until reactivated.
- Embarc records timestamps and actors for each status change for audit and analytics.

Customers and Loans

One-to-many: A single customer can hold multiple loans simultaneously— top-ups, parallel facilities, or different products.
Loan creation: Supply the clientId when you call POST /api/v1/loans; all servicing for that loan uses the same ID.
Visibility: GET /api/v1/clients/{id}?associations=all returns linked loans, making it easy to show balances and arrears in a customer dashboard.
Business rules: Enforce your credit policies before creating additional loans; Embarc does not hard-cap facilities per customer.

Core APIs

Action	Endpoint	Notes
Create customer	`POST /api/v1/clients`	Provide demographics, identifiers, office assignment.
Update customer	`PUT /api/v1/clients/{id}`	Adjust contact info, KYC data, or custom fields.
Activate	`POST /api/v1/clients/{id}?command=activate`	Moves Submitted →Active
Close	`POST /api/v1/clients/{id}?command=close`	Only when no active loans remain.
Fetch with loans	`GET /api/v1/clients/{id}?associations=all`	Includes loan summaries, recent transactions, staff info.

Best Practices

KYC first: Gather required documentation before activation so loan applications aren’t blocked later.
Assign ownership: Use staff/loan officer fields for task routing and collections tracking.
Track churn: When closing or rejecting a customer, capture the reason (notes or custom fields) for analytics.
Keep records clean: Reactivate or recreate customers instead of duplicating active IDs to avoid servicing confusion.

Embarc treats the customer as the central hub for every product relationship. Keep customer states in sync with your onboarding journey, and you can associate as many facilities as each customer qualifies for without friction.