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

# Lead fields reference

> Every accepted field by group, what it does, and the limits that apply to the repeating ones.

export const UiPath = ({children}) => {
  const parts = String(children).split(/\s*(?:→|>)\s*/).filter(Boolean);
  return <span className="pl-path">
      {parts.map((part, index) => <span key={`${index}-${part}`}>
          {index > 0 && <span className="pl-path__sep">→</span>}
          {part}
        </span>)}
    </span>;
};

export const Screenshot = ({id, alt, caption, frame = 'browser', url, marks = [], lang = 'en', workspace = 'northwind-outbound'}) => {
  const src = `/images/screenshots/${lang}/${id}.png`;
  const chrome = url ? `app.pipelime.ai/${workspace}${url}` : 'app.pipelime.ai';
  return <figure className={`pl-shot pl-shot--${frame} not-prose`}>
      <div className="pl-shot__frame">
        {frame !== 'bare' && <div className="pl-shot__bar">
            <span className="pl-shot__dots">
              <span className="pl-shot__dot" />
              <span className="pl-shot__dot" />
              <span className="pl-shot__dot" />
            </span>
            <span className="pl-shot__url">{chrome}</span>
          </div>}
        <div className="pl-shot__media">
          <img src={src} alt={alt} loading="lazy" />
          {marks.map(mark => <span key={mark.n} className="pl-shot__mark" style={{
    left: `${mark.x}%`,
    top: `${mark.y}%`
  }} aria-hidden="true">
              {mark.n}
            </span>)}
        </div>
      </div>
      {caption && <figcaption className="pl-shot__caption">{caption}</figcaption>}
    </figure>;
};

Every field `POST /leads` and `POST /leads/batch` accept for one lead: the same fields the **Fields** card under <UiPath>Settings → API & Integrations</UiPath> lists, plus the array forms and the handful of extra fields that card leaves out.

<div className="pl-availability">
  <div className="pl-availability__row">
    <div className="pl-availability__label">Where</div>
    <div className="pl-availability__value"><span className="pl-path">Settings<span className="pl-path__sep">→</span>API & Integrations</span></div>
  </div>

  <div className="pl-availability__row">
    <div className="pl-availability__label">Your role needs</div>
    <div className="pl-availability__value">Update access to Lead intake API <code>update-companies</code>. Admin have it by default.</div>
  </div>

  <div className="pl-availability__note">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.</div>
</div>

## 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.              |

### Tags

| 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](/en/leads/custom-fields-and-collected-data) for where it shows up afterwards.

<Screenshot id="api/lead-fields-reference--fields" url="/settings/api" alt="The Fields card in Settings, listing every accepted field as a flat list divided by hairlines, with a Required or One of these marker under the four field names that carry one" caption="The card runs the fields together in one list instead of grouping them, so the small word under a field name is the only thing separating required from optional." />

## 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](/en/developers/post-leads#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.                                                                                                                                                                                                                                                                                                                                                                                        |

<Note>
  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.
</Note>

## Related

<CardGroup cols={2}>
  <Card title="POST /leads" icon="send" href="/en/developers/post-leads">
    The endpoint that accepts every field on this page: status codes, matching, dry run and the full response envelope.
  </Card>

  <Card title="Status vocabularies" icon="list-check" href="/en/reference/status-vocabularies">
    Every enum a lead or its company can be in, and the label each one renders as.
  </Card>

  <Card title="Custom fields and collected data" icon="database" href="/en/leads/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.
  </Card>
</CardGroup>