Skip to main content
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. The examples assume your key is in the STATISFY_API_KEY environment variable.

Pagination

List and search endpoints return one page at a time:
  • 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).

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.

Filter a list

List endpoints take filters as query parameters in the form filter[<field>][<operator>]=<value>. Multiple filters are combined with AND.
  • 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.
  • 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.

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
  • 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:
  • 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:
  • 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.
Each field definition tells you: To write a custom field, send it under fields:
  • 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:
  • 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:
  • 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:
  • 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:
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:
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.

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.
  • 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:
Branch on code, not on message. details lists each problem, with loc pointing at the input that caused it. 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:
  • 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: 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.
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.