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 201 means the batch envelope was accepted, even when every row failed — always read errorCount. A 400 means the envelope itself was invalid, such as more than 100 rows or a missing array. Each row is isolated, so one failure never rolls back the others. For large backfills, send about 25 rows per call with roughly two seconds between batches.

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"
  }
}