Lead fields reference - PipeLime Help Center

Every field POST /leads and POST /leads/batch accept for one lead: the same fields the Fields card under lists, plus the array forms and the handful of extra fields that card leaves out.

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.

Required

name is the only field the API always requires. Alongside it, send at least one of email, phone or linkedin_url. Or, instead of any of those, send a non-empty emails or phones array. A request with none of the five fails validation, and the error names only the three singular fields even though the array forms satisfy it too.

Fields

Identity

Field	Type	Required	What it is
`name`	string	Yes	The person’s full name. The only always-required field.

Contact

Field	Type	Required	What it is
`email`	email	One of these	Work email. A business domain also identifies their company automatically.
`phone`	phone	One of these	Any format works, we normalize it. Used for WhatsApp outreach.
`linkedin_url`	url	One of these	Their LinkedIn profile. Used for LinkedIn outreach and for deduplication.

Person

Field	Type	Required	What it is
`job_title`	string	No	Their role. Strongly improves how the AI writes to them.
`description`	longtext	No	Anything useful about this person or how they arrived. Fed to the AI writing the outreach.
`language`	string	No	Preferred language for outreach.
`decision_maker`	boolean	No	Mark them as a decision maker.
`custom_fields`	keyvalue	No	Any extra data, up to 25 keys. Readable inside workflows as a collected field.

Company

Field	Type	Required	What it is
`company.name`	string	No	Company name. Optional when the email is on a company domain.
`company.website`	url	No	Best field you can send after the email: we analyze the site and write better outreach.
`company.linkedin_url`	url	No	The company’s LinkedIn page.
`company.industry`	string	No	Free text, e.g. “Software”, “Logistics”.
`company.size`	string	No	Headcount band, free text.
`company.description`	longtext	No	Only used when we cannot analyze the website ourselves.

Location

Field	Type	Required	What it is
`location.country`	string	No	Country name or ISO code.
`location.city`	string	No	City.
`location.state`	string	No	State or region.
`location.zip_code`	string	No	Postal code.

Field	Type	Required	What it is
`tags`	tags	No	Tag names. This is what puts the lead into a campaign or workflow, so send at least one.

Options

Field	Type	Required	What it is
`on_duplicate`	string	No	”update” (default) merges into the existing lead, “skip” leaves it alone, “error” returns 409.
`create_missing_tags`	boolean	No	Default true. Set false to reject unknown tag names instead of creating them.
`enrich`	boolean	No	Default true. Set false to skip the automatic website analysis of new companies.
`dry_run`	boolean	No	Validate and preview without saving anything and without triggering any automation.

The last group in that table is different in kind. on_duplicate, create_missing_tags, enrich and dry_run are switches for the call, not fields on the lead: in a batch you send them once, beside leads, and they apply to every row. custom_fields deserves one more sentence: each key is slugified before it’s stored (Plan tier becomes plan_tier), a boolean value is stored as the text yes or no, and any value that is itself an object or an array is dropped instead of being flattened. See Custom fields and collected data for where it shows up afterwards.

Fields the card above doesn’t list

A few fields the API accepts aren’t in the Fields card, so they aren’t in the table above either. They come straight from the request’s own validation.

Field	Type	What it is
`gender`	string	Free text, stored on the lead the same way as `job_title` and `language`.
`location.address`	string	Street address. `location.country`, `location.city`, `location.state` and `location.zip_code` are in the table above; this one isn’t.
`company.id`	integer	Targets one company already in your workspace directly, instead of letting a domain or a name resolve one. An id that isn’t in your workspace is rejected: with a 422 on `POST /leads`, and as a single failed row inside the 200 on `POST /leads/batch`. See how the company is resolved when you don’t send this.
`company.location.country`, `.state`, `.city`, `.address`, `.zip_code`	string	The same five location fields as above, describing the company instead of the person.

Fields that accept more than one value

Field	What it adds
`emails`	More addresses for the same person, alongside `email`. Also counts on its own toward the “at least one contact detail” requirement.
`phones`	More numbers for the same person, alongside `phone`. Both are normalized to digits before the combined list is capped, so formatting differences like spaces or dashes don’t produce two entries for the same number. A value left with fewer than seven digits is discarded at that point, silently and without failing the call, so a lead sent with only a too-short `phone` is created carrying no number. Also counts on its own toward the contact requirement.
`links`	Public profiles beyond `linkedin_url`: each entry needs a `type`, from a fixed set of link kinds the request validates against, and a `url`.
`tag_ids`	Tag ids instead of names. An unrecognized name in `tags` is created for you unless you send `create_missing_tags: false`; an unrecognized id is never created whatever that switch says, and is rejected the same way `company.id` is: the whole call on `POST /leads`, that row alone in a batch.
`company.emails`, `company.phones`	The same array fields as above, attached to the company instead of the person.

Every array field above has its own cap, enforced before anything is saved: go over it and the whole request fails with a 422 naming that field. email and emails are the one pair worth knowing about beyond that. Each already passes its own check on its own, but the two are then combined into a single address list and that combined list is capped again, so filling both fields to their individual limits can still mean the address you listed last doesn’t get kept. phone and phones behave the same way.

POST /leads

The endpoint that accepts every field on this page: status codes, matching, dry run and the full response envelope.

Status vocabularies

Every enum a lead or its company can be in, and the label each one renders as.

Custom fields and collected data

Where a value sent in custom_fields shows up afterwards, and the other way a lead picks up collected data.

​Required

​Fields

​Identity

​Contact

​Person

​Company

​Location

​Tags

​Options

​Fields the card above doesn’t list

​Fields that accept more than one value

​Related