> ## 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.

# Statisfy API overview

> Read and write Statisfy accounts, contacts, opportunities, projects, and tasks, set up products and their usage dimensions, write and read product usage, read account health, read the customer timeline and push your other systems' activities onto it (every email, meeting, chat thread, ticket, survey, and note on an account, with its AI summary), read the conversations your AI handles with their messages and notes, build and read your reports and run SQL over your report data, write the email templates your campaigns send, build and publish surveys and read their responses, run email and survey campaigns and read what they sent, create and run your digital workers, read the emails they sent on their own initiative, manage the knowledge they answer from and the skills your agents follow, read and update your teammates, read your AI credit usage, manage your sender domains, read and change your workspace settings and read its licenses and features, read your Agent Studio agents and flows and your scheduled workflows, read and decide the approvals your flows wait on, read your integrations and file imports, read the meetings Statisfy's notetaker recorded, and cut, share and read clips of recordings, from your own code over HTTPS with a scoped API key.

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

| Object | What you can do |
| - | - |
| **Accounts** | List, search, get, create, update, batch update, upsert by `domain` or `crm_account_id`, and delete |
| **Account health** | Read each account's health, per pillar: the AI's assessment with its reason and confidence, and the manual entries and overrides people made in the app. Get the current health, the health on a past date, or the full history. Read only. |
| **Contacts** | List, search, get, create, update, batch update, and upsert by `email` |
| **Custom objects** | List, search by any of their fields or by account, and get your custom objects' records. Each record carries the account or contact it belongs to, its `external_id` in the system that fills the object, and its values. What you can change depends on what fills the object: create, update, batch update, upsert by `external_id`, and delete the records of objects Statisfy holds; update the records Salesforce fills. Objects a warehouse or another system fills are read only. Create custom objects and rename them, and add, change, and delete their fields. See [Custom objects](https://help.statisfy.com/rest-api/requests.md#custom-objects). |
| **Meetings** | List and get the meetings Statisfy's notetaker recorded, filtered by account, participant, or date. Get a meeting's transcript as download links valid for one hour. |
| **Clips** | List, get, create, change, delete, and share clips: parts of a meeting or call recording, from Statisfy's notetaker or another recorder. A clip is cut after the create returns: get it until its `status` is `completed`. Its video and thumbnail come as download links valid for one hour. Share opens the clip's public page for 1 to 365 days. |
| **Activities** | Read the customer timeline: list an account's or a person's activities (emails, meetings from any recorder, Slack and Teams threads, tickets, surveys, Chatter, notes, campaign sends), newest first, filtered by type, source, sentiment, or date; get one with its AI summary and the facts of its kind (a ticket's status, a survey's score, a campaign); read what was written in it (a thread's messages, a note, a survey's answers, a campaign's email). Push what another of your systems did with a person (an email thread, a LinkedIn conversation, a call, a webinar, a form) onto the timeline, one at a time or up to 100 per request, and delete what was pushed. See [Push activities onto the timeline](#push-activities-onto-the-timeline). |
| **Conversations** | Read the conversations your AI handles (email, Slack, Teams, portal, and in-app chat): list them most recently active first, filtered by account, assignee, digital worker, status group, channel, kind, priority, tag, the day of the latest message, or whether a worker's proactive email went out on it; get one with its status, assignee, tags, engineering issue, and what the AI did; read its messages, each marked with who wrote it and whether an AI did; read its internal notes. Read only. |
| **Opportunities** | List, search, get, create, update, batch update, upsert by `crm_opportunity_id`, and delete |
| **Saved views and segments** | List and get the saved views of the Accounts, People, and Opportunities pages, and saved segments such as campaign audiences: the ones the key's creator sees in the app. Pass a view's id as `view_id` to that object's list or search to get the records the view selects. A key with `views:update` also lists every member's views, private ones included, and changes a view's owner. |
| **Products** | Set up products and their usage dimensions: list, get, create, update, and delete them, or set up a product and the dimensions you name in one upsert, matched by product name and dimension key |
| **Product usage** | Write a product's usage values, up to 1,000 account-and-date rows per request, naming accounts by id, CRM id, or domain; read them back by account and date |
| **Projects** | List, search, get, create (optionally from a project template), update, batch update, and delete. List your project templates and the custom fields they carry. Add or remove a custom field on a template or on one project. |
| **Reports** | List the report views SQL can read, with their columns. Run your own SQL over them, up to 1,000 rows. List and get your reports and their widgets, private ones included. Create, change, and delete any report and its widgets, private ones included: a widget is a chart, metric, or table that runs SQL over the report views, or text. |
| **Tasks** | List, search, get, create, update, batch update, and delete |
| **Email templates** | List and get the templates your campaigns and flows send, with their HTML. List the merge tags a template can use. Preview a template for a contact and account, or with sample values, without sending it. Create, change, publish, and delete templates. A template created over the API, or whose HTML is changed over the API, opens in the app's HTML editor. |
| **Surveys** | List and get the surveys in your survey creator, with their questions, theme, and email. Create, change, publish, duplicate, and delete surveys. List a survey's responses. A survey's email set over the API opens in the app's HTML editor. A published survey is locked: it can't be changed or deleted, only duplicated. Survey titles are unique, deleted surveys included. For the questions and theme JSON, see [Survey definition and theme](https://help.statisfy.com/rest-api/survey_definition.md). |
| **Campaigns** | List and get your email and survey campaigns. A digital worker's proactive-outreach container isn't a campaign: it isn't listed, and getting it returns `404`. Its emails are under outreach emails. Create, change, publish, unpublish (pause), and delete them. Send a test email to a member of your workspace. Read a campaign's numbers (audience size, delivered, opened, clicked, blocked) and the contacts it was sent to. List the audiences and account roles a campaign can use. A published campaign sends each hour, between its start and end dates, to the contacts in its audience it hasn't reached. |
| **Digital workers** | List and get your digital workers with their settings: their job, voice, and guardrails, the channels they answer on (portal, in-app chat, email, Slack, and Teams), whether their replies wait for a person, the accounts they cover, and who a conversation they hand to a person is assigned to. Create them, change their settings, and activate, stop, or archive them. List the accounts a worker covers. A new worker is a draft, and a draft answers nobody until it's activated. Try a worker on one message, as it is, with changes you haven't saved, or as a saved version: nothing is sent or saved. List a worker's saved versions and restore one, which saves it as a new version and leaves the worker's status as it is. |
| **Outreach emails** | Read the emails your digital workers sent on their own initiative: list them newest first, filtered by worker, account, contact, sent date, status, or whether the customer replied; get one with its text; and count them, with reply, delivery, open, click, and approval numbers, over a range of days, per worker or per week. Each email carries its reply, its delivery, any opt-out, and who approved it. Proactive outreach is part of AI CSM: a workspace without it gets a `403`. Read only. |
| **Knowledge bases** | List your knowledge bases and their documents, with each document's indexing status. Push Markdown, HTML, or text documents by your own id, one at a time or in batches, and delete them. Search the way a digital worker would. |
| **Skills** | List and get the skills your agents load, Statisfy's and your own, with their instructions and files. Create, change, copy, and archive your own, read their earlier versions and make any of them live again, and turn any skill off for your workspace. Changing a skill an agent uses needs `skills:publish`. |
| **Sender domains** | List and get the domains your workspace sends email from, with their status and the DNS records to publish. Add a domain: adding one that's already in the workspace returns it as it is, with a `200`. Verify a domain once its DNS records are published. Delete a domain that isn't verified: a verified domain can't be deleted (`409`). |
| **Notification rules** | List, get, create, update, and delete the rules that send a processed meeting's insights by email, Slack, or Teams. A rule's conditions are filters on the meeting's account and on its internal user, in the same form the app's rule editor saves; a rule with no conditions sends for every meeting. A new email must be a workspace member's, and a new channel one Statisfy is in. List the Slack and Teams channels a rule can send to. |
| **Workspace settings** | Read and change the workspace settings of Settings > Config: the quarter start month, AI task auto-close, the health wait after go-live, meeting processing, the shareable link's life, Stella's disclosure message, the empty-widget switches, the automated email denylist and patterns, the workspace NoteTaker settings, and two email notifications. A change is checked as the app checks it, and one bad value refuses the whole change. Company domains and Stella's PII guardrail are read only: change them in the app. Read the workspace's licenses (each product's term, status, and seats, and who holds a seat) and which optional features are on. Read the health settings (the health scale, how long a manual override holds, the instructions to the AI by pillar, the product field, and the extra fields the AI reads), the renewal settings (which opportunities are renewals, the amount field, the forecast settings, and the risks the agent looks for), which changes made in Statisfy are written back to the CRM, and the Company Context. Licenses, features, and these settings are read only: change them in the app. |
| **Agent Studio** | List and get your Agent Studio agents, Statisfy's and your own, with their instructions, toolkits, skills, and knowledge bases. List your flows, filtered by name, enabled, trigger, or folder, and get one with its trigger and steps. Read only. |
| **Workflows** | List and get your scheduled workflows: the questions Stella answers on a schedule and emails to their owner or pins to their dashboard. Filter by status or owner. A key that acts for a person sees only that person's workflows. Read only. |
| **Approvals** | Read the Approvals inbox: the flow runs waiting on an Agent Studio approval step. List them by My Approvals or All Approvals and by tab (pending, approved, rejected, or history), get one with what it would send (an email's recipients, subject, body, and attachments), and approve or reject up to 100 at once. Only a person's own key approves or rejects, and approving resumes the run, which can email your customers. See [Authentication](https://help.statisfy.com/rest-api/authentication.md#scopes). |
| **Integrations** | List every app your workspace can connect, with whether it's connected, its last run, and what it supports. For each app, read its connections, schedule, and recent runs, and for Slack and Teams the channels Statisfy is in. List file imports and get one with its row counts and failed rows. For a SQL warehouse, also save its config, queries, and schedule, start runs, and run or preview SQL. For Pendo, read and change its config, saved queries, NPS survey settings, and schedule, start its runs (the NPS survey job too), look up its reports, catalog, account fields, and NPS guides, and check a query; previewing a query or the survey job returns Pendo data. Credentials are never returned. |
| **Users** | List, search, get, update, and batch update your teammates: the people on the Team page, whose ids owner fields and a task's creator hold. Update a user's name, role, department, manager, calendar link, and custom user fields. Filter on standard fields only: filtering on a custom user field returns `422`. Access roles, membership, and invites aren't on the API. |
| **AI credits** | Read your AI credits for the current contract period: the summary (allotted, used, remaining, and the credits one call costs per tier), usage by Agent Studio flow, and the usage log of every AI call. The log names the person who made a call by id only, never by name or email. Read only. |
| **Fields** | Read the field definitions of accounts, activities, contacts, opportunities, projects, tasks, users, and your custom objects. Create custom fields and change field definitions on accounts, contacts, opportunities, projects, tasks, users, and your custom objects (on projects and tasks, custom fields only). |
| **Meta** | Check which key you're using and discover every operation the API offers |

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](https://help.statisfy.com/rest-api/authentication.md).

| Endpoint | What it does |
| - | - |
| `PUT /v1/activities` | Creates or updates one activity. The response carries `result`: `created` (`201`), `updated`, or `unchanged`. |
| `POST /v1/activities/batch/upsert` | Pushes up to 100 activities. You get a result for each, in request order: `created`, `updated`, `unchanged`, or `failed` with that item's error. A failed item leaves the rest written. Each item counts against your [rate limit](https://help.statisfy.com/rest-api/requests.md#rate-limits). |
| `DELETE /v1/activities/{activity_id}` | Deletes an activity the API pushed, from every timeline. An activity Statisfy synced returns `404`. |

```bash theme={null}
curl -X PUT https://api.statisfy.com/v1/activities \
  -H "Authorization: Bearer $STATISFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "HubSpot",
    "external_id": "thread-8812",
    "channel": "email",
    "direction": "outbound",
    "occurred_at": "2026-10-27T14:05:00Z",
    "person": { "email": "dana@acme.com", "first_name": "Dana" },
    "sent_by": "alex@yourcompany.com",
    "messages": [
      {
        "external_id": "msg-1",
        "direction": "outbound",
        "sent_at": "2026-10-27T14:05:00Z",
        "subject": "Q4 roadmap review",
        "body_text": "Hi Dana, here is the deck we discussed."
      }
    ]
  }'
```

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

```text theme={null}
https://api.statisfy.com/v1
```

Requests and responses are JSON. Every request needs an API key in the `Authorization` header. See [Authentication](https://help.statisfy.com/rest-api/authentication.md).

## Quickstart

You need an API key with the `accounts:read` scope. Admins create keys in **Settings → API Keys**. See [Get an API key](https://help.statisfy.com/rest-api/authentication.md#get-an-api-key).

**1. Store your key**

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

```bash theme={null}
export STATISFY_API_KEY="stfy_live_…"
```

**2. Check the key**

Call `GET /v1/meta/whoami`. It works with any valid key, whatever its scopes:

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

The response names your workspace, the key, and the scopes it has:

```json theme={null}
{
  "org_id": "org_…",
  "actor_type": "service",
  "actor_display": "API key: Nightly renewal sync",
  "attribution_id": "apikey:…",
  "scopes": ["accounts:read"],
  "worker_id": null,
  "run_id": null,
  "request_id": "3f2c9a…"
}
```

A `401` means the key is missing, mistyped, expired, or revoked.

**3. List accounts**

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

You get a page of accounts. Standard fields sit at the top level of each record, and custom fields sit under `fields`:

```json theme={null}
{
  "data": [
    {
      "id": "4f9a2c1e8b7d4e6fa3c5b0d2e1f7a9c8",
      "name": "Acme Corp",
      "domain": "acme.com",
      "type": "Customer",
      "arr": 120000,
      "renewal_date": "2027-03-31",
      "fields": { "segment__c_": "Enterprise" }
    }
  ],
  "next_cursor": "eyJpZCI6…",
  "has_more": true
}
```

The example shows only some of the fields a record carries. To get the next page, pass `next_cursor` as `cursor`. See [Pagination](https://help.statisfy.com/rest-api/requests.md#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.

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

Each entry in `capabilities` describes one operation:

| Key | What it tells you |
| - | - |
| `summary`, `description` | What the operation does and the rules it applies |
| `rest` | The HTTP `method` and `path` to call |
| `required_scope`, `also_requires` | The scopes your key needs to call it |
| `read_only` | Whether it only reads data |
| `idempotent` | Whether you can safely repeat the same call |
| `paginated` | Whether it returns pages |
| `request_schema`, `response_schema` | JSON Schemas for the input and the output |

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

> [card] [Authentication](https://help.statisfy.com/rest-api/authentication.md)
>
> How API keys work, the scopes, and how to get, rotate, and revoke a key.

> [card] [Working with the API](https://help.statisfy.com/rest-api/requests.md)
>
> Pagination, filters, custom fields, upserts, batches, retries, errors, and rate limits.


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