Contact lists
Create, manage, and access contact lists (people lists) in your Sumble account via the API.
Contact lists let you save and organize people for outreach, tracking, or export. You can create lists, add people to them by their Sumble person IDs, and retrieve the full list with enriched contact details.
See Contact lists for how lists are created and managed in the web application.
Credit cost
List contact lists
1 credit per list returned
Get contact list details
1 credit per person returned
Create contact list
No credit cost
Add people to a list
No credit cost
List contact lists
Returns your saved contact lists with each list's ID, name, and people count.
Pass a .csv, .xlsx or .json file_name to receive file metadata and an authenticated Sumble download URL instead of list rows. The file contains one row per saved list. The response keeps its credit metadata and leaves contact_lists empty. Opening the download URL requires the file owner's Sumble web session.
Successful Response
Validation Error
GET /v9/contact-lists HTTP/1.1
Host: api.sumble.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "019d25ba-90e8-7a3c-a008-7f0bf41ac79a",
"credits_used": 1,
"credits_remaining": 9992,
"contact_lists": [
{
"id": 3839,
"name": "Sumblers",
"people_count": 17,
"url": "https://sumble.com/lists/3839"
}
]
}Get contact list details
Returns one contact list and the people currently in it, with enriched profile data including name, job title, job function, LinkedIn URL, organization, and contact information (emails and phone when available).
Use the list_id returned from the list endpoint.
Pass a .csv, .xlsx or .json file_name to receive file metadata and an authenticated Sumble download URL instead of person rows. The metadata includes the file kind, row count, columns, and byte size. Opening the download URL requires the file owner's Sumble web session.
Successful Response
Validation Error
GET /v9/contact-lists/{list_id} HTTP/1.1
Host: api.sumble.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "019d265b-526d-74cf-a4e0-2c41dc0f4866",
"credits_used": 2,
"credits_remaining": 99986,
"list_info": {
"id": 3839,
"name": "Target contacts",
"people_count": 2,
"url": "https://sumble.com/lists/3839"
},
"people": [
{
"id": 169860318,
"url": "https://sumble.com/l/person/cSAZUHj6Nmt8",
"name": "Jared Nightingale",
"job_title": "Business Operations Specialist",
"job_function_name": "Operations",
"job_function_slug": "operations",
"linkedin_url": "https://www.linkedin.com/in/jared-nightingale",
"organization_id": 1726684,
"organization_name": "Sumble",
"organization_slug": "sumble"
},
{
"id": 177409621,
"url": "https://sumble.com/l/person/mOGBSiARsL83",
"name": "Gervasio Marchand",
"job_title": "Founding Engineer",
"job_function_name": "Engineer",
"job_function_slug": "engineer",
"linkedin_url": "https://www.linkedin.com/in/g3rv4",
"organization_id": 1726684,
"organization_name": "Sumble",
"organization_slug": "sumble",
"contact_info": {
"emails": [
"gervasio@sumble.com"
]
}
}
]
}Create contact list
Create a new, empty contact list. Use the returned id to add people to it.
Successful Response
Validation Error
POST /v9/contact-lists HTTP/1.1
Host: api.sumble.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 26
{
"name": "Target contacts"
}{
"id": 3839,
"name": "Target contacts",
"url": "https://sumble.com/lists/3839"
}Add people to a list
Add people to an existing contact list by their Sumble person IDs. People already on the list are silently skipped. The response tells you how many were added and how many were already present.
One request can add up to 10,000 people. Larger batches are rejected with a validation error, so split them across requests.
On Free and Pro plans a list holds up to 10,000 people in total. A request that would take a list past that is rejected with a 403 and the error type contact_list_full, and nothing from it is added. Enterprise lists have no size limit.
You can obtain person IDs from the People endpoint.
Successful Response
Validation Error
POST /v9/contact-lists/{list_id}/people HTTP/1.1
Host: api.sumble.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 36
{
"people_ids": [
177409621,
254399875
]
}{
"added": 2,
"already_on_list": 0
}Last updated