Required.
/users returns your managers — the people who own leads, tasks,
and calls. It is not incremental:
it is fetched in full on every sync.Purpose
A user is one manager in your CRM — a person who owns work. HunterAI reads/users to build the manager roster and to resolve per-manager attribution:
every lead, task, and call points at a user through responsible_user_id, and
that link is what powers per-manager analytics. is_active separates current
managers from ones who have left, so departed managers can be excluded from
live reporting without losing their history.
Request
/users is not incremental — it receives no updated_since and is fetched in
full on every sync. Return your complete current list each time.
Response envelope
200 OK
data, has_more, page, limit) is the same on every endpoint
— see How sync works → The envelope.
Only data and has_more are read.
Fields
Timestamp format
This endpoint reads no timestamp fields./users is fetched in full every
sync and is not watermarked, so any created_at or updated_at you send on a
user is ignored.
Fields the adapter ignores
Sending any of these has no effect — do not spend effort populating them:phone— dropped. There is no phone column on a user, so aphoneyou send is discarded. See Limitations → Fields dropped entirely.- Any
created_at/updated_at—/usersis not incremental, so timestamps here are not read. - Any other key not listed in the Fields table — users retain no raw copy, so anything unlisted is dropped entirely.
Identity & cross-references
- Identity:
idis the stable primary key. HunterAI upserts by(connection, id), so a user’sidmust never change — a changedidis ingested as a brand-new user, orphaning every deal, task, and call that pointed at the old one. - Referenced by other entities: each
responsible_user_idon/leads,/contacts,/tasks, and/callsresolves to a useridreturned here. Return every user any of those entities can reference, or their attribution is left unresolved. /usersitself points at no other entity.
Incremental sync
This endpoint is not incremental./users receives no updated_since and is
fetched in full on every sync — return your complete current list of managers
every time. This collection is expected to be small (tens to low hundreds of
rows). See
How sync works → Incremental sync.
Deletion behaviour
Users have no tombstone — there is nois_deleted on a user. Because the
upsert only inserts and updates, a user you remove from your response is not
deleted from HunterAI; it simply stops being refreshed and the historical row
persists. To mark a manager as gone, set is_active: false rather than dropping
them from the response — that keeps their past attribution while excluding them
from live reporting. Only leads support deletion, via is_deleted — see
Limitations → Tombstones.
Failure modes
A page of users (up to 100 records) is validated and written as one transaction. The consequences:- A single malformed user fails the whole page. If any user on a page cannot
be processed — a missing
id, or an over-lengthid— none of the users on that page are saved. This is page-level, not per-record. - A failed page fails the sync. Because
/usersis required, a page that fails takes the users entity down with it, and the overall sync is reported failed. Pages that already committed stay committed. 429,5xx, and request timeouts are retried with exponential backoff up to 5 times, then the entity fails; a timeout is retried the same way as a5xx. HunterAI applies its request rate limit per connection, so two connections to the same base URL are throttled independently.- A repeated or unbounded page — a page whose IDs match the previous page, or a run past the page ceiling — fails the entity. See How sync works → Paging.