Ingest API Start Here

One Endpoint

Send every event to POST /ingest.

POST /ingest
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

Request Shape

Every request has same envelope:

{
  "category": "client",
  "data": {
    "step": "create"
  }
}

category chooses payload type. data.step chooses action.

Accepted Categories

Category	Use it for	Key links
`client`	Individual and company records	Referenced by loan disbursements and purchase allocations.
`disbursement`	Loan and purchase financing	Parent for payments and optional operation tracking.
`payment`	Expected, paid, and canceled payments	References `disbursement_id`.
`operation`	Additional underlying operation or asset tracking	References `disbursement_id`.

Recommended Flow

1. Create client (if applicable)

2. Create disbursement (loan or purchase linked to clients)

3. Add payment events for scheduled and received money.

4. Add operation only when you need to track the underlying operation or asset.

Minimal Complete Request

{
  "category": "client",
  "data": {
    "step": "create",
    "client_id": "BR-2024-001",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "address": "123 Main St, New York, NY 10001",
    "country": "US",
    "is_company": false,
    "registration_number": "ID-1234567890",
    "gender": "male"
  }
}

Company clients use the same endpoint. When is_company is true, send contact_person; gender may be omitted and is stored as company.

{
  "category": "client",
  "data": {
    "step": "create",
    "client_id": "COMP-2024-001",
    "name": "Acme Trading LLC",
    "email": "finance@acme.example",
    "phone": "+15550001031",
    "address": "100 Market Street, New York, NY 10001",
    "country": "US",
    "is_company": true,
    "registration_number": "REG-COMPANY-001",
    "contact_person": "Jane Smith"
  }
}

Idempotency

Use a new Idempotency-Key for each new event. If same key is sent again, API returns duplicate response instead of creating another event.

{
  "status": "duplicate",
  "message": "Event already processed"
}

Quick Checks

category must be one of client, disbursement, payment, operation.
data.step must be create, update, or delete.
Individual client creates require gender; company client creates require contact_person and do not require gender.
disbursement.kind must be loan or purchase.
payment.status must be expected, paid, or canceled.
Old categories such as loan, purchase, schedule, insurance, write_off, asset_status, and disbursement_status are not accepted as top-level /ingest categories.
Updating a missing row returns 404; unknown parent references return validation errors.