Reference

Lists

Create lead lists and add leads to them.

Lists group leads for campaigns. A lead can be in any number of lists, and deleting a list never deletes its leads.

List lists

GET/api/v1/listsScope leads:read

Lead lists newest first, with their lead counts.

Parameters

NameInTypeDescription
cursorquerystringOpaque cursor from the previous page's nextCursor.
limitqueryintegerPage size. 1 to 100. Default 50.

Example request

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

Response 200

FieldTypeDescription
dataarray of objectThe page of results, newest first.
data[].idstring (uuid)UUID.
data[].namestring
data[].descriptionstring or null
data[].sourcestringWhere it came from, for example csv, api, inbox or network.
data[].leadCountinteger
data[].isDemobooleanTrue for demo data in a demo workspace.
data[].createdAtstring (date-time)When it was created (RFC 3339, UTC).
nextCursorstring or nullPass back as cursor for the next page; null on the last page.
{
  "data": [
    {
      "id": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99",
      "name": "Q1 founders, UK",
      "description": null,
      "source": "csv",
      "leadCount": 0,
      "isDemo": false,
      "createdAt": "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 a list

POST/api/v1/listsScope leads:write

Creates an empty list.

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

FieldTypeRequiredDescription
namestringYesUp to 120 characters.
descriptionstringNoUp to 500 characters.

Example request

curl -s -X POST "https://app.graphkit.com/api/v1/lists" \
  -H "Authorization: Bearer $GRAPHKIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"Q1 founders, UK","description":"Seed-stage founders from the January webinar"}'

Response 201

FieldTypeDescription
idstring (uuid)UUID.
namestring
descriptionstring or null
sourcestringWhere it came from, for example csv, api, inbox or network.
leadCountinteger
isDemobooleanTrue for demo data in a demo workspace.
createdAtstring (date-time)When it was created (RFC 3339, UTC).
{
  "id": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99",
  "name": "Q1 founders, UK",
  "description": null,
  "source": "csv",
  "leadCount": 0,
  "isDemo": false,
  "createdAt": "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.
429rate_limited: more than 300 requests in a minute; wait for Retry-After.

Add leads to a list

POST/api/v1/lists/{id}/leadsScope leads:write

Adds 1 to 1000 leads. Leads already in the list are counted in alreadyPresent, and ids that are not leads of this workspace are returned in unknownLeadIds.

Parameters

NameInTypeDescription
idpathstring (uuid)The resource id.
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

leadIds (1–1000); campaigns also accept listId instead.

FieldTypeRequiredDescription
leadIdsarray of string (uuid)NoLead ids. Up to 1000 items.
listIdstring (uuid)NoOnly leads in this list.

Example request

curl -s -X POST "https://app.graphkit.com/api/v1/lists/0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99/leads" \
  -H "Authorization: Bearer $GRAPHKIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"leadIds":["0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99","0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6fa0"]}'

Response 200

FieldTypeDescription
addedinteger
alreadyPresentinteger
unknownLeadIdsarray of string (uuid)
{
  "added": 12,
  "alreadyPresent": 12,
  "unknownLeadIds": []
}

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.
400invalid_lead_ids: Missing, empty, more than 1000, or not UUIDs.
429rate_limited: more than 300 requests in a minute; wait for Retry-After.

On this page