> ## Documentation Index
> Fetch the complete documentation index at: https://help.statisfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Working with the API

> Paginate, filter, and search records; read and write custom fields; upsert and batch update; retry safely; and handle errors and rate limits in the Statisfy API.

This page covers the behavior shared by every object in the Statisfy API. For a single operation's parameters, rules, and response, see its entry in the endpoint reference or in `GET /v1/meta/capabilities`. See [Discover operations](https://help.statisfy.com/rest-api/overview.md#discover-operations).

The examples assume your key is in the `STATISFY_API_KEY` environment variable.

## Pagination

List and search endpoints return one page at a time:

```json theme={null}
{
  "data": [ ... ],
  "next_cursor": "eyJpZCI6…",
  "has_more": true
}
```

* `limit` sets the page size: 25 by default, up to 100.
* To get the next page, pass `next_cursor` as `cursor`. Keep the same filter on every page.
* When `has_more` is `false`, you've reached the last page and `next_cursor` is `null`.
* Records come back in a stable order. There's no sort parameter.
* Treat the cursor as opaque. A cursor that has been changed returns `400`.
* A list or search can trail a write by a moment. To read a record you just created or changed, get it by its ID: that always shows your writes.
* A few lists are short enough to come back whole, in `data` with no cursor: products, project templates, surveys, campaigns, a campaign's audiences and account roles, digital workers, and skills.
* Product usage and account health pages hold up to 1,000 rows (100 by default).

```bash theme={null}
curl -G https://api.statisfy.com/v1/objects/account/records \
  -H "Authorization: Bearer $STATISFY_API_KEY" \
  --data-urlencode "limit=100" \
  --data-urlencode "cursor=eyJpZCI6…"
```

### Choose which custom fields come back

A record includes every custom field it has. To get only some, pass their keys in `fields`, separated by commas. Standard fields always come back.

```bash theme={null}
curl "https://api.statisfy.com/v1/objects/account/records/4f9a2c1e8b7d4e6fa3c5b0d2e1f7a9c8?fields=segment__c_,csm_notes__c_" \
  -H "Authorization: Bearer $STATISFY_API_KEY"
```

## Filter a list

List endpoints take filters as query parameters in the form `filter[<field>][<operator>]=<value>`. Multiple filters are combined with AND.

```bash theme={null}
curl -G https://api.statisfy.com/v1/objects/opportunity/records \
  -H "Authorization: Bearer $STATISFY_API_KEY" \
  --data-urlencode "filter[close_date][gte]=2026-10-01" \
  --data-urlencode "filter[is_closed][eq]=false" \
  --data-urlencode "limit=50"
```

| Operator | Matches |
| - | - |
| `eq` | Equal to the value |
| `gt`, `gte`, `lt`, `lte` | Greater than, at least, less than, or at most the value |
| `in` | Any of the values. Repeat the parameter for each value, up to 100. |
| `nin` | None of the values. Use `nin` with one value for "not equal to". |
| `contains` | Text that contains the value |
| `starts_with` | Text that starts with the value |
| `exists`, `not_exists` | Records where the field has a value, or has none. These take no value. |

* Each field supports only some operators. An operator a field doesn't support returns `422`, and the message lists the operators it does support.
* Filter on standard and custom fields by their keys from `GET /v1/fields`. See [Custom fields](#custom-fields).
* Write dates as `YYYY-MM-DD`. They compare as whole days.
* Each object's reference entry explains its own matching rules, such as which text comparisons ignore case.

```bash theme={null}
# Accounts with no renewal date, in either of two segments
curl -G https://api.statisfy.com/v1/objects/account/records \
  -H "Authorization: Bearer $STATISFY_API_KEY" \
  --data-urlencode "filter[renewal_date][not_exists]=true" \
  --data-urlencode "filter[segment__c_][in]=Enterprise" \
  --data-urlencode "filter[segment__c_][in]=Mid-Market"
```

## Search with AND and OR

For AND/OR logic, send the filter as JSON to the object's search endpoint, `POST /v1/objects/<object>/records/search`. A filter is either a condition or a group:

* **Condition:** `{ "field": "<key>", "op": "<operator>", "value": <value> }`
* **Group:** `{ "and": [ ... ] }` or `{ "or": [ ... ] }`, holding conditions or more groups

```bash theme={null}
curl https://api.statisfy.com/v1/objects/task/records/search \
  -H "Authorization: Bearer $STATISFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "and": [
        { "field": "status", "op": "nin", "value": ["Done"] },
        {
          "or": [
            { "field": "priority", "op": "eq", "value": "high" },
            { "field": "due_date", "op": "lt", "value": "2026-10-15" }
          ]
        }
      ]
    },
    "limit": 50
  }'
```

* A filter can nest groups up to 3 levels deep and hold up to 20 conditions.
* The operators and rules are the same as for list filters.
* `limit`, `cursor`, and `fields` go in the request body.

## Use a saved view

A saved view or segment from the app can select the records of a list or search. `GET /v1/views` lists the views the key's creator sees in the app: their own, the workspace's, and those shared with them. Each view names its `object`. Pass its `id` as `view_id` to that object's list or search:

```bash theme={null}
curl -G https://api.statisfy.com/v1/objects/account/records \
  -H "Authorization: Bearer $STATISFY_API_KEY" \
  --data-urlencode "view_id=42" \
  --data-urlencode "filter[segment__c_][eq]=Enterprise"
```

* The view's filter and its list ("My book", "Team book", "Churned") apply as in the app, for the key's creator. A "My book" view selects the creator's book.
* Other filters narrow the view's records further.
* Records come in id order, not in the view's sort order.
* Listing views needs `views:read`. Reading the records needs the object's own read scope.
* Accounts (`/v1/objects/account/records`), contacts (`/v1/objects/contact/records`, the People page), and opportunities (`/v1/objects/opportunity/records`) take `view_id`. A view of another object returns `422`. A view the creator doesn't see returns `404`.
* A key that no current member created sees the workspace's views only, and a book view selects no records for it.

### Change a view's owner

An admin can give a view to another member, for example when a person leaves the team. Both operations need `views:update`. A key that acts for a person gets it only when that person is an admin.

* `GET /v1/views/all` lists every member's views and segments, private ones included, with their owners. Filter with `object`, `type`, and `owner_id` (a person id).
* `POST /v1/views/{view_id}/owner` gives the view to the member in `owner_id`, and returns the view:

```bash theme={null}
curl -X POST https://api.statisfy.com/v1/views/42/owner \
  -H "Authorization: Bearer $STATISFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"owner_id": "<person id>"}'
```

* The new owner must be a member who signs in. Another person returns `422`.
* An unknown view, or a view of a page the API doesn't serve, returns `404`.
* When the new owner already has a view with the same name (case is ignored) and the same scope, on any page, the call returns `409` and changes nothing. Rename the view in the app. Then send the call again.
* The new owner's own share of the view is removed, because an owner has full access. Other shares stay. The old owner no longer sees a private view unless it is shared with them.
* Each change is in the audit log, with the key that made it.
* One call moves one view. To move all views of a person, list them with `owner_id`. Then change each one.

## Custom fields

`GET /v1/fields?object=<object>` lists every standard and custom field on an object, where `<object>` is `account`, `activity`, `contact`, `opportunity`, `project`, `task`, `user`, or a custom object's key. The keys it returns are the ones you use in filters, in `fields`, and in writes.

```bash theme={null}
curl "https://api.statisfy.com/v1/fields?object=account" \
  -H "Authorization: Bearer $STATISFY_API_KEY"
```

Each field definition tells you:

| Key | Meaning |
| - | - |
| `key`, `label`, `type` | The field's key, display name, and data type |
| `kind` | `standard` fields sit at the top level of a record. `custom` fields sit under `fields`. |
| `options` | The allowed values of a picklist |
| `mandatory`, `hidden` | Whether the field is required, and whether it's hidden in the app |
| `owner` | What sets the field's value: `statisfy`, `crm`, `warehouse`, `integration`, `ai`, or `computed` |
| `writable` | Whether an API update can write the field |
| `syncs_to_crm` | Whether a value you write reaches your CRM |

To write a custom field, send it under `fields`:

```bash theme={null}
curl -X PATCH https://api.statisfy.com/v1/objects/account/records/4f9a2c1e8b7d4e6fa3c5b0d2e1f7a9c8 \
  -H "Authorization: Bearer $STATISFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "arr": 150000, "fields": { "segment__c_": "Enterprise" } }'
```

* An update changes only the keys you send.
* `null` clears a custom field that isn't mandatory.
* Statisfy checks every key before it writes anything. If any key has a problem, such as an unknown key, a value of the wrong type, or a value outside the field's options, nothing is written. The `422` response lists each problem in `details`.
* A field with `writable: false` returns `422` with the code `field_not_writable`. This includes fields owned by another system, such as your CRM, and fields that Statisfy AI fills in (`owner` is `ai`).

You can also create custom fields on accounts, contacts, opportunities, projects, tasks, users, and custom objects with `POST /v1/fields`, and change a field's display name, visibility, requiredness, or picklist options. Use a new field's key right away in reads, filters, and writes. On users you can't filter by it: filtering on a custom user field returns `422`.

To delete a custom field, send `DELETE /v1/fields/{key}?object=<object>` with a key that has `fields:delete`:

```bash theme={null}
curl -X DELETE "https://api.statisfy.com/v1/fields/renewal_risk__c_?object=account" \
  -H "Authorization: Bearer $STATISFY_API_KEY"
```

```json theme={null}
{ "key": "renewal_risk__c_", "object": "account", "deleted": true }
```

* The delete removes the field's value on every record. You can't undo it.
* You can delete only a field created in Statisfy, in the app or with `POST /v1/fields`. A field from your CRM or a system field returns `422`.
* A field that other data still uses, such as an AI field with value history, returns `409` and nothing changes.
* Projects and tasks share one set of custom fields. A delete with `object=project` or `object=task` removes the field from both.
* A field that isn't there returns `404`. So does a second delete of the same field.
* On a custom object, a field your CRM fills, and any field of an object a warehouse or another system fills, can't be deleted: the next sync would bring it back. Deleting one returns `422`.

## Custom objects

A custom object's records sit at `/v1/objects/<key>/records`, where `<key>` is the object's key from `GET /v1/objects`. Its fields are keyed `<key>__<field>`, as `GET /v1/fields?object=<key>` lists them, and a record holds its values under `fields`.

What you can change depends on what fills the object. `GET /v1/objects` gives each object's `source` and the `operations` it takes:

| The object is filled by | What you can do with its records |
| - | - |
| Statisfy (`source` is `statisfy`) | List, search, get, create, update, batch update, upsert by `external_id`, and delete |
| Salesforce | List, search, get, update, and batch update. Create and delete them in Salesforce. |
| A warehouse or another system | List, search, and get |

* A record belongs to an account or to a contact, as the object's `belongs_to` says. A create names it in `account_id` or `contact_id`, and it can't change after that.
* `external_id` is the record's id in your system. It's optional on a create, and unique among the object's records on the same account or contact: a create that repeats one returns `409`.
* A create needs a value for every mandatory field that's `writable`.
* On an object Salesforce fills, a field Salesforce fills (`owner` is `crm`) is writable only while writeback to Salesforce is on for the object, which you turn on in the app. What you write there goes back to Salesforce, and you can't clear it over the API.
* Deleting a record removes it and its values for good.

### Set up a custom object

To create a custom object, send its `key`, `name`, and what its records belong to (`belongs_to`, `account` or `contact`) to `POST /v1/objects`:

* The key is lowercase letters, digits, and underscores, starts with a letter, and has at most 50 characters. It can't contain `__`, and it can't change after the object is created.
* A standard object's name, such as `account`, returns `422`. A key another object already has, in any case, returns `409`.
* The new object belongs to Statisfy (`source` is `statisfy`) and starts with no fields.

Add its fields with `POST /v1/fields`, with `object` set to its key. A field's key is made from its name, as the app's Object Manager makes it: a field named `Renewal stage` on `contract` is `contract__renewal_stage`. A custom object's fields can be text, textarea, text\_list, number, float, percent, percent\_ratio, currency, boolean, date, datetime, url, or pill. A pill is a picklist and takes `options`. An object a warehouse or another system fills takes no new field.

To rename an object, send its new `name` to `PATCH /v1/objects/<key>`. Delete an object in the app: deleting one removes all its records and values.

## Upsert

An upsert updates the record that matches a key in the body, or creates the record if nothing matches. Send the body with `PUT /v1/objects/<object>/records` for accounts, contacts, opportunities, and custom objects, or `PUT /v1/products` for products, and name the matching key in `match`:

| Object | `match` values |
| - | - |
| Accounts | `domain` or `crm_account_id` |
| Contacts | `email` |
| Opportunities | `crm_opportunity_id` |
| Custom objects | `external_id`, among the records on the account or contact the body names |
| Products | `name`. Each dimension in the body is matched by its `key`, or the key its name makes; dimensions you don't send are left as they are. |

```bash theme={null}
curl -X PUT "https://api.statisfy.com/v1/objects/account/records?match=domain" \
  -H "Authorization: Bearer $STATISFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp", "domain": "acme.com", "arr": 150000 }'
```

* A match updates the record and returns `200` with `"result": "updated"`.
* No match creates the record and returns `201` with `"result": "created"`. The body must then meet the object's create rules.
* Some matches return `409` instead, such as a domain shared by several accounts or a CRM ID held by a deleted record. Each object's reference entry lists its cases.
* An upsert needs both the `create` and `update` scopes for the object.
* Retrying an upsert is safe: a retry after a create updates the record it created.

## Batch update

`POST /v1/objects/<object>/records/batch/update` updates up to 100 records in one request, each with its own values. It works on accounts, contacts, opportunities, projects, tasks, users, and custom objects. Each item is the record's `id` plus the keys to change:

```bash theme={null}
curl https://api.statisfy.com/v1/objects/account/records/batch/update \
  -H "Authorization: Bearer $STATISFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "id": "4f9a2c1e8b7d4e6fa3c5b0d2e1f7a9c8", "fields": { "segment__c_": "Enterprise" } },
      { "id": "7c1e0b9d3a2f4e5b8c6d1a0f9e8b7c6d", "arr": 90000 }
    ]
  }'
```

Each item is checked and written on its own, so one failure doesn't stop the rest. The response lists every item in request order:

```json theme={null}
{
  "items": [
    { "id": "4f9a2c1e8b7d4e6fa3c5b0d2e1f7a9c8", "status": "updated", "error": null },
    {
      "id": "7c1e0b9d3a2f4e5b8c6d1a0f9e8b7c6d",
      "status": "failed",
      "error": { "code": "field_not_writable", "message": "…", "details": [] }
    }
  ]
}
```

A failed item carries the error a single update would have returned. The whole request fails only when it's malformed, for example with no items, more than 100, or the same record twice. A batch counts as one write per item against your [rate limits](#rate-limits).

## Delete

Delete matches the delete action in the app. A deleted record leaves every list, and a `GET` on it returns `404`. Deleting a record that's already deleted returns the same response and changes nothing, so a retry is safe. Products, their dimensions, custom fields, and custom objects' records are the exception: they're deleted outright, so deleting one again returns `404`. Each object's reference entry describes exactly what its delete does. For example, deleting a project also deletes its tasks, and deleting an opportunity doesn't delete it in your CRM. Contacts can't be deleted over the API.

## Retries and idempotency

To retry a `POST` request safely, such as a create or a batch update, send an `Idempotency-Key` header with a unique value, such as a UUID, for each operation. A key is 1 to 255 printable ASCII characters with no spaces; a longer key, or one with any other character, returns `400`. An empty header counts as no key.

```bash theme={null}
curl https://api.statisfy.com/v1/objects/task/records \
  -H "Authorization: Bearer $STATISFY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1d2c1e-4b8a-4f6e-9a57-2f0c8e1d9b43" \
  -d '{ "title": "Schedule QBR", "account": "4f9a2c1e8b7d4e6fa3c5b0d2e1f7a9c8" }'
```

* If you send the same key with the same request again, Statisfy returns the first response instead of running the request again. The replayed response has the header `Idempotent-Replay: true`.
* Reusing a key with a different request returns `409` with the code `idempotency_conflict`.
* If the first request is still running, a retry returns `409` with a `Retry-After` header. Wait that many seconds and retry.
* If the first request failed without writing anything, the key is freed and a retry runs normally.
* Keys belong to the API key that sent them. A key is answered for 24 hours; after that it's forgotten, and a request that sends it again runs again.

`PATCH`, `PUT` (upsert), and `DELETE` requests are safe to repeat without an idempotency key. So is a product usage write (`POST /v1/products/{id}/usage`), which sets values.

## Request size

A request body can be up to 1 MiB, or 8 MiB for creating or changing an email template and for a product usage write. A bigger body returns `413` with the code `payload_too_large`, refused as soon as its size is known.

## Request IDs

Every response has an `X-Request-Id` header, and every error repeats it as `request_id`. To trace a request end to end, send your own `X-Request-Id` of up to 64 letters, digits, and hyphens; Statisfy uses it instead of generating one. Include the request ID when you contact Statisfy support about a request.

## Errors

Every error has the same shape:

```json theme={null}
{
  "error": {
    "code": "validation_failed",
    "message": "Request validation failed.",
    "request_id": "3f2c9a…",
    "details": [
      { "loc": "fields.renewal_stage__c_", "msg": "…", "code": "validation_failed" }
    ]
  }
}
```

Branch on `code`, not on `message`. `details` lists each problem, with `loc` pointing at the input that caused it.

| Status | Code | Meaning |
| - | - | - |
| `400` | `validation_failed` | The request couldn't be read, such as invalid JSON or a changed cursor |
| `401` | `unauthorized` | The key is missing, invalid, expired, or revoked |
| `403` | `insufficient_scope` | The key doesn't have the scope this operation needs |
| `403` | `not_entitled` | Your workspace's plan doesn't include this, whatever the key's scopes, such as campaigns, which come with AI CSP or AI CSM |
| `403` | `forbidden` | The key may call this operation, but not on this record, such as a comment someone else wrote |
| `404` | `not_found` | No such record, or no such endpoint |
| `405` | `method_not_allowed` | The endpoint doesn't support this HTTP method |
| `409` | `conflict` | The write clashes with existing data, such as a domain another account already has |
| `409` | `idempotency_conflict` | The `Idempotency-Key` was used for a different request, or the first request is still running |
| `413` | `payload_too_large` | The request body is bigger than the operation takes (see [Request size](#request-size)) |
| `422` | `validation_failed` | A parameter or value is invalid, or a filter uses an unsupported operator |
| `422` | `field_not_writable` | Every problem is a field the API can't write |
| `429` | `rate_limited` | You've hit a rate limit |
| `500` | `internal_error` | Something went wrong on Statisfy's side |
| `502` | `upstream_failed` | A service the request depends on, such as SendGrid for sender domains, failed. Nothing changed: retry after the `Retry-After` header. A `503` with this code means the service isn't available yet, or a new clip couldn't be queued for cutting. |
| `503` | `overloaded` | The service is busy. Retry after the `Retry-After` header. |
| `504` | `query_timeout` | The query took too long. Narrow your filter or use a smaller `limit`. Report SQL stops after about 15 seconds: simplify it or filter it to fewer rows. |

If a create fails after the record was saved, the error message names the new record. Update that record instead of creating it again, or retry with the same `Idempotency-Key` to get the same answer.

## Rate limits

Requests are limited per minute, both per key and across your whole workspace, plus a daily cap per key:

| Limit | Reads | Writes |
| - | - | - |
| Per key, per minute | 600 | 120 |
| Per workspace, all keys combined, per minute | 1,200 | 240 |
| Per key, per day | 50,000 requests in total | |

* Reads are `GET` requests, searches, and report SQL runs (`POST /v1/reports/query`). Writes are creates, updates, upserts, and deletes.
* Report SQL runs also have a limit on how many run at once: a few per workspace on each server. One past it waits a few seconds, then returns `429` with `Retry-After`.
* Every authenticated request counts once as soon as it arrives, including one then refused for its input. A batch update counts its other items once its body is read, so it counts as one write per item. A batch too big to ever fit in your limits returns `422` with the number of items you can send per request.
* A product usage write counts as one write, however many rows it holds (up to 1,000).
* Statisfy can set a different per-minute limit for a key. Its write limit is then a fifth of its read limit.
* Minute windows reset at the start of each minute, and the daily cap resets at midnight UTC.
* Each server running the API counts on its own, so a limit can let somewhat more through when your requests are spread across servers. Treat the numbers as approximate, and rely on `429` and `Retry-After` rather than counting.

After a request is authenticated, its response includes these headers, including when it fails:

| Header | Meaning |
| - | - |
| `X-RateLimit-Limit` | The limit for this key and kind of request (read or write) in the current minute |
| `X-RateLimit-Remaining` | How many requests are left in that window |
| `X-RateLimit-Reset` | When the window resets, in Unix epoch seconds |

Requests that fail authentication, or that go to an endpoint that doesn't exist, don't include them. When you go over a limit, the API returns `429` with the code `rate_limited` and a `Retry-After` header giving the seconds to wait. On a `429`, the rate-limit headers describe the limit you hit. A request refused for going over a limit doesn't count against your limits.

> [!TIP]
>
> To stay under the limits, use batch updates instead of many single updates, request 100 records per page, and back off when `X-RateLimit-Remaining` gets low.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.