---
title: "Response Shapes & Data Models · COUNT Partner API"
description: "Every Partner API response shares a common envelope, with list payloads nested under a resource-specific key. Know the shape before you parse it."
canonical: "https://developers.getcount.com/getting-started/response-shapes"
source: "https://developers.getcount.com/getting-started/response-shapes"
---
Getting Started

# Response shapes & data models

Responses share a common envelope, but list payloads are nested under a resource-specific key. Knowing the shape up front avoids guesswork when parsing.

## Success envelope

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

200 OK

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

## Entity identifiers (UUIDs)

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.

## Catalog and configuration ids (integers)

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.

## Identifier naming

- `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 batch responses

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`:

201 Created (bulk)

```json
{
  "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:

201 Created (partial bulk failure)

```json
{
  "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.

## List payloads vary by resource

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 row paths

```javascript
// 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'],
};
```

## Error envelope

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

409 Conflict

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

Warnings on mutations

Some successful mutating responses include a `_partnerWarnings` array of `{ field, reason, message }`, one per field you sent that was not applied. `internal_only` means COUNT manages that field itself — use the dedicated route instead; `unknown_field` means a typo or a field the resource does not have. A success with warnings does not mean every field was saved.