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

Operation	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.

List contact lists

get

Authorizations

api_token

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Successful Response

application/json

idstring · uuidRequired

credits_usedintegerRequired

credits_remainingintegerRequired

422

Validation Error

application/json

get/v9/contact-lists

HTTPcURLJavaScriptPython

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.

Get contact list details

get

Authorizations

api_token

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

list_idintegerRequired

Responses

200

Successful Response

application/json

idstring · uuidRequired

credits_usedintegerRequired

credits_remainingintegerRequired

422

Validation Error

application/json

get/v9/contact-lists/{list_id}

HTTPcURLJavaScriptPython

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": [
          "[e-mail]"
        ]
      }
    }
  ]
}

---

Create contact list

Create a new, empty contact list. Use the returned id to add people to it.

Create a contact list

post

Authorizations

api_token

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

namestringRequired

Responses

200

Successful Response

application/json

idintegerRequired

namestringRequired

urlstring · uri · min: 1 · max: 2083Required

422

Validation Error

application/json

post/v9/contact-lists

HTTPcURLJavaScriptPython

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.

You can obtain person IDs from the People endpoint.

Add people to a contact list

post

Authorizations

api_token

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

list_idintegerRequired

Body

application/json

people_idsinteger[]Required

Responses

200

Successful Response

application/json

urlstring · uri · min: 1 · max: 2083Required

addedintegerRequired

already_on_listintegerRequired

422

Validation Error

application/json

post/v9/contact-lists/{list_id}/people

HTTPcURLJavaScriptPython

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
}