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.
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.
Name In Type Description cursorquery string Opaque cursor from the previous page's nextCursor. limitquery integer Page size. 1 to 100. Default 50. listIdquery string (uuid) Only leads in this list. qquery string Matches name, company or email.
curl -s "https://app.graphkit.com/api/v1/leads" \
-H "Authorization: Bearer $GRAPHKIT_API_KEY "
Field Type Description dataarray of object The 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 null Profile URL on the channel. data[].avatarUrlstring or null data[].customFieldsobject Custom fields, keyed by lowercase snake_case names. data[].sourcestring Where it came from, for example csv, api, inbox or network. data[].isDemoboolean True for demo data in a demo workspace. data[].identitiesarray of object Channel identities of the lead. data[].identities[].channelstring The channel. One of linkedin, instagram, whatsapp, telegram, facebook. data[].identities[].handlestring or null Public handle on the channel (LinkedIn slug, @username or phone). data[].identities[].profileUrlstring or null Profile URL on the channel. data[].identities[].isPrimaryboolean The identity shown first and used by default. data[].identities[].verifiedboolean Confirmed 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 null Pass 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
}
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/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.
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.
At least one identity (or profileUrl, read as a LinkedIn identity).
Field Type Required Description firstNamestring No lastNamestring No fullNamestring No headlinestring No jobTitlestring No companyNamestring No locationstring No emailstring No phonestring No profileUrlstring No Profile URL on the channel. identitiesarray of object No Channel identities of the lead. Up to 8 items. identities[].channelstring Yes The channel. One of linkedin, instagram, whatsapp, telegram, facebook. identities[].valuestring Yes Profile URL, public id, @username or +E.164 phone. customFieldsobject No Custom fields, keyed by lowercase snake_case names. listIdsarray of string (uuid) No Lists the lead belongs to. Up to 20 items.
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"]}'
Field Type Description outcomestring One 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 null Profile URL on the channel. lead.avatarUrlstring or null lead.customFieldsobject Custom fields, keyed by lowercase snake_case names. lead.sourcestring Where it came from, for example csv, api, inbox or network. lead.isDemoboolean True for demo data in a demo workspace. lead.identitiesarray of object Channel identities of the lead. lead.identities[].channelstring The channel. One of linkedin, instagram, whatsapp, telegram, facebook. lead.identities[].handlestring or null Public handle on the channel (LinkedIn slug, @username or phone). lead.identities[].profileUrlstring or null Profile URL on the channel. lead.identities[].isPrimaryboolean The identity shown first and used by default. lead.identities[].verifiedboolean Confirmed 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 string Identities 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" : []
}
Created. Same body as the 200 response.
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.400 invalid_identities: No identity, more than 8, an unknown channel, or a value that cannot be read for its channel.400 invalid_custom_fields: A custom field key or value is not valid.400 invalid_list_ids: More than 20 list ids.400 unknown_list: A list id does not exist in this workspace.429 rate_limited: more than 300 requests in a minute; wait for Retry-After.
GET /api/v1/leads/{id}Scope leads:read
One lead with its identities and list ids.
Name In Type Description idpath string (uuid) The resource id.
curl -s "https://app.graphkit.com/api/v1/leads/0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99" \
-H "Authorization: Bearer $GRAPHKIT_API_KEY "
Field Type Description 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 null Profile URL on the channel. avatarUrlstring or null customFieldsobject Custom fields, keyed by lowercase snake_case names. sourcestring Where it came from, for example csv, api, inbox or network. isDemoboolean True for demo data in a demo workspace. identitiesarray of object Channel identities of the lead. identities[].channelstring The channel. One of linkedin, instagram, whatsapp, telegram, facebook. identities[].handlestring or null Public handle on the channel (LinkedIn slug, @username or phone). identities[].profileUrlstring or null Profile URL on the channel. identities[].isPrimaryboolean The identity shown first and used by default. identities[].verifiedboolean Confirmed 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"
}
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.429 rate_limited: more than 300 requests in a minute; wait for Retry-After.