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:limitsets the page size: 25 by default, up to 100.- To get the next page, pass
next_cursorascursor. Keep the same filter on every page. - When
has_moreisfalse, you’ve reached the last page andnext_cursorisnull. - 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
datawith 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 infields, separated by commas. Standard fields always come back.
Filter a list
List endpoints take filters as query parameters in the formfilter[<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, andfieldsgo 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) takeview_id. A view of another object returns422. A view the creator doesn’t see returns404. - 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 needviews:update. A key that acts for a person gets it only when that person is an admin.
GET /v1/views/alllists every member’s views and segments, private ones included, with their owners. Filter withobject,type, andowner_id(a person id).POST /v1/views/{view_id}/ownergives the view to the member inowner_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
409and 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.
To write a custom field, send it under
fields:
- An update changes only the keys you send.
nullclears 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
422response lists each problem indetails. - A field with
writable: falsereturns422with the codefield_not_writable. This includes fields owned by another system, such as your CRM, and fields that Statisfy AI fills in (ownerisai).
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 returns422. - A field that other data still uses, such as an AI field with value history, returns
409and nothing changes. - Projects and tasks share one set of custom fields. A delete with
object=projectorobject=taskremoves 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_tosays. A create names it inaccount_idorcontact_id, and it can’t change after that. external_idis 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 returns409.- A create needs a value for every mandatory field that’s
writable. - On an object Salesforce fills, a field Salesforce fills (
owneriscrm) 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 itskey, 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, returns422. A key another object already has, in any case, returns409. - The new object belongs to Statisfy (
sourceisstatisfy) and starts with no fields.
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 withPUT /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
200with"result": "updated". - No match creates the record and returns
201with"result": "created". The body must then meet the object’s create rules. - Some matches return
409instead, 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
createandupdatescopes 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:
Delete
Delete matches the delete action in the app. A deleted record leaves every list, and aGET 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 aPOST 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
409with the codeidempotency_conflict. - If the first request is still running, a retry returns
409with aRetry-Afterheader. 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 returns413 with the code payload_too_large, refused as soon as its size is known.
Request IDs
Every response has anX-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: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
GETrequests, 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
429withRetry-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
422with 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
429andRetry-Afterrather than counting.
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.