Examples show the wire-format
Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE header. To compute the signature in your code, use the signedRequest helper in Authentication.Before you start
- One endpoint, one action per call. Every call is a
POSTtohttps://api.play2sell.com/functions/v1/default-integrationwith"action"in the body. Filters also go in the body, because the signature covers the body and not the query string (see Conventions). - Scopes. Reading needs
leads:read; writing needsleads:write. One does not imply the other, and neither openssync_collaboratorsorsync_activities. A key without the scope gets403withcode: "scope_insufficient". Create keys in Admin > Integrations > API Keys. - Each company has its own pipeline. Stage names and order are configured per company and can change at any time. Always use the stage ID from
list_pipelines, and read won/lost fromstage.outcome(open,won,lost), never from the name. - Points stay with Missions. Changes made through this API update the lead, its stage and its history, but do not score points in missions or campaigns. Points from integrations come only from
sync_activities.
The lead object
Every action that returns a lead returns this shape.Identifying a lead
Write actions andget_lead accept either form:
lead_id: the SalesOS ID (UUID);external_id+source: your ID, within thesourceyou used when creating it (defaultapi).
400. A lead of another company is never found: the answer is 404 LEAD_NOT_FOUND.
Reading
Action: list_pipelines
The company’s pipelines and stages, in order. Call it once, cache it, and refresh when a stage ID you hold is rejected.requirements tells you what move_lead_stage will ask for when a lead advances into that stage.
Action: list_lead_fields
The company’s lead fields in screen order, including custom fields.path says where the value appears in the lead object (null = not exposed by the API).
Action: get_lead
200: { "data": { "found": true, "lead": { … } } }, or { "found": false, "lead": null } when the lead does not exist in the company.
Action: list_leads
All optional, combined with AND. An unknown filter returns
400, so a typo never returns everything.{ "by": "updated_at" | "created_at", "direction": "asc" | "desc" }. Default: updated_at ascending when updated_since is sent, otherwise newest first.400 (cursor): start again without a cursor.
Change feed. With updated_since, the list is ordered by updated_at ascending and the answer includes sync_watermark. When has_more is false, use sync_watermark as your next updated_since: no change made before it can still appear later. See Two-way sync.
Action: get_lead_history
Every change to a lead, oldest first: what changed (before/after), the kind of change and who made it.kind is created, updated, stage_changed, archived or restored. changes lists only the fields that changed, each with old and new. Changes are recorded for leads of the leads pipeline.
Writing
All write actions:- answer with the lead as it is after the change, plus
result; - accept an optional
idempotency_keyandexpected_version; - run as one transaction: everything is written, or nothing is.
add_lead_activity answers with the activity instead of the lead, and does not take expected_version.
Action: sync_leads
Create or update up to 100 leads per call: a form on your website, a landing page, another system. A new lead enters the company’s default leads pipeline at the first stage, or at thestage_id you send.
How a lead is recognized
For each item we look for an active lead of the company in this order:- the same
external_idwithin the samesource(two sources never mix); - the same
email(case-insensitive); - the same
phone.
IDENTITY_CONFLICT and nothing is written for it. The same person twice in a batch creates one lead and updates that same lead the second time.
What an update does
Request
Optional. See Retrying safely.
Optional, only for new leads: an open stage of the leads pipeline without requirements (see
list_pipelines). Otherwise the item fails with STAGE_NOT_ALLOWED_ON_CREATE or STAGE_NOT_FOUND.utm_source, utm_medium, utm_campaign, utm_term, utm_content, landing_page, referrer, form_id (500 characters each).Response (200)
One result per lead, in request order. A bad item does not fail the batch: it returnsstatus: "error" and the others go through.
Errors that affect the whole batch (
leads empty or over 100, invalid source or idempotency_key) answer 400 VALIDATION_ERROR.
Action: update_lead
Changes only the fields you send.null clears an optional field. An unknown field returns 400.
name (cannot be cleared), email, phone, document, company_name, product, value (≥ 0), expected_close_date (YYYY-MM-DD), priority (low, medium, high, urgent), notes (max 5,000), buying_moment, is_important, is_starred, owner_email, custom_fields (label → text, or null to remove that field; up to 50), add_tags, remove_tags (up to 20 each).200 with { "data": { "result": "updated", "lead": { … } } }.
Action: move_lead_stage
Moves the lead tostage_id, a stage of the lead’s own pipeline. Moving forward follows the stage’s rules exactly as in the app; moving back is always allowed.
A missing requirement returns
422 STAGE_REQUIREMENT_MISSING, and details says what to send:
Action: close_lead
Marks the lead as won or lost by outcome, whatever the stages are called. It moves the lead to the first stage of its pipeline with thatoutcome, following the same rules as move_lead_stage.
422 NO_STAGE_FOR_OUTCOME. To reopen, use move_lead_stage to an open stage.
Action: archive_lead / restore_lead
archive_lead takes the lead out of the pipeline (status: "archived") without deleting anything. restore_lead brings it back with the status it had. Answers result: "archived", "restored" or "unchanged". An archived lead cannot be updated or moved (409 LEAD_ARCHIVED) until it is restored.
Notes and activities
Action: add_lead_activity
Logs something that happened with the lead. It appears in the lead’s timeline in the app, like activities logged there, and does not score points (points come fromsync_activities).
Your ID of this activity (with
source, default api). Sending the same pair again returns the existing activity (result: "existing", 200) instead of creating another.201 (created) or 200 (already existed):
Action: list_lead_activities
One lead’s timeline (lead_id, or external_id + source), or every activity of the company from since on. Includes what was logged in the app and by integrations, oldest first. Stage changes come as type: "status_change" with stage_change.from_stage_id / to_stage_id.
ISO 8601. Required when no lead is given. Filters by
occurred_at: an activity logged later with a past occurred_at does not show up in a feed that already passed that date.{ "data": { "found": true, "items": [ … ], "next_cursor": null, "has_more": false } }. For a lead that does not exist, found is false.
Retrying safely: idempotency_key
Networks fail. To retry a write without doing it twice, send anidempotency_key (8–255 characters: letters, digits, _ . : -) that is unique for that operation, such as your own event ID.
The key is per API key: two keys never share it. It is in the body, which is signed, not in a header.
Avoiding overwrites: expected_version
To change a lead only if nobody changed it since you read it, send theversion you read as expected_version. If the lead is no longer at that version, nothing is written and the answer is 409 VERSION_CONFLICT, with details.current_version. Read the lead again, merge, and retry.
Errors
Authentication errors (
401, and 403 scope_insufficient when the key lacks leads:read or leads:write) and rate limits (429) have their own format, the same for every endpoint: see Authentication.
