Dates, Timestamps, and Numbers

Consistent formatting keeps Embarc integrations predictable. This guide
explains how the API represents calendar dates, full timestamps, and numeric
values.

Dates

• Timezone: All date-only fields (e.g., disbursement dates, due dates,
  customer birth dates) are interpreted in the tenant’s timezone. The tenant
  timezone is configured centrally; no extra header is required.

• Format: Responses typically render dates as [YYYY, MM, DD] arrays
  or ISO strings depending on the endpoint. When posting dates, include
  dateFormat and locale to avoid ambiguity:

  JSON

  {
    "disbursementDate": "13 October 2025",
    "dateFormat": "dd MMMM yyyy",
    "locale": "en"
  }

  You may also use ISO ("2025-10-13") if you prefer; just set dateFormat
  accordingly.

• Business logic: Interest accrual, delinquency ageing, and schedule
  generation all rely on tenant-local dates, so supply accurate local values
  when creating or updating records.

Timestamps

• Timezone: All timestamps (e.g., createdOn, audit logs, repayment
  posting times) are stored and returned in UTC.
• Format: Embarc uses ISO 8601 (YYYY-MM-DDTHH:MM:SS[.SSS]Z). Example:
  "2025-10-13T07:45:12Z".
• Conversion: Convert to the user’s local timezone on the client side if
  needed. The API will not adjust timestamps per user.

Numbers

• Decimal separator: Use a dot (.). Example: "principal": 10000.50.
• Currency precision: Currency amounts are represented with the precision
  defined for the tenant’s currency (often 2 or 4 decimal places). Do not send
  amounts with thousands separators.
• Integers: Provide plain integers for quantities (e.g., number of
  instalments). Avoid strings unless the field explicitly requires one.

Best Practices

1. Always send dateFormat + locale when you post dates. This avoids
   parsing errors and keeps future API versions compatible with your integration.
2. Normalize timestamps client-side. Store them in UTC or convert them to
   the user’s timezone after reading from Embarc.
3. Validate numeric inputs before calling the API. Reject invalid
   characters (commas, spaces) to prevent 400 responses.
4. Log raw API payloads. When troubleshooting, the exact values returned
   by the API (especially timestamps) help support determine whether an issue is
   due to timezone handling or business logic.

Handle dates, timestamps, and numbers with these rules and your integration
will remain accurate across tenants, environments, and timezones.