Skip to main content
The Statisfy API lets your scripts, backend services, and AI agents read and write the records in your Statisfy workspace. Use it to keep Statisfy in step with another system, automate bulk updates, or build an integration that the built-in connectors don’t cover.

What you can work with

Every object’s records sit under one path, /v1/objects/{object}/records: /v1/objects/account/records for accounts, and /v1/objects/{key}/records for a custom object. GET /v1/objects lists the objects, standard and custom, with what you can do with each. Writes go through the same checks as an edit in the app. For example, a field that your CRM owns can’t be written over the API, and a write to a field that syncs to your CRM reaches it on the next sync. Reports are the exception to who may write: a key with a reports write scope can change any report, whoever owns it.

Push activities onto the timeline

Your marketing platform, sequencer, or dialer can put what it did with a person on that person’s and their account’s timeline. You need a key with activities:write. A key that acts for a person gets it only when that person is an admin. See Authentication.

How a push becomes an activity

  • Type: channel sets the activity’s type, the way Statisfy types its own activities. email becomes an email (EMAIL). call and meeting become a meeting (MEETING). linkedin becomes a LinkedIn thread. webinar, form, web_visit, event, and other become a marketing event. The activity’s source is api, and pushed.system holds the source you sent.
  • Idempotency: source and external_id together identify the activity. Sending the same pair again updates the activity in place, so retries, re-syncs, and later changes such as an email being opened never add a copy.
  • Conversations: an email thread or a LinkedIn exchange is one activity with its messages. Send the whole thread again, or only the new messages. Statisfy merges them by each message’s external_id. The activity’s date is its latest message. An email or LinkedIn push without messages is a thread of one. Sending body_text alongside messages returns 422, and so does sending messages on any other channel. Read the messages back, oldest first, with GET /v1/activities/{activity_id}/content.
  • Person: Statisfy matches person.email to a person, ignoring case. When no person matches, Statisfy creates one as an external person. An address on your own company domains is a teammate’s, and returns 422.
  • Account: the activity goes on the account you name in account (by id, crm_account_id, or domain). A named account that doesn’t exist returns 404. Without account, it goes on the person’s account, else the account matching their email’s domain. On a CRM-connected workspace, only a CRM account matches a domain. A personal domain such as gmail.com never matches. With no account, the activity stays on the person. Push it again once the account exists to add it.
  • Engagement: an inbound touch, an inbound message, or outcome.replied_at marks the person as engaged and moves the account’s last activity date. A touch that only went out to the person does neither.
  • Campaigns: a push can’t name a campaign. Sending campaign returns 422.
A pushed activity shows on the timelines and agents read it. It doesn’t send notifications, create workbench actions, or push to your CRM. Statisfy doesn’t summarize it with AI or reply to it, and it never counts as your team’s own mail.

Base URL

Every endpoint lives under /v1:
Requests and responses are JSON. Every request needs an API key in the Authorization header. See Authentication.

Quickstart

You need an API key with the accounts:read scope. Admins create keys in Settings → API Keys. See Get an API key.
1

Store your key

Keep the key in an environment variable rather than in your code:
2

Check the key

Call GET /v1/meta/whoami. It works with any valid key, whatever its scopes:
The response names your workspace, the key, and the scopes it has:
A 401 means the key is missing, mistyped, expired, or revoked.
3

List accounts

You get a page of accounts. Standard fields sit at the top level of each record, and custom fields sit under fields:
The example shows only some of the fields a record carries. To get the next page, pass next_cursor as cursor. See Pagination.

Discover operations

GET /v1/meta/capabilities returns a machine-readable list of every operation the API offers. Like whoami, it works with any valid key.
Each entry in capabilities describes one operation: The input schema covers query parameters and the request body, so it’s the place to look up exactly what an operation accepts. Hand this response to an AI agent or a code generator to give it typed access to the whole API. The list is the same for every key, so check required_scope before you call an operation. Every endpoint is also documented under Endpoints in these docs.

Next steps

Authentication

How API keys work, the scopes, and how to get, rotate, and revoke a key.

Working with the API

Pagination, filters, custom fields, upserts, batches, retries, errors, and rate limits.