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.
GET /api/v1/listsScope leads:read
Lead lists newest first, with their lead counts.
Name In Type Description cursorquery string Opaque cursor from the previous page's nextCursor. limitquery integer Page size. 1 to 100. Default 50.
curl -s "https://app.graphkit.com/api/v1/lists" \
-H "Authorization: Bearer $GRAPHKIT_API_KEY "
Field Type Description dataarray of object The page of results, newest first. data[].idstring (uuid) UUID. data[].namestring data[].descriptionstring or null data[].sourcestring Where it came from, for example csv, api, inbox or network. data[].leadCountinteger data[].isDemoboolean True for demo data in a demo workspace. data[].createdAtstring (date-time) When it was created (RFC 3339, UTC). nextCursorstring or null Pass 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
}
Status Code and meaning 401 invalid_api_key: the key is missing, unknown or revoked.403 insufficient_scope: the key lacks the scope this endpoint needs.429 rate_limited: more than 300 requests in a minute; wait for Retry-After.
POST /api/v1/listsScope leads:write
Creates an empty list.
Name In Type Description Idempotency-Keyheader string Replays 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.
Field Type Required Description namestring Yes Up to 120 characters. descriptionstring No Up to 500 characters.
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"}'
Field Type Description idstring (uuid) UUID. namestring descriptionstring or null sourcestring Where it came from, for example csv, api, inbox or network. leadCountinteger isDemoboolean True 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"
}
Status Code and meaning 401 invalid_api_key: the key is missing, unknown or revoked.403 insufficient_scope: the key lacks the scope this endpoint needs.429 rate_limited: more than 300 requests in a minute; wait for Retry-After.
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.
Name In Type Description idpath string (uuid) The resource id. Idempotency-Keyheader string Replays 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.
leadIds (1–1000); campaigns also accept listId instead.
Field Type Required Description leadIdsarray of string (uuid) No Lead ids. Up to 1000 items. listIdstring (uuid) No Only leads in this list.
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"]}'
Field Type Description addedinteger alreadyPresentinteger unknownLeadIdsarray of string (uuid)
{
"added" : 12 ,
"alreadyPresent" : 12 ,
"unknownLeadIds" : []
}
Status Code and meaning 401 invalid_api_key: the key is missing, unknown or revoked.403 insufficient_scope: the key lacks the scope this endpoint needs.404 not_found: no such resource in this key's workspace.400 invalid_lead_ids: Missing, empty, more than 1000, or not UUIDs.429 rate_limited: more than 300 requests in a minute; wait for Retry-After.