API setup

The Integration API lets tools such as Clay, Zapier, and your own services work with your organization's Athean data. Use it to read contacts and accounts, add enrichment, publish signals from external systems, or retrieve task and signal counts.

An organization administrator creates and manages API keys. Each key acts within that organization. If you want a connection built around your workflow, including an internal platform, chat with us.

1. Open Org settings → API keys and select Create key.
2. Give it a name that identifies the tool or workflow, such as Clay enrichment, then select Create key.
3. Copy the key into your tool's credentials or secret settings before closing the dialog. The complete key is shown once and cannot be retrieved later.
4. Open the API documentation tab for the endpoint reference and examples. Use Copy docs as Markdown to share the reference with the person building the connection.

Keep the key in your integration's secret storage. If you lose it, revoke it and create a replacement.

Use https://app.athean.com/api/integration/v1 as the base URL. Add your key in one of these HTTP headers:

• Authorization: Bearer YOUR_API_KEY
• X-API-Key: YOUR_API_KEY

Send a GET request to /whoami. A successful response contains orgId, keyId, and keyName. Check that they match the organization and connection you intended before adding write operations.

Read endpoints accept GET query parameters or a POST JSON body. Write endpoints use POST with a JSON body. The API documentation tab includes the exact fields and copyable examples.

Use /contacts/get or /accounts/get to look up a record. A contact can be identified by its Athean ID, Salesforce ID, or email; an account by its Athean ID, Salesforce ID, or domain.

Use /contacts/list and /accounts/list for multiple records. Pass the returned nextCursor as cursor to retrieve the next page. Stop when no next cursor is returned. The default page size is 100, with a maximum of 500.

The /contacts/upsert and /accounts/upsert endpoints update a matching record or create one when permitted:

• Fill missing data: the default overwrite: false writes only where the current value is empty.
• Replace data: overwrite: true lets supplied fields replace existing values. Empty strings and non-positive numbers do not clear fields.
• Record creation: a new contact requires an email, and a new account requires a domain. Organization policies can refuse creation. For a contact with a personal email address, supply an account ID or business domain explicitly.

These writes change Athean records. They act as local edits, can override CRM-synced values, and survive the next CRM sync. They are not pushed back to your CRM. See Import contacts for the separate CRM import flow.

Use /signals/upsert to bring events from external tools into Signals. Before sending events, an administrator must add a matching category in Org settings → Signal types.

1. Choose a stable type for the source and event, and a sourceId that identifies each event in the source system.
2. Configure a signal type rule that matches that source. Requests without a matching category are refused.
3. Send the event title, supporting description, and account identifier. This endpoint currently requires the resolved account to be Salesforce-linked. A contact and explicit assignee are optional.
4. Review the resulting signal in Athean to check its category, account, and assignment.

Sending the same type and sourceId again updates the existing signal. Only the first creation fires the signal-created event workflows. Follow Event-triggered automations to configure the workflow that responds. Use the in-app API reference for the full field requirements and assignment rules.

For reporting, /tasks/countByCategory returns a user's open, dated tasks by overdue, due today, and upcoming status; undated tasks are excluded. /signals/countByCategory counts explicitly assigned signals by their highest-priority category. Identify one user per request.

In API keys, review each key's name, prefix, status, creation date, and Last used time. Create and test a replacement before revoking a key used by an active integration. Revoke stops that key from working immediately and cannot be undone.

• 400: check the request fields and format.
• 401: check that the key is present, correct, and active.
• 404: check the exact record ID.
• 422: read the response message; a required match, signal category, or organization policy may prevent the operation.
• 429: slow down and honor Retry-After. The limit is 15 requests per second per key.

If you need help, contact support with the endpoint and error message. Keep your API key out of the message.