Choose what your integration will do
The Integration API lets tools such as Clay, Zapier, and your own services read and upsert accounts and contacts, publish signals from external systems, and retrieve a user's task and signal counts.
Organization administrators create and manage API keys in Org settings → API & MCP. Each key acts within that organization. The API documentation tab on that page has the endpoint reference and examples.
Organization API keys let other tools call Athean. To let Athean call another service's API, use Settings → API secrets (see API secrets).
To use Athean from another AI assistant, such as Claude, follow Use Athean from another AI assistant instead. That connection signs in as a person and uses their permissions; it doesn't use an organization API key. For a connection built around your workflow, including an internal platform, contact support.
Create an API key
- Open Org settings → API & MCP, select API keys, and choose Create key.
- Enter a Name that identifies the tool or workflow, such as Clay enrichment, then select Create key.
- Copy the key into your tool's credentials or secret settings before closing the dialog. The complete key is shown once and can't be retrieved later. If it's lost, revoke it and create a new one.
- Open the API documentation tab for the endpoint reference and examples. Select Copy docs as Markdown to share the reference with the person building the connection.
Base URL, authentication headers, and /whoami
All Integration API requests use the base URL https://app.athean.com/api/integration/v1 and authenticate via either HTTP header:
Authorization: Bearer YOUR_API_KEYX-API-Key: YOUR_API_KEY
Send a GET request to /whoami to verify authentication; a valid key returns 200 OK with orgId, keyId, and keyName. Check that they match the organization and key you intended before adding write operations. Read endpoints support GET query parameters or POST JSON bodies; write endpoints require POST with a JSON body.
Account and contact endpoints
| Endpoint | Behavior and parameters |
|---|---|
/contacts/get/accounts/get | Fetch a single record. Identify contacts by Athean ID, Salesforce ID, or email; identify accounts by Athean ID, Salesforce ID, or domain. |
/contacts/list/accounts/list | Paginate records (default page size 100, maximum 500). Pass the returned nextCursor value as cursor on the next request until nextCursor is omitted. |
/contacts/upsert/accounts/upsert | Create or update a record. By default, overwrite: false populates only empty fields; set overwrite: true to overwrite existing non-empty values (empty strings and non-positive numbers are ignored). Creating a new contact requires an email address (plus an explicit account ID or business domain if the email uses a personal domain); creating a new account requires a domain. Organization policies can refuse record creation. |
CRM writeback note: Upserts via the Integration API change Athean records. They're saved as local edits that can override CRM-synced values and persist across later CRM syncs. They aren't pushed back to your CRM.
Signal and workload count endpoints
| Endpoint | Behavior and requirements |
|---|---|
/signals/upsert | Creates or updates an external signal in Signals keyed by type and sourceId. Requires: (1) a matching rule configured in Org settings → Signal types, and (2) an account identifier, or a contact, that resolves to a Salesforce-linked account. Only the initial creation triggers signal-created Event-triggered automations. |
/tasks/countByCategory | Returns a single user's open, dated task counts grouped by overdue, due today, and upcoming (undated tasks are excluded). |
/signals/countByCategory | Returns a single user's explicitly assigned signal counts grouped by highest-priority signal category. |
Manage API keys, rate limits, and status codes
In the API keys tab of Org settings → API & MCP, review each key's name, prefix, status (Active or Revoked), creation date, and Last used time. Create and test a replacement before you revoke a key that an active integration uses. Revoke stops the key from working immediately and can't be undone.
| HTTP status | Meaning and resolution |
|---|---|
400 Bad Request | The request body is malformed or a required field is missing. Check the request fields and format. |
401 Unauthorized | The API key is missing, invalid, or revoked. Check that the key is present, correct, and active. |
404 Not Found | No record matches the identifier you sent: an Athean ID, Salesforce ID, email, or domain on a /get request, or an Athean or Salesforce ID on an upsert. Check the value you sent. |
422 Unprocessable Entity | A business rule refused the request (for example, an unlinked Salesforce account or a missing signal type rule on /signals/upsert, or record creation blocked by organization policy). Read the response message. |
429 Too Many Requests | The key exceeded its rate limit. Slow down and honor the Retry-After response header. The API documentation tab shows the current limit. |
If you need help, contact support with the endpoint and error message. Keep your API key out of the message.