POST /leads - PipeLime Help Center

One POST creates a person, their company and the tag that puts them into a campaign or workflow. Or it merges into the lead you already have, if you send the same person twice.

Where

Settings→API & Integrations

Your role needs

Update access to Lead intake API update-companies. Admin have it by default.

Authenticated by a workspace API key, not by a signed-in session. Creating a key needs the same permission as the rest of the API settings tab.

Status codes

Status	When
`201 Created`	A brand-new lead was created, and this wasn’t a dry run
`200 OK`	Everything else that succeeds: an update, a skip, or any dry run, including one that would have created
`400 Bad Request`	The `Idempotency-Key` header is longer than the API accepts
`401 Unauthorized`	Missing, invalid, revoked or expired key: see Authentication
`403 Forbidden`	The key is valid but wasn’t granted `leads:write`
`409 Conflict`	`on_duplicate: "error"` and a matching lead already exists, or the same `Idempotency-Key` was sent with a different body
`422 Unprocessable Entity`	The payload fails validation: no `name`, no contact detail, an unknown tag name, a company id from another workspace
`429 Too Many Requests`	Too many calls on this key inside one minute

A dry run that would have created a lead still returns 200, not 201. The status code alone can’t tell you what happened. Read meta.status in the body instead; it’s the one field every code path sets.

POST /leads/batch doesn’t follow this table. Once the request itself validates it always returns 200, with a per-row outcome inside the body, so one bad row can’t fail the rest. See POST /leads/batch.

Request body

name is the only always-required field. Alongside it, send at least one way to reach the person.

Field	Rule
`name`	Always required
`email`, `phone`, `linkedin_url`	Send at least one of the three, or in their place, a non-empty `emails` or `phones` array

Everything else (job_title, description, gender, language, decision_maker, links, location, tags, tag_ids, a company block, and custom_fields) is optional and, when present, lands in the same request. custom_fields lands in the same place a workflow’s collect-data block writes to, so a value you send is readable inside a workflow immediately; see Custom fields and collected data. Each key is slugified before it is stored (Plan tier becomes plan_tier), and any value that is itself an object or an array is dropped rather than flattened. The full list, grouped and described field by field, is on the lead fields reference.

curl -X POST 'https://api.pipelime.ai/api/v1/leads' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Jane Doe",
    "email": "jane.doe@acme-demo.test",
    "tags": ["Inbound"]
  }'

{
  "name": "Jane Doe",
  "email": "jane.doe@acme-demo.test",
  "tags": ["Inbound"]
}

{
  "name": "Jane Doe",
  "email": "jane.doe@acme-demo.test",
  "job_title": "Head of Growth",
  "company": {
    "website": "https://acme-demo.test"
  },
  "tags": ["Inbound"]
}

Matching and duplicates

Before the lead or its company is touched, we look for an existing lead in your workspace using the strongest identifier first:

Order	Matched on	`matched_on` reads
1	Any email address in the payload	`email address`
2	The profile handle inside `linkedin_url`	`LinkedIn profile`
3	A phone number, compared on its trailing digits so the same number with and without a country code still matches	`phone number`

A name is never part of matching. Two people who happen to share one are two people, and merging them would be unrecoverable. Matching never reaches outside the workspace the key belongs to. on_duplicate decides what happens when a match is found:

`on_duplicate`	What happens
`update` (default)	Merges the payload into the existing lead. `meta.status` is `updated`.
`skip`	Leaves the existing lead untouched and returns it as-is. `meta.status` is `skipped`.
`error`	Rejects the call with `409 Conflict` instead of touching anything.

On update, a supplied field wins over what’s on file. But only if you actually sent it; anything you leave out is left alone. name only overwrites when it’s genuinely different, not just re-cased. The lead’s stage is never rolled back to Untouched, even if it had already moved further along your pipeline.

A lead that already has a company keeps it. A company block in this call fills that company’s description, industry and size only where they are blank, and adds a website, a LinkedIn page, contacts or a location alongside what is already there. But it never moves the lead to a different company, even one your payload names explicitly. That’s deliberate: re-posting the same person can’t orphan their campaign history. When the company.name you send differs from the name on file, meta.warnings says the payload’s company was ignored.

A rejected duplicate (on_duplicate: "error") gets its own response shape, not the usual envelope:

409 Conflict

{
  "message": "A lead with this email address already exists in this workspace.",
  "error": "duplicate_lead",
  "matched_on": "email address",
  "lead_id": 4821
}

How the company is resolved

A lead you already have keeps the company it already belongs to. For a person we haven’t seen before, the company is resolved in this order:

company.id, when you send one and it belongs to your workspace. An id we can’t find fails with 422.
A domain: company.website first, and only if you didn’t send a usable one, the domain of the person’s email, and then only when it isn’t a shared free-mail domain. The domain is matched against the websites of companies already on file; if nothing matches, a company is created from it. Once a domain is in play the steps below are never reached.
company.name, matched case-insensitively against companies on file, and created if nothing matches.
Nothing usable: a placeholder company named after the person, so the lead always has one.

Only a company created from a domain (step 2) is analyzed: creating one queues a background scan of its website, which is what keeps the outreach from reading as generic. A company created from a bare name, or the placeholder, has nothing to scan and is used as you sent it. enrich: false skips the scan; the company is still created. meta.company.enrichment_queued reports whether an analysis was queued.

Dry run

dry_run: true runs the real thing inside a database transaction that always rolls back, so every check (column limits, matching, company resolution) behaves exactly as it would live. Nothing it writes survives the call.

A dry run never fires a queued job, even though everything else runs for real inside the rollback. Tag application, the website analysis and the trigger a new lead normally fires are all explicitly skipped. A queued job can’t be undone by rolling back a transaction, so a preview would otherwise have real side effects.

Every id in the response is null on a dry run (data.id, data.company.id, meta.lead_id, meta.company.id, and the id on each entry in tags_applied), so a preview response can never be mistaken for a saved record. One field to read carefully: meta.company.enrichment_queued still reads true on a preview. It tells you what a real call would queue, not what this one did.

Response envelope

The body is always { data, meta }. data is the lead in full, the same shape GET /leads/{id} returns:

Field	Type	Notes
`id`	integer or `null`	`null` on every dry run
`name`	string
`job_title`, `description`, `gender`, `language`	string or `null`
`decision_maker`	boolean or `null`
`stage`	string	`untouched` on a new lead: see pipeline stages
`source`	string	`api` for a lead created here, which is how you tell these apart from search or manual leads
`emails`, `phones`	array of strings
`links`	array of `{ type, url }`
`location`	object or `null`
`tags`	array	This lead’s full tag list after the call
`company`	object or `null`	The company this lead belongs to
`created_at`, `updated_at`	timestamps

meta is the part worth reading closely. It’s the answer to “I posted a lead and nothing seems to have happened”:

Field	Type	What it means
`status`	`created`, `updated` or `skipped`	What this call actually did
`created`	boolean	Shorthand for `status === "created"`
`duplicate`	boolean	True whenever `status` isn’t `created`
`dry_run`	boolean	Echoes whether this call was a preview
`lead_id`	integer or `null`	`null` on every dry run
`company`	object or `null`	`id`, `name`, `created` and `enrichment_queued`
`tags_applied`	array of `{ id, name }`	The tags this call resolved from `tags` and `tag_ids`, not the lead’s full list, which is `data.tags`
`tags_created`	array of strings	Names of tags that didn’t exist yet and were created by this call
`warnings`	array of strings	Notices worth reading: an unset tag, a merged duplicate, a company preserved instead of overwritten, and more

A successful create

{
  "data": {
    "id": 4821,
    "name": "Jane Doe",
    "job_title": null,
    "stage": "untouched",
    "source": "api",
    "emails": ["jane.doe@acme-demo.test"],
    "phones": [],
    "tags": [{ "id": 12, "name": "Inbound" }],
    "company": { "id": 930, "name": "acme-demo.test" }
  },
  "meta": {
    "status": "created",
    "created": true,
    "duplicate": false,
    "dry_run": false,
    "lead_id": 4821,
    "company": { "id": 930, "name": "acme-demo.test", "created": true, "enrichment_queued": true },
    "tags_applied": [{ "id": 12, "name": "Inbound" }],
    "tags_created": [],
    "warnings": ["Created company \"acme-demo.test\" from the email domain and queued a website analysis; its profile will fill in within a few minutes."]
  }
}

That example is trimmed to keep it readable. A real body carries every field in the two tables above, including the ones that came back null.

Automations

Creating a lead through this endpoint fires the same New Lead Ready trigger a workflow uses to react to a brand-new lead, even though, unlike a lead found through search, it’s born already analyzed rather than working through an enrichment pipeline first. Only a genuine created outcome fires it: an update or a skip does not. Tags are the other way in, and they work on an update too. Attaching a tag the lead didn’t already carry fires the Tag Added trigger, whatever put it there. So re-posting a person with a tag they don’t have yet can start a workflow, even though meta.status reads updated. Re-sending a tag they already carry changes nothing and fires nothing. Creating a lead through this endpoint doesn’t spend credits. You’re handing over data you already have, not asking us to find it.

Retrying safely

Add an Idempotency-Key header and a retried call with the exact same body returns the original response instead of creating a second lead: the difference between a network timeout being harmless and it silently duplicating your pipeline. Reusing the same key with a different body is rejected outright. Full mechanics are on Idempotency, deduplication and rate limits.

Lead fields reference

Every field this request accepts, grouped and described one by one.

POST /leads/batch

Send many leads in one call and read the outcome of each row on its own.

Idempotency, deduplication and rate limits

Retry safely, and see what happens when you send too fast.

Errors reference

Every status the API returns and what to change before retrying.

​Status codes

​Request body

​Matching and duplicates

​How the company is resolved

​Tags

​Dry run

​Response envelope

​Automations

​Retrying safely

​Related

Lead fields reference

POST /leads/batch

Idempotency, deduplication and rate limits

Errors reference

Status codes

Request body

Matching and duplicates

How the company is resolved

Tags

Dry run

Response envelope

Automations

Retrying safely

Related