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.

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, in the same shape `POST /leads` returns in its `data`

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 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. {id} must be numeric; anything else doesn’t match this route at all. A lead outside the key’s workspace returns the exact same 404 as an id 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 you don’t have access to exists. The response is identical either way.

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, and every relation on it 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
`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

curl https://api.pipelime.ai/api/v1/leads/4821 \
  -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"
    },
    "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