You need a key with
leads:read and leads:write. Use one key per integration: the key is how SalesOS tells your changes from everyone else’s.
1. Map pipelines and stages once
Calllist_pipelines and map your statuses to SalesOS stage IDs. Keep these rules:
- Map by
stage.id, never by name: each company names and orders its stages as it wants, and renames them. - Read won/lost from
stage.outcome(open,won,lost). To mark won or lost without knowing the stage, useclose_lead. - If a call returns
STAGE_NOT_FOUND, the company changed the pipeline: calllist_pipelinesagain and review the map.
2. Initial load
Bring your leads in withsync_leads, 100 per call, each with your external_id and the same source (for example my-crm). From then on you can address any lead by external_id + source, without storing SalesOS IDs.
To read what already exists in SalesOS, page through list_leads until has_more is false.
3. SalesOS → your system: the change feed
Every few minutes, ask for what changed since your last checkpoint:- Apply each item in your system (find it by
external_id+source, or byid). - While
has_moreistrue, call again withcursor=next_cursor(same filters). - When
has_moreisfalse, savesync_watermarkand use it as the nextupdated_since.
sync_watermark and not the time of your call: a change saved by a long operation can carry an updated_at slightly in the past. sync_watermark already accounts for that, so no change is skipped. Some items may come twice across runs; applying them again must do nothing (compare version).
exclude_own_changes leaves out leads whose latest change was made by your key, so your own writes do not come back to you. include_archived makes archived leads appear, so you can archive them on your side too.
To know what changed in a lead, not only that it changed, call get_lead_history: each entry has the fields with old and new, and change_source says whether it came from the app or from which API key.
4. Real time with webhooks (optional)
The feed is enough to sync. To react within seconds, also subscribe to the lead sync events in Integrations → Webhooks (see Webhooks):
In the webhook’s Payload Template, these fields are available:
version arrives as a number and changes as an object ({ "stage_id": { "old": "…", "new": "…" } }). Check it with Preview and Test before saving.
When a delivery arrives:
- Ignore your own changes: if
change_source.api_key_idis your key’s ID, it is the echo of your own write. - Ignore old news: if you already applied a
versionequal or higher for that lead, skip it. Deliveries can repeat and arrive out of order. - Apply it, or just call
get_leadand apply the current lead.
5. Your system → SalesOS: writing without loops or overwrites
When something changes on your side, call the matching action:
On every write:
- Send
idempotency_keywith an ID that is unique for that change on your side (for example your event or audit ID). If the network fails, retry with the same key: it is done once. - Send
expected_versionwith theversionyou last saw. If someone changed the lead in SalesOS in the meantime, you get409 VERSION_CONFLICTand nothing is overwritten: read the lead, decide (merge field by field, or let the most recent win), and write again. - Expect stage rules. Moving forward follows the stage’s requirements exactly as in the app.
422 STAGE_REQUIREMENT_MISSINGsays what is missing (details), and202 pending_approvalmeans the lead’s leader must approve: the lead stays where it was until then, and the change appears in the feed when approved.
exclude_own_changes) nor as an echo you cannot recognize (change_source.api_key_id in webhooks and history).
6. Points and missions
Changes made through the API update the lead, its stage and its history, but do not score points. If your system is where salespeople do their work, send what should score as activities withsync_activities, mapped to missions in the Dashboard. That keeps points counted once, even when the same lead moves on both sides.
Checklist
- One API key for this integration, with
leads:readandleads:write - Stage map by ID, refreshed on
STAGE_NOT_FOUND - Feed with
updated_since= lastsync_watermark,exclude_own_changes: true,include_archived: true - Applying the same item twice changes nothing (compare
version) - Every write with
idempotency_key; edits withexpected_version -
409 VERSION_CONFLICT,422 STAGE_REQUIREMENT_MISSINGand202 pending_approvalhandled - Webhooks (if used) ignore your own key and old versions; the feed keeps running

