# Retrieve a contact

> Fetch one contact by its handle, with the referral data, trust verdict and live queue position already resolved.

Source: https://getlaunchlist.com/help/docs/api/contacts-retrieve

---

Requires the `contacts:read` scope.

Fetch one contact. The `position` and `referral` data are resolved as part of the response, so
showing somebody their place in line takes one call.

## The contact object

This is the same object every contact endpoint returns. Every field below is always present.

| Field                 | Description                                                                                                                                                 |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                  | The `con_` handle.                                                                                                                                          |
| `livemode`            | `false` for a test-mode contact.                                                                                                                            |
| `project`             | The owning `prj_` handle.                                                                                                                                   |
| `identifier`          | The deduplicated identity. `null` when the contact is locked.                                                                                               |
| `identifier_type`     | `email`, `phone`, `username`, `wallet` or `custom`.                                                                                                         |
| `email`               | The address this contact is mailed at. Equals `identifier` for an email identity; otherwise the address collected beside it, or `null`. `null` when locked. |
| `external_id`         | Your own id, or `null`. Unique per project.                                                                                                                 |
| `attributes`          | Your custom key-value pairs, always an object. Empty when locked.                                                                                           |
| `status`              | `pending` (shown as Not subscribed in the dashboard), `subscribed`, `unsubscribed`, `bounced` or `blocked`. Everyone who joins is `subscribed`; `pending` is only an imported contact you were not sure about. It said `verified` instead of `subscribed` until the October 2026 rename.                                                                 |
| `stage`               | The pipeline stage key, from **your** funnel.                                                                                                               |
| `deliverability`      | `null` until the verdict is revealed with a credit. Then `deliverable`, `undeliverable`, `disposable`, `risky`, `role` or `unknown`.                        |
| `trust_tier`          | `verified`, `valid`, `unknown`, `risky` or `fake`.                                                                                                          |
| `position`            | Live queue position, or `null` when the contact is not on the board.                                                                                        |
| `referral`            | `{ code, url, count, referred_by, state }`, or `null` when the contact is locked.                                                                           |
| `unsubscribed`        | `true` when `status` is `unsubscribed`. A convenience mirror.                                                                                               |
| `locked`              | `true` when the [overflow lock](/help/docs/account/billing) is withholding this contact.                                                                    |
| `verified_at`         | When they proved they own the identity, or `null`. Proof only, not consent.                                                                                 |
| `opt_in_confirmed_at` | When they clicked the verification link, or `null`.                                                                                                         |
| `consent` | How they agreed to hear from you: `signup` (they joined), `confirmed` (they clicked the verification link), `imported` or `owner` (you attested they asked), or `v1`. `null` when they never agreed. Kept after an unsubscribe. |
| `consented_at` | When they agreed, or `null`. |
| `unsubscribed_by` | Who ended the subscription: `contact`, `owner` or `complaint`. `null` while subscribed. See [subscription](/help/docs/api/contacts-subscription). |
| `unsubscribed_at` | When it ended, or `null`. |
| `created_at`          | ISO 8601.                                                                                                                                                   |
| `url`                 | This contact's path on the API.                                                                                                                             |

> [!NOTE] `verified_at` is proof, `status` is consent
> They move independently. Everyone who joins is subscribed, so a contact who never clicked
> a verification link, or was never sent one, carries `status: "subscribed"` with `verified_at: null`.
> The mailing gate reads `status`, and a broadcast's Who in this audience choice can then narrow it by
> `verified_at`.

## Looking a contact up by your own id

If you stored an `external_id`, filter the list rather than storing our handles:

```bash
curl "https://api.getlaunchlist.com/v1/contacts?project=prj_7Qk2mN4pR8&external_id=user_9182" \\
  -H "Authorization: Bearer llk_live_8xKq3Rp9Wm2Nz7Vt6yL1cG5dH0jA4sE8uNqB2fXk"
```

The same works for `identifier`, canonicalized before matching.

> [!NOTE] A contact from another workspace returns 404, not 403
> Across a workspace boundary we never confirm that an id exists. See
> [errors](/help/docs/api/errors) for why.

## Next

- [Update a contact](/help/docs/api/contacts-update) · [Position](/help/docs/api/contacts-position)
- [List contacts](/help/docs/api/contacts-list)