Response shapes & data models

Successful responses include status, a human-readable message, and a data object. List endpoints add pagination fields (page, limit, totalRecords).

{
  "status": "success",
  "message": "Success on fetching customers.",
  "data": {
    "page": 1,
    "limit": 20,
    "totalRecords": 1,
    "totalPages": 1,
    "records": [ /* ... */ ]
  }
}

Resources you create or fetch — customers, accounts, vendors, invoices, tags, transactions, and so on — expose their identifier as a UUID string on id. Path parameters, list filters, and cross-resource body fields use UUIDs (often named customerUuid, accountUuid, and similar).

Internal numeric database ids are not exposed on these resources. Passing a non-UUID value in a path or UUID reference field returns 400.

Some request fields reference catalog or configuration rows that are not partner-facing resources. These use small integers where documented on the endpoint — for example subTypeId and institutionId on chart of accounts, salesRepId on customers, or tax ids on New Zealand account create. Copy these values from list responses or reference endpoints; do not substitute UUIDs for them.

• id — the resource UUID in API responses and in path parameters such as /partners/customers/{uuid}.
• uuid — the same value as id in bulk update row bodies (for example bulk customer update).
• *Uuid — scoped references to another resource type in create/update bodies (for example customerUuid, accountUuid).

Bulk create and bulk update routes return a bare batch summary without the standard status, message, and data envelope. HTTP status is typically 201. Check successCount, errorCount, and per-row results:

{
  "successCount": 2,
  "errorCount": 0,
  "results": [
    { "index": 0, "success": true, "customer": { "id": "dfa3219e-6af8-4c53-997a-037534f63a35", "..." : "..." } },
    { "index": 1, "success": true, "customer": { "id": "...", "..." : "..." } }
  ]
}

When some rows fail, error on each failed row is a plain string message (not a structured object). Retry only the failed indices:

{
  "successCount": 1,
  "errorCount": 1,
  "results": [
    { "index": 0, "success": true, "transaction": { "id": "dfa3219e-6af8-4c53-997a-037534f63a35" } },
    { "index": 1, "success": false, "error": "Account sub type not found." }
  ]
}

The array of records lives under a different key per resource. Some list responses also include a filters object echoing applied query parameters. Map row paths once in your client so parsing stays consistent:

// List responses are nested differently per resource.
const LIST_ROW_PATHS = {
  'GET /partners/customers': ['data', 'records'],
  'GET /partners/transactions': ['data', 'transactions'],
  'GET /partners/invoices': ['data', 'invoices'],
};

Errors set status: "error" with a machine-readable code and optional details.

{
  "status": "error",
  "message": "A customer with this email already exists",
  "code": "DUPLICATE_EMAIL",
  "details": {
    "field": "email",
    "existingCustomerUuid": "dfa3219e-6af8-4c53-997a-037534f63a35"
  }
}