Conformance checklist

Tick every box below before your business owner creates the connection. Each item is a requirement the adapter depends on — not a wish list.

​

Transport & auth

• All endpoints are served over HTTPS under one versioned base URL.
• Every request requires Authorization: Bearer <token>; a bad token returns 401.
• The token is read-only and can be revoked/rotated independently.

​

Envelope & paging

• Every collection returns { "data": [...], "has_more": <bool> }.
• has_more is true only when another page exists, and false on the last page.
• Endpoints honour page (1-based) and limit=100.
• An empty result returns 200 with { "data": [], "has_more": false } — never 404.
• No record appears on two pages of the same run; pages never repeat.

​

Required endpoints

• GET /pipelines returns pipelines with nested stages[].
• Every stage’s kind is exactly open, won, or lost.
• GET /users returns your managers.
• GET /contacts returns contacts.
• GET /leads returns deals with pipeline_id + stage_id.

​

Optional endpoints

• /events, /tasks, and /calls are either implemented or return 404.
• Every /calls record has a lead_id or a contact_id.

​

Incremental sync

• /contacts, /leads, /tasks, /calls, /events accept updated_since and filter on updated_at >= updated_since.
• Those endpoints return records ordered by updated_at ascending.
• Every record carries a valid updated_at, and updated_at changes on every modification — including stage moves and soft-deletes.
• /pipelines and /users return the full list every time (they get no updated_since).

​

IDs & references

• Every record has a stable id that never changes for the life of the record.
• Cross-references (pipeline_id, stage_id, responsible_user_id, contact_ids, lead_id) use those same ids.

​

Data expectations

• price on leads is in one consistent currency per connection (currency is not stored).
• The most representative contact is first in contact_ids (only the first is kept).
• Deletions you need reflected are sent as is_deleted: true on leads (no soft-delete exists for other entities).
• Timestamps are ISO-8601; you have reviewed the truncation limits for your longest text fields.

​

Errors

• 429 responses include a Retry-After header where possible.
• Transient failures return 5xx; genuine client errors return 4xx.