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

# Concepts

> The eight words that every response and every tool uses.

Learn these eight words once and the field names explain themselves.

## Person

Someone Ziplined has seen around your workspace. They engaged, they follow you, they
connected, or you added them.

```json theme={null}
{ "id": "7b1f...", "name": "Jane Doe", "job_title": "Head of Growth", "company": "Acme BV" }
```

A person record carries the profile, the relationship and your own notes and tags.

> [accordion] Profile, relationship and annotation fields
>
> Profile: `name`, `headline`, `job_title`, `company`, `company_id`, `company_industry`,
> `company_size`, `country`, `location`, `seniority`, `industry`, connection degree,
> follower and connection counts.
>
> Relationship: `stage`, `fit`, `warmth`, `first_engaged_at`, `last_engaged_at`,
> `last_engaged_type`, `engagements_30d`.
>
> Yours: `notes`, `tags`, `outreach_count`, `last_outreach_at`.
>
> Contact details (`email`, `phone` and their lookup status) need the separate `contacts`
> scope. Without that scope the fields are absent, not `null`.

## Fit

How well someone matches your ideal customer profile.

```json theme={null}
{ "fit": { "score": 84, "tier": "high" } }
```

Score runs 0 to 100. Tier is `none`, `low`, `medium` or `high`. Fit moves only when their
profile or your ICP changes.

## Warmth

How engaged someone has been lately.

```json theme={null}
{ "warmth": { "score": 61, "tier": "warm" } }
```

Score runs 0 to 100. Tier is `cold`, `cool`, `warm` or `hot`. Warmth decays when they go
quiet.

> [!NOTE]
>
> High fit with cold warmth is someone worth warming up. Hot warmth with low fit is an
> audience member, not a lead.

## Stage

Where the relationship stands, as a decision you made.

```json theme={null}
{ "stage": "lead" }
```

One of `lead`, `customer`, `peer`, `watchlist`, `disqualified`, or `null` when undecided.
Set it with `PATCH /v1/people/{person_id}` or the `update_person` tool.

> [accordion] What watchlist and disqualified mean
>
> `watchlist` is a pin: someone you want to keep an eye on.
>
> `disqualified` beats every other stage, so a disqualified person never reads as undecided.

## Audience

A named list of people inside your workspace.

```json theme={null}
{ "id": "c41d...", "name": "NL SaaS founders", "people_count": 184, "companies_count": 96 }
```

Audiences narrow anything that takes a list: a people search, a routing rule, an enrichment
run. In MCP you pass the audience **name**, not the id.

> [accordion] Counts and unknown names
>
> `people_count` and `companies_count` are the state of the last scoring round, not of this
> second.
>
> An unknown audience name in MCP answers with the names that do exist, so no lookup call is
> needed. Archived audiences are left out of `list_audiences`.

## Source

Something whose posts and reactions Ziplined collects. The app calls the set of them your
**radar**.

```json theme={null}
{ "id": "a19f...", "type": "company", "display_name": "Acme BV", "source_kind": "competitor", "status": "active" }
```

A source is a person, a company or a keyword query. `source_kind` is `team`, `competitor`,
`influencer` or `market`. `GET /v1/sources` answers "why is this person in my list".

> [accordion] Pausing a source
>
> A source is `active`, `paused` or `removed`. Pausing stops collection and keeps everything
> already gathered.

## Post

One of your own posts, with its numbers.

```json theme={null}
{ "post_id": "urn:li:activity:74...", "likes": 38, "comments": 12, "impressions": 4210 }
```

These are your posts, not the posts of the sources you track. Feed a `post_id` into a people
search to see who engaged with it.

## Engagement

One act by one person on one post: a like, a comment or a share.

```json theme={null}
{ "person_id": "7b1f...", "type": "comment", "day": "2026-09-11", "via": "Acme BV" }
```

Engagement is the raw layer under warmth. It records a UTC day and the source it arrived
through.

> [accordion] Reading engagements
>
> `GET /v1/engagements` requires a `person_id`. The read binds on the people you name, not on
> the whole workspace.
>
> For "who engaged with this post", use the people search with the post id instead.

## Outreach

What you sent, as opposed to engagement, which is what they did.

```bash theme={null}
curl -X POST https://api.ziplined.io/v1/people/7b1f.../touches \
  -H "Authorization: Bearer $ZIPLINED_API_KEY" \
  -H "Idempotency-Key: 3f1b2c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d" \
  -H "Content-Type: application/json" \
  -d '{"channel":"email","note":"Sent the Q4 deck"}'
```

A channel is `linkedin_message`, `email`, `call` or `other`. Logging outreach is what makes
"warm and never approached" a filter you can trust.

> [!WARNING]
>
> `outreach_count` and `last_outreach_at` on the person record are rebuilt nightly. They lag
> one night behind. The act itself is readable straight away in the person detail.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.