LaunchListBeta

Retrieve a contact

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

Updated ·3 min read
GET/v1/contacts/{contact}

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 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.
unsubscribed_at When it ended, or null.
created_at ISO 8601.
url This contact's path on the API.

Looking a contact up by your own id#

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

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.

Next#

Was this page helpful?
curl "https://api.getlaunchlist.com/v1/contacts/con_4mKp9Wq2Rx" \\
  -H "Authorization: Bearer llk_live_8xKq3Rp9Wm2Nz7Vt6yL1cG5dH0jA4sE8uNqB2fXk"
{
  "object": "contact",
  "id": "con_4mKp9Wq2Rx",
  "livemode": true,
  "project": "prj_7Qk2mN4pR8",
  "identifier": "ada@lovelace.dev",
  "identifier_type": "email",
  "email": "ada@lovelace.dev",
  "external_id": "user_9182",
  "attributes": { "role": "Founder", "cohort": "beta-2" },
  "status": "subscribed",
  "stage": "waitlist",
  "deliverability": null,
  "trust_tier": "verified",
  "position": 1284,
  "referral": {
    "code": "ADA7X2",
    "url": "https://acme.launchlist.page?ref=ADA7X2",
    "count": 3,
    "referred_by": "con_2Bn8Vd5Lk",
    "state": "credited"
  },
  "unsubscribed": false,
  "locked": false,
  "verified_at": "2026-07-28T14:02:55+00:00",
  "opt_in_confirmed_at": "2026-07-28T14:02:55+00:00",
  "consent": "signup",
  "consented_at": "2026-07-28T13:59:10+00:00",
  "unsubscribed_by": null,
  "unsubscribed_at": null,
  "created_at": "2026-07-28T13:59:10+00:00",
  "url": "/v1/contacts/con_4mKp9Wq2Rx"
}