Reference

Leads

Create, merge, list and read leads and their channel identities.

A lead is one person in one workspace, with one or more channel identities. Creating a lead matches on every identity you send, so the same person is never stored twice. See Leads and lists for the merge rules.

List leads

GET/api/v1/leadsScope leads:read

Leads newest first. Filter by list with listId, or search with q, which matches the name, company or email.

Parameters

NameInTypeDescription
cursorquerystringOpaque cursor from the previous page's nextCursor.
limitqueryintegerPage size. 1 to 100. Default 50.
listIdquerystring (uuid)Only leads in this list.
qquerystringMatches name, company or email.

Example request

curl -s "https://app.graphkit.com/api/v1/leads" \
  -H "Authorization: Bearer $GRAPHKIT_API_KEY"

Response 200

FieldTypeDescription
dataarray of objectThe page of results, newest first.
data[].idstring (uuid)UUID.
data[].firstNamestring or null
data[].lastNamestring or null
data[].fullNamestring or null
data[].headlinestring or null
data[].jobTitlestring or null
data[].companyNamestring or null
data[].locationstring or null
data[].emailstring or null
data[].phonestring or null
data[].profileUrlstring or nullProfile URL on the channel.
data[].avatarUrlstring or null
data[].customFieldsobjectCustom fields, keyed by lowercase snake_case names.
data[].sourcestringWhere it came from, for example csv, api, inbox or network.
data[].isDemobooleanTrue for demo data in a demo workspace.
data[].identitiesarray of objectChannel identities of the lead.
data[].identities[].channelstringThe channel. One of linkedin, instagram, whatsapp, telegram, facebook.
data[].identities[].handlestring or nullPublic handle on the channel (LinkedIn slug, @username or phone).
data[].identities[].profileUrlstring or nullProfile URL on the channel.
data[].identities[].isPrimarybooleanThe identity shown first and used by default.
data[].identities[].verifiedbooleanConfirmed to exist by the network or by a person.
data[].listIdsarray of string (uuid)Lists the lead belongs to.
data[].createdAtstring (date-time)When it was created (RFC 3339, UTC).
data[].updatedAtstring (date-time)When it last changed.
nextCursorstring or nullPass back as cursor for the next page; null on the last page.
{
  "data": [
    {
      "id": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99",
      "firstName": "Jane",
      "lastName": "Doe",
      "fullName": "Jane Doe",
      "headline": "Head of Growth at Northwind",
      "jobTitle": "Head of Growth",
      "companyName": "Northwind",
      "location": "London, United Kingdom",
      "email": "jane@northwind.example",
      "phone": null,
      "profileUrl": "https://www.linkedin.com/in/jane-doe",
      "avatarUrl": null,
      "customFields": {},
      "source": "csv",
      "isDemo": false,
      "identities": [
        {
          "channel": "linkedin",
          "handle": "jane-doe",
          "profileUrl": "https://www.linkedin.com/in/jane-doe",
          "isPrimary": true,
          "verified": true
        }
      ],
      "listIds": [
        "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99"
      ],
      "createdAt": "2026-11-15T10:04:05Z",
      "updatedAt": "2026-11-15T10:04:05Z"
    }
  ],
  "nextCursor": null
}

Errors

StatusCode and meaning
401invalid_api_key: the key is missing, unknown or revoked.
403insufficient_scope: the key lacks the scope this endpoint needs.
429rate_limited: more than 300 requests in a minute; wait for Retry-After.

Create or merge a lead

POST/api/v1/leadsScope leads:write

Creates a lead, or merges into the lead that already owns one of the identities. An identity value can be a profile URL, a public id, an @username or a +E.164 phone number, depending on the channel. A profileUrl with no identities is read as a LinkedIn identity.

Merging only fills empty fields, and never changes a field a teammate edited by hand. The response is 201 when the lead was created and 200 when it was merged, with outcome set to created, updated or duplicate. conflicts lists identities that already belong to a different lead; they stay with that lead, and leads are never merged automatically.

A lead created here emits the lead.created webhook.

Parameters

NameInTypeDescription
Idempotency-KeyheaderstringReplays the stored response for 24 hours (header Idempotent-Replayed: true). Reusing a key with a different request is 422; while the first request runs, 409. Up to 255 characters.

Request body

At least one identity (or profileUrl, read as a LinkedIn identity).

FieldTypeRequiredDescription
firstNamestringNo
lastNamestringNo
fullNamestringNo
headlinestringNo
jobTitlestringNo
companyNamestringNo
locationstringNo
emailstringNo
phonestringNo
profileUrlstringNoProfile URL on the channel.
identitiesarray of objectNoChannel identities of the lead. Up to 8 items.
identities[].channelstringYesThe channel. One of linkedin, instagram, whatsapp, telegram, facebook.
identities[].valuestringYesProfile URL, public id, @username or +E.164 phone.
customFieldsobjectNoCustom fields, keyed by lowercase snake_case names.
listIdsarray of string (uuid)NoLists the lead belongs to. Up to 20 items.

Example request

curl -s -X POST "https://app.graphkit.com/api/v1/leads" \
  -H "Authorization: Bearer $GRAPHKIT_API_KEY" \
  -H "Idempotency-Key: crm-contact-4711" \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Jane","lastName":"Doe","companyName":"Northwind","jobTitle":"Head of Growth","identities":[{"channel":"linkedin","value":"https://www.linkedin.com/in/jane-doe"}],"customFields":{"crm_id":"4711"},"listIds":["0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99"]}'

Response 200

FieldTypeDescription
outcomestringOne of created, updated, duplicate.
leadobject
lead.idstring (uuid)UUID.
lead.firstNamestring or null
lead.lastNamestring or null
lead.fullNamestring or null
lead.headlinestring or null
lead.jobTitlestring or null
lead.companyNamestring or null
lead.locationstring or null
lead.emailstring or null
lead.phonestring or null
lead.profileUrlstring or nullProfile URL on the channel.
lead.avatarUrlstring or null
lead.customFieldsobjectCustom fields, keyed by lowercase snake_case names.
lead.sourcestringWhere it came from, for example csv, api, inbox or network.
lead.isDemobooleanTrue for demo data in a demo workspace.
lead.identitiesarray of objectChannel identities of the lead.
lead.identities[].channelstringThe channel. One of linkedin, instagram, whatsapp, telegram, facebook.
lead.identities[].handlestring or nullPublic handle on the channel (LinkedIn slug, @username or phone).
lead.identities[].profileUrlstring or nullProfile URL on the channel.
lead.identities[].isPrimarybooleanThe identity shown first and used by default.
lead.identities[].verifiedbooleanConfirmed to exist by the network or by a person.
lead.listIdsarray of string (uuid)Lists the lead belongs to.
lead.createdAtstring (date-time)When it was created (RFC 3339, UTC).
lead.updatedAtstring (date-time)When it last changed.
conflictsarray of stringIdentities already owned by another lead (left there).
{
  "outcome": "created",
  "lead": {
    "id": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99",
    "firstName": "Jane",
    "lastName": "Doe",
    "fullName": "Jane Doe",
    "headline": "Head of Growth at Northwind",
    "jobTitle": "Head of Growth",
    "companyName": "Northwind",
    "location": "London, United Kingdom",
    "email": "jane@northwind.example",
    "phone": null,
    "profileUrl": "https://www.linkedin.com/in/jane-doe",
    "avatarUrl": null,
    "customFields": {},
    "source": "csv",
    "isDemo": false,
    "identities": [
      {
        "channel": "linkedin",
        "handle": "jane-doe",
        "profileUrl": "https://www.linkedin.com/in/jane-doe",
        "isPrimary": true,
        "verified": true
      }
    ],
    "listIds": [
      "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99"
    ],
    "createdAt": "2026-11-15T10:04:05Z",
    "updatedAt": "2026-11-15T10:04:05Z"
  },
  "conflicts": []
}

Response 201

Created. Same body as the 200 response.

Errors

StatusCode and meaning
401invalid_api_key: the key is missing, unknown or revoked.
403insufficient_scope: the key lacks the scope this endpoint needs.
400invalid_identities: No identity, more than 8, an unknown channel, or a value that cannot be read for its channel.
400invalid_custom_fields: A custom field key or value is not valid.
400invalid_list_ids: More than 20 list ids.
400unknown_list: A list id does not exist in this workspace.
429rate_limited: more than 300 requests in a minute; wait for Retry-After.

Get a lead

GET/api/v1/leads/{id}Scope leads:read

One lead with its identities and list ids.

Parameters

NameInTypeDescription
idpathstring (uuid)The resource id.

Example request

curl -s "https://app.graphkit.com/api/v1/leads/0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99" \
  -H "Authorization: Bearer $GRAPHKIT_API_KEY"

Response 200

FieldTypeDescription
idstring (uuid)UUID.
firstNamestring or null
lastNamestring or null
fullNamestring or null
headlinestring or null
jobTitlestring or null
companyNamestring or null
locationstring or null
emailstring or null
phonestring or null
profileUrlstring or nullProfile URL on the channel.
avatarUrlstring or null
customFieldsobjectCustom fields, keyed by lowercase snake_case names.
sourcestringWhere it came from, for example csv, api, inbox or network.
isDemobooleanTrue for demo data in a demo workspace.
identitiesarray of objectChannel identities of the lead.
identities[].channelstringThe channel. One of linkedin, instagram, whatsapp, telegram, facebook.
identities[].handlestring or nullPublic handle on the channel (LinkedIn slug, @username or phone).
identities[].profileUrlstring or nullProfile URL on the channel.
identities[].isPrimarybooleanThe identity shown first and used by default.
identities[].verifiedbooleanConfirmed to exist by the network or by a person.
listIdsarray of string (uuid)Lists the lead belongs to.
createdAtstring (date-time)When it was created (RFC 3339, UTC).
updatedAtstring (date-time)When it last changed.
{
  "id": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99",
  "firstName": "Jane",
  "lastName": "Doe",
  "fullName": "Jane Doe",
  "headline": "Head of Growth at Northwind",
  "jobTitle": "Head of Growth",
  "companyName": "Northwind",
  "location": "London, United Kingdom",
  "email": "jane@northwind.example",
  "phone": null,
  "profileUrl": "https://www.linkedin.com/in/jane-doe",
  "avatarUrl": null,
  "customFields": {},
  "source": "csv",
  "isDemo": false,
  "identities": [
    {
      "channel": "linkedin",
      "handle": "jane-doe",
      "profileUrl": "https://www.linkedin.com/in/jane-doe",
      "isPrimary": true,
      "verified": true
    }
  ],
  "listIds": [
    "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99"
  ],
  "createdAt": "2026-11-15T10:04:05Z",
  "updatedAt": "2026-11-15T10:04:05Z"
}

Errors

StatusCode and meaning
401invalid_api_key: the key is missing, unknown or revoked.
403insufficient_scope: the key lacks the scope this endpoint needs.
404not_found: no such resource in this key's workspace.
429rate_limited: more than 300 requests in a minute; wait for Retry-After.

On this page