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.