# 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](https://docs.sumble.com/web-application/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.

## GET /v5/contact-lists

> List contact lists

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v5"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"ContactListsResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"contact_lists":{"items":{"$ref":"#/components/schemas/ContactListSummary"},"type":"array","title":"Contact Lists"}},"type":"object","required":["id","credits_used","credits_remaining","contact_lists"],"title":"ContactListsResponse"},"ContactListSummary":{"properties":{"id":{"type":"integer","title":"Id"},"name":{"type":"string","title":"Name"},"people_count":{"type":"integer","title":"People Count"},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"}},"type":"object","required":["id","name","people_count","url"],"title":"ContactListSummary"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v5/contact-lists":{"get":{"tags":["contact-lists"],"summary":"List contact lists","operationId":"list_contact_lists__api_version__contact_lists_get","parameters":[{"name":"require_mcp","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Require Mcp"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

***

## 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 /v5/contact-lists/{list\_id}

> Get contact list details

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v5"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"ContactListResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"list_info":{"$ref":"#/components/schemas/ContactListSummary"},"people":{"items":{"$ref":"#/components/schemas/ContactListPerson"},"type":"array","title":"People"}},"type":"object","required":["id","credits_used","credits_remaining","list_info","people"],"title":"ContactListResponse"},"ContactListSummary":{"properties":{"id":{"type":"integer","title":"Id"},"name":{"type":"string","title":"Name"},"people_count":{"type":"integer","title":"People Count"},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"}},"type":"object","required":["id","name","people_count","url"],"title":"ContactListSummary"},"ContactListPerson":{"properties":{"id":{"anyOf":[{"type":"integer"},{"type":"string"}],"title":"Id"},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"},"name":{"type":"string","title":"Name"},"job_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Title"},"job_function_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Function Name"},"job_function_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Function Slug"},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url"},"organization_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Organization Id"},"organization_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Organization Name"},"organization_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Organization Slug"},"contact_info":{"anyOf":[{"$ref":"#/components/schemas/ProfileContactInfo"},{"type":"null"}]}},"type":"object","required":["id","url","name"],"title":"ContactListPerson"},"ProfileContactInfo":{"properties":{"emails":{"items":{"type":"string"},"type":"array","title":"Emails"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"}},"type":"object","required":["emails"],"title":"ProfileContactInfo"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v5/contact-lists/{list_id}":{"get":{"tags":["contact-lists"],"summary":"Get contact list details","operationId":"get_contact_list__api_version__contact_lists__list_id__get","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"integer","title":"List Id"}},{"name":"require_mcp","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Require Mcp"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

***

## Create contact list

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

## POST /v5/contact-lists

> Create a contact list

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v5"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"CreateContactListRequest":{"properties":{"name":{"type":"string","title":"Name"}},"type":"object","required":["name"],"title":"CreateContactListRequest"},"CreateContactListResponse":{"properties":{"id":{"type":"integer","title":"Id"},"name":{"type":"string","title":"Name"},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"}},"type":"object","required":["id","name","url"],"title":"CreateContactListResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v5/contact-lists":{"post":{"tags":["contact-lists"],"summary":"Create a contact list","operationId":"create_contact_list__api_version__contact_lists_post","parameters":[{"name":"require_mcp","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Require Mcp"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateContactListRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateContactListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

***

## 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 find](https://docs.sumble.com/api/people) or [People find-related-people](https://docs.sumble.com/people#find-related-people) endpoints.

## POST /v5/contact-lists/{list\_id}/people

> Add people to a contact list

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v5"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"AddContactsRequest":{"properties":{"people_ids":{"items":{"type":"integer"},"type":"array","title":"People Ids"}},"type":"object","required":["people_ids"],"title":"AddContactsRequest"},"AddContactsResponse":{"properties":{"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"},"added":{"type":"integer","title":"Added"},"already_on_list":{"type":"integer","title":"Already On List"}},"type":"object","required":["url","added","already_on_list"],"title":"AddContactsResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v5/contact-lists/{list_id}/people":{"post":{"tags":["contact-lists"],"summary":"Add people to a contact list","operationId":"add_contacts_to_list__api_version__contact_lists__list_id__people_post","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"integer","title":"List Id"}},{"name":"require_mcp","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Require Mcp"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddContactsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddContactsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```