Skip to main content
Try signed requests in your browser at the API Sandbox — paste your API key and secret, and the playground signs requests automatically.
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.
The Leads API lets your system work with the leads of the API key’s company: list and read them, create and update them, move them through the pipeline, mark them won or lost, archive them and log notes and activities. Keeping two systems in sync is covered step by step in Two-way sync.

Before you start

  • One endpoint, one action per call. Every call is a POST to https://api.play2sell.com/functions/v1/default-integration with "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 needs leads:write. One does not imply the other, and neither opens sync_collaborators or sync_activities. A key without the scope gets 403 with code: "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 from stage.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 and get_lead accept either form:
  • lead_id: the SalesOS ID (UUID);
  • external_id + source: your ID, within the source you used when creating it (default api).
Sending both returns 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

string
SalesOS ID (UUID). Or send external_id.
string
Your ID (max 255).
string
With external_id. Default api.
The answer is always 200: { "data": { "found": true, "lead": { … } } }, or { "found": false, "lead": null } when the lead does not exist in the company.

Action: list_leads

object
All optional, combined with AND. An unknown filter returns 400, so a typo never returns everything.
object
{ "by": "updated_at" | "created_at", "direction": "asc" | "desc" }. Default: updated_at ascending when updated_since is sent, otherwise newest first.
integer
1–500, default 100. Larger values are reduced to 500.
string
next_cursor from the previous page.
The cursor is tied to the filters and sort that produced it. Changing them in the middle of a pagination returns 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_key and expected_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 the stage_id you send.

How a lead is recognized

For each item we look for an active lead of the company in this order:
  1. the same external_id within the same source (two sources never mix);
  2. the same email (case-insensitive);
  3. the same phone.
Found: update. Not found: create. If the email belongs to one lead and the phone to another, the item returns 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

string
Where the leads come from, lowercase: letters, digits, _ . - (max 60). Default api.
string
Optional. See Retrying safely.
array
required
Array of leads (max 100).
string
required
Unique ID of the lead in your system (max 255).
string
Max 200. To create, send at least one of name, email and phone.
string
Customer email.
string
With country code, e.g. +5511987654321. Without one, the company’s country is assumed.
string
CPF (11) or CNPJ (14) digits; punctuation is ignored.
string
Max 200.
string
Max 300.
string[]
Up to 20 tags, 60 characters each.
string
Owner. Unknown or inactive: the lead goes to the default owner, with a warning.
string
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.
object
Label → text. Up to 50 fields, 1,000 characters each.
object
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 returns status: "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.
object
required
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).
Answer: 200 with { "data": { "result": "updated", "lead": { … } } }.

Action: move_lead_stage

Moves the lead to stage_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.
string
required
Stage ID from list_pipelines.
string
When the stage requires a document: an http(s) link to it.
string | number
When the stage requires a field (requirements.field).
string
When the target stage has outcome: "lost" (1–500 characters).
number
Updates the lead’s value together with the move.
string
Message to the leader when the stage requires approval (max 1,000).
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 that outcome, following the same rules as move_lead_stage.
string
required
won or lost.
string
Only with lost.
number
Final value.
If the pipeline has no stage with that outcome: 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 from sync_activities).
string
The lead. Or send lead_external_id + lead_source.
string
Your ID of the lead (with lead_source, default api).
string
required
note, call, whatsapp, email, meeting or visit.
string
Up to 5,000 characters. Required for note.
string
When it happened (ISO 8601). Default: now. Cannot be in the future.
string
Who did it: an active user of the company. Default: the lead’s owner.
string
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.
string
inbound or outbound (calls, messages).
integer
0–86,400.
Answer 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.
string
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.
string[]
Only these types, e.g. ["note", "call"].
integer
1–500, default 100.
string
next_cursor from the previous page.
Answer: { "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 an idempotency_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 the version 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.