HunterAI maps every source into one canonical, source-blind model. Once ingested,
nothing downstream — dashboards, funnels, AI coaching — knows whether a row came from
amoCRM or your custom CRM. This page explains what each entity becomes and the handful of
conventions that apply everywhere.
What HunterAI derives from each entity
Conventions that apply everywhere
IDs are strings
Every id you return — and every cross-reference like pipeline_id, stage_id,
responsible_user_id, contact_ids, lead_id — is coerced to a string on ingest. Use
whatever ID scheme you like: numeric, UUID, or prefixed slugs (pipe-sales, stg-won).
The only hard rule: an ID must be stable for the life of the record, because it is half
of the (connection, id) upsert key.
If a record’s id changes between syncs, HunterAI treats it as a new record and the
old one is orphaned. Never recycle or renumber IDs.
Cross-references are by ID, never nested objects
A lead points at its pipeline, stage, owner, and contact by ID. HunterAI resolves the
relationships on its side. You do not embed the full pipeline object inside a lead — you
send pipeline_id, stage_id, responsible_user_id, and contact_ids.
Timestamps are ISO-8601 strings
All timestamps are ISO-8601 strings. Both of these are accepted:
- A timestamp with no timezone is interpreted as UTC.
- An unparseable timestamp becomes
null for that field — it does not reject the
record or fail the page. A null updated_at, however, means the record cannot
participate in the watermark, so keep your timestamps valid.
updated_at is load-bearing: it is both the updated_since filter field and the
watermark. See How sync works.
Custom fields
/contacts and /leads accept a flat custom_fields object:
HunterAI stores it as a list of { "name": …, "value": … } pairs. Values may be any JSON
type. Custom fields are retained but are not interpreted by analytics in v1.0.
String fields are truncated, not rejected
Text fields have maximum accepted lengths. A value longer than the limit is silently
truncated to fit — it never rejects the record. The exact limit is listed on each
endpoint page and collected in
Limitations → Truncation.
Raw payloads
For leads, events, and calls, HunterAI keeps your full raw JSON alongside the
mapped columns (useful for later reprocessing). Contacts, users, pipelines, stages, and
tasks do not retain a raw copy — any field on those entities that this spec does not map
is dropped. Don’t rely on sending extra fields on those entities; send what the reference
documents.
Tenancy
A HunterAI business can hold more than one connection. Every ingested row is stamped with
the connection it came from, and that stamp is applied by HunterAI — never trusted from
your payload. Your data is isolated per connection; two connections never see each other’s
rows. 
