> ## Documentation Index
> Fetch the complete documentation index at: https://docs.play2sell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Two-way sync

> Keep your system and SalesOS in sync in both directions, without loops, duplicates or overwrites.

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](https://docs.play2sell.com/api/integrations/leads.md). It covers the four problems every two-way sync has:

| Problem | What solves it |
| - | - |
| Missing changes | A change feed with a safe watermark (`list_leads` + `sync_watermark`) |
| Loops (your own write coming back to you) | `exclude_own_changes`, and `change_source` in history and webhooks |
| Duplicates when a call is retried | `idempotency_key` and your `external_id` |
| Overwriting someone else's change | `expected_version` |

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`](https://docs.play2sell.com/api/integrations/leads#action-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`](https://docs.play2sell.com/api/integrations/leads#action-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`](https://docs.play2sell.com/api/integrations/leads#action-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`](https://docs.play2sell.com/api/integrations/leads#action-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:

```json theme={null}
{
  "action": "list_leads",
  "filters": { "updated_since": "2026-11-20T10:00:00.000Z", "exclude_own_changes": true, "include_archived": true },
  "limit": 500
}
```

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`](https://docs.play2sell.com/api/integrations/leads#action-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](https://docs.play2sell.com/api/integrations/webhooks.md)):

| Event | When |
| - | - |
| `lead_sync.created` | A lead was created in the leads pipeline (app, API or integration) |
| `lead_sync.updated` | Lead fields changed |
| `lead_sync.stage_changed` | The lead changed stage, including won/lost |
| `lead_sync.archived` | The lead was archived |
| `lead_sync.restored` | An archived lead came back |

In the webhook's **Payload Template**, these fields are available:

```json theme={null}
{
  "lead_id": "{{lead_id}}",
  "external_id": "{{external_id}}",
  "source": "{{source}}",
  "kind": "{{kind}}",
  "version": "{{version}}",
  "changes": "{{changes}}",
  "change_source": "{{change_source}}",
  "change_id": "{{change_id}}"
}
```

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 your side | Action |
| - | - |
| New lead | `sync_leads` |
| Contact data, owner, value, tags, custom fields | `update_lead` |
| Status change | `move_lead_stage` with the mapped `stage_id` |
| Won / lost | `close_lead` |
| Deleted or discarded | `archive_lead` |

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`](https://docs.play2sell.com/api/integrations/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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.