GET /me, GET /tags and GET /leads/{id}

Three calls that only read: confirm your key and see its workspace, list this workspace’s tags, and read one lead back by id or email, including whether we have emailed them and whether they replied.

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.

The three endpoints

Method & path	Scope required	Returns
`GET /me`	None	The workspace this key belongs to, the key’s own details, and its rate limit
`GET /tags`	`tags:read`	The workspace’s tags, ordered by name: the active ones unless you ask for archived too
`GET /leads/{id}`	`leads:read`	One lead, by id or email: the shape `POST /leads` returns in its `data`, plus `outreach` and `campaigns`

Every timestamp these three return is UTC ISO-8601 with microseconds: 2026-08-21T09:14:02.000000Z.

Status codes

Status	When	Applies to
`200 OK`	The call succeeds	All three
`401 Unauthorized`	Missing, invalid, revoked or expired key: see Authentication	All three
`403 Forbidden`	The key is valid but wasn’t granted the scope its route needs	`GET /tags`, `GET /leads/{id}`
`404 Not Found`	No lead with this id or email exists in this workspace	`GET /leads/{id}` only
`429 Too Many Requests`	Too many calls on this key inside the current window	All three

GET /me

No scope is required for this one. Any key, whatever it’s scoped for, can call it. That makes it the fastest way to confirm a credential works before you build anything else on it, and the right endpoint to wire into your own monitoring as a health check.

Response

Field	Type	Notes
`data.workspace.id`	integer
`data.workspace.name`	string
`data.api_key.name`	string	The label given when the key was created
`data.api_key.prefix`	string	The public half of the key
`data.api_key.scopes`	array of strings	Any of `leads:write`, `leads:read`, `tags:read`
`data.api_key.expires_at`	timestamp or null	Null for a key created with no expiry: see Create, roll and revoke API keys
`data.api_key.last_used_at`	timestamp or null	Null for a key that has never made a request
`data.rate_limit.requests_per_minute`	integer	This key’s per-minute request budget
`data.rate_limit.batch_max`	integer	The most leads one `POST /leads/batch` call accepts

curl https://api.pipelime.ai/api/v1/me \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": {
    "workspace": { "id": 42, "name": "Acme Freight" },
    "api_key": {
      "name": "Production integration",
      "prefix": "plk_live_a1B2c3D4",
      "scopes": ["leads:write", "tags:read"],
      "expires_at": null,
      "last_used_at": "2026-08-30T12:04:00.000000Z"
    }
  }
}

That example leaves out rate_limit to keep it short. It’s the two integer fields in the table above. See Idempotency, deduplication and rate limits for what they’re currently set to.

GET /tags

Returns every tag in the workspace the key belongs to, ordered by name. There’s no pagination on this list: by design, since a workspace has tens of tags, not thousands, so there’s nothing here worth adding a cursor for. By default only tags with active: true come back. Pass include_archived=true to also get the ones that have been archived.

Query parameters

Param	Type	Default	Effect
`include_archived`	boolean	`false`	Also return archived tags (`active: false`)

Response

Field	Type	Notes
`data[].id`	integer
`data[].name`	string
`data[].color`	string or null	Null for a tag saved without one
`data[].active`	boolean	`false` only appears when the call passed `include_archived=true`

curl https://api.pipelime.ai/api/v1/tags \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": [
    { "id": 12, "name": "Inbound", "color": "#4F46E5", "active": true },
    { "id": 18, "name": "Cold outreach", "color": "#10B981", "active": true }
  ]
}

GET /leads/

Needs its own leads:read scope, separate from leads:write, which only guards the two POST routes. It is not a default scope: tick it when you create the key, or the call is a 403 insufficient_scope. {id} is either the numeric id from a create response or a URL-encoded email address (jane.doe%40acme.com). A LinkedIn profile URL or a phone number work too. It is resolved with the same precedence POST /leads deduplicates on (email, then LinkedIn, then phone, oldest match first), so the lead this returns for an address is exactly the one a POST with that address would have updated. A lead outside the key’s workspace returns the exact same 404 as an id or email that doesn’t exist anywhere:

404 Not Found

{
  "message": "Lead not found in this workspace.",
  "error": "not_found"
}

This endpoint can never confirm whether an id or address you don’t have access to exists. The response is identical either way, which also makes the 404 the signal an integration wants: this person is not in the workspace yet, so POST /leads will create rather than update them.

Response

The body is { data }, with no meta: there’s nothing to report about an action, since nothing changed. data is the same lead shape POST /leads returns in its own data field, plus two blocks the POST response does not carry: outreach and campaigns. Every relation is loaded on every call (emails, phones, links, location, tags, and the company’s own links and tags), so none of these fields is ever left out here for lacking an eager load.

This is deliberately not the shape the app’s own screens use internally: no admin-triage columns, CRM bookkeeping, possibility scores or phone-reveal state, and contacts come back as plain string arrays ("emails": ["jane@…"]) instead of objects. So an integration reads lead.emails[0] directly.

Field	Type	Notes
`id`	integer
`name`	string
`job_title`	string or null
`description`	string or null
`gender`	string or null
`language`	string or null
`decision_maker`	boolean
`stage`	string	See status vocabularies
`source`	string	`api` for a lead created through this API: also `search`, `import`, `manual` and the other channels a lead can come from
`emails`, `phones`	array of strings
`links`	array of `{ type, url }`
`location`	object or null	`country`, `state`, `city`, `address`, `zip_code`. A lead can carry several locations; this is the first one
`tags`	array	This lead’s own tags, same shape as `GET /tags`
`company`	object or null	See below
`outreach`	object	Has this person been emailed, did they reply. See below
`campaigns`	array	The campaigns that emailed this person, oldest first. Empty until contacted
`created_at`, `updated_at`	timestamps

company, when present:

Field	Type	Notes
`id`	integer
`name`	string or null
`website`	string or null	The company’s first link of type `website`
`linkedin_url`	string or null	The company’s first link of type `linkedin`
`industry`	string or null
`size`	string or null
`description`	string or null
`status`	string	`pending` while a website analysis is still running
`tags`	array	This company’s own tags, separate from the lead’s
`created_at`	timestamp

outreach, which covers email only, since email is what this API feeds:

Field	Type	Notes
`contacted`	boolean	At least one email has been delivered. Queued and warm-up messages don’t count
`messages_sent`	integer	Emails delivered, across every campaign
`first_contacted_at`, `last_contacted_at`	timestamp or null	Null until contacted
`replied`	boolean	The person wrote back with something that isn’t an automatic reply. A reply not yet classified counts as real
`replies`	integer	Real replies received
`automatic_replies`	integer	Out-of-office and other automatic replies, kept apart so you can tell an autoresponder from silence
`last_reply_at`	timestamp or null	When the latest real reply arrived

replied uses the same rule the app’s own dashboard and reply detection use: an out-of-office never counts as a reply, and a reply the classifier hasn’t looked at yet does. If this endpoint says replied: true, the campaign has stopped following up with that person.

Each entry in campaigns:

Field	Type	Notes
`id`	integer
`name`	string or null
`active`	boolean	Whether the campaign is currently running
`messages_sent`	integer	Emails this campaign delivered to the person
`first_message_at`, `last_message_at`	timestamp or null

curl https://api.pipelime.ai/api/v1/leads/jane.doe%40acme-demo.test \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": {
    "id": 4821,
    "name": "Jane Doe",
    "job_title": "Head of Growth",
    "description": null,
    "gender": null,
    "language": null,
    "decision_maker": true,
    "stage": "contacted",
    "source": "api",
    "emails": ["jane.doe@acme-demo.test"],
    "phones": [],
    "links": [{ "type": "linkedin", "url": "https://linkedin.com/in/janedoe-demo" }],
    "location": null,
    "tags": [{ "id": 12, "name": "Inbound", "color": "#4F46E5", "active": true }],
    "company": {
      "id": 930,
      "name": "acme-demo.test",
      "website": "https://acme-demo.test",
      "linkedin_url": null,
      "industry": null,
      "size": null,
      "description": null,
      "status": "analyzed",
      "tags": [{ "id": 12, "name": "Inbound", "color": "#4F46E5", "active": true }],
      "created_at": "2026-08-21T09:14:02.000000Z"
    },
    "outreach": {
      "contacted": true,
      "messages_sent": 2,
      "first_contacted_at": "2026-08-22T08:30:00.000000Z",
      "last_contacted_at": "2026-08-27T08:30:00.000000Z",
      "replied": true,
      "replies": 1,
      "automatic_replies": 0,
      "last_reply_at": "2026-08-29T15:41:07.000000Z"
    },
    "campaigns": [
      {
        "id": 17,
        "name": "Q3 outbound",
        "active": true,
        "messages_sent": 2,
        "first_message_at": "2026-08-22T08:30:00.000000Z",
        "last_message_at": "2026-08-27T08:30:00.000000Z"
      }
    ],
    "created_at": "2026-08-21T09:14:02.000000Z",
    "updated_at": "2026-08-29T15:41:07.000000Z"
  }
}

API overview

Authentication, scopes and what counts as a stable contract.

Lead fields reference

Every field POST /leads accepts, grouped and described one by one.

Status vocabularies

Every value stage, source and status can hold, and what each renders as.

​The three endpoints

​Status codes

​GET /me

​Response

​GET /tags

​Query parameters

​Response

​GET /leads/

​Response

​Related

API overview

Lead fields reference

Status vocabularies

The three endpoints

Status codes

GET /me

Response

GET /tags

Query parameters

Response

GET /leads/

Response

Related