Skip to main content
This guide shows how to keep leads in sync between your system (a CRM, an ERP, a spreadsheet robot) and SalesOS, in both directions, using the Leads API. It covers the four problems every two-way sync has: 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

Call list_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, use close_lead.
  • If a call returns STAGE_NOT_FOUND, the company changed the pipeline: call list_pipelines again and review the map.

2. Initial load

Bring your leads in with sync_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:
  1. Apply each item in your system (find it by external_id + source, or by id).
  2. While has_more is true, call again with cursor = next_cursor (same filters).
  3. When has_more is false, save sync_watermark and use it as the next updated_since.
Why 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:
A placeholder alone in a value keeps its type: 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:
  1. Ignore your own changes: if change_source.api_key_id is your key’s ID, it is the echo of your own write.
  2. Ignore old news: if you already applied a version equal or higher for that lead, skip it. Deliveries can repeat and arrive out of order.
  3. Apply it, or just call get_lead and apply the current lead.
Webhooks are delivered on a best-effort basis, with retries. Keep the feed running anyway, less often, to catch anything a delivery missed.

5. Your system → SalesOS: writing without loops or overwrites

When something changes on your side, call the matching action: On every write:
  • Send idempotency_key with 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_version with the version you last saw. If someone changed the lead in SalesOS in the meantime, you get 409 VERSION_CONFLICT and 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_MISSING says what is missing (details), and 202 pending_approval means the lead’s leader must approve: the lead stays where it was until then, and the change appears in the feed when approved.
Your writes come back neither in the feed (with 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 with sync_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:read and leads:write
  • Stage map by ID, refreshed on STAGE_NOT_FOUND
  • Feed with updated_since = last sync_watermark, exclude_own_changes: true, include_archived: true
  • Applying the same item twice changes nothing (compare version)
  • Every write with idempotency_key; edits with expected_version
  • 409 VERSION_CONFLICT, 422 STAGE_REQUIREMENT_MISSING and 202 pending_approval handled
  • Webhooks (if used) ignore your own key and old versions; the feed keeps running