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

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

> Confirm which workspace a key belongs to, list the tags you can apply, and read a lead back.

Three calls that only read: confirm your key and see its workspace, list this workspace's tags, and read one lead back by id.

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

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

<CodeGroup>
  ```bash cURL theme={"system"}
  curl https://api.pipelime.ai/api/v1/me \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```json Response theme={"system"}
  {
    "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"
      }
    }
  }
  ```
</CodeGroup>

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](/en/developers/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` |

<CodeGroup>
  ```bash cURL theme={"system"}
  curl https://api.pipelime.ai/api/v1/tags \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```json Response theme={"system"}
  {
    "data": [
      { "id": 12, "name": "Inbound", "color": "#4F46E5", "active": true },
      { "id": 18, "name": "Cold outreach", "color": "#10B981", "active": true }
    ]
  }
  ```
</CodeGroup>

## GET /leads/{id}

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:

```json 404 Not Found theme={"system"}
{
  "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`](/en/developers/post-leads#response-envelope) 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.

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

| 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](/en/reference/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      |                                                     |

<CodeGroup>
  ```bash cURL theme={"system"}
  curl https://api.pipelime.ai/api/v1/leads/4821 \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```json Response theme={"system"}
  {
    "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"
    }
  }
  ```
</CodeGroup>

## Related

<CardGroup cols={2}>
  <Card title="API overview" icon="compass" href="/en/developers/overview">
    Authentication, scopes and what counts as a stable contract.
  </Card>

  <Card title="Lead fields reference" icon="list" href="/en/developers/lead-fields-reference">
    Every field POST /leads accepts, grouped and described one by one.
  </Card>

  <Card title="Status vocabularies" icon="list-check" href="/en/reference/status-vocabularies">
    Every value `stage`, `source` and `status` can hold, and what each renders as.
  </Card>
</CardGroup>