> For the complete documentation index, see [llms.txt](https://docs.sumble.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sumble.com/api/lists/contact-lists.md).

# 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](/web-app/lists-monitoring/contact-lists.md) 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.

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.

## GET /v9/contact-lists

> List contact lists

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"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":{"/v9/contact-lists":{"get":{"tags":["contact-lists"],"summary":"List contact lists","operationId":"list_contact_lists__api_version__contact_lists_get","parameters":[],"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.

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.

## GET /v9/contact-lists/{list\_id}

> Get contact list details

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"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","description":"Person rows. Empty when `file` is present because the file contains these rows."},"file":{"anyOf":[{"$ref":"#/components/schemas/ApiFileResponse"},{"type":"null"}],"description":"Metadata for the downloadable file created when `file_name` was supplied. Ask Sumble and Slack attach it automatically. In other MCP clients, present `download_url` to the user. Do not recreate the file."}},"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/ContactListContactInfo"},{"type":"null"}]}},"type":"object","required":["id","url","name"],"title":"ContactListPerson"},"ContactListContactInfo":{"properties":{"emails":{"items":{"type":"string"},"type":"array","title":"Emails"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"requested":{"$ref":"#/components/schemas/ContactInfoRequested"}},"type":"object","required":["emails"],"title":"ContactListContactInfo","description":"Paid-API contact info for a contact-list person.\n\nDeliberately decoupled from the shared `ProfileContactInfo` (as\n`/people/enrich` already is): the shared model carries web-only fields (e.g.\nthe async-reveal `pending` flag, SMB-2070) that must not drift into the\nCadwyn-versioned paid response. This mirrors the shared model's current paid\ncontract exactly — `emails`, `phone`, `requested`."},"ContactInfoRequested":{"properties":{"email":{"type":"boolean","title":"Email","default":false},"phone":{"type":"boolean","title":"Phone","default":false}},"type":"object","title":"ContactInfoRequested"},"ApiFileResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Opaque file identifier."},"filename":{"type":"string","title":"Filename","description":"Filename shown to the user."},"media_type":{"type":"string","title":"Media Type","description":"IANA media type."},"kind":{"type":"string","enum":["organization_list","contact_list"],"title":"Kind","description":"The kind of data contained in the file."},"row_count":{"type":"integer","title":"Row Count","description":"Number of data rows in the file."},"columns":{"items":{"type":"string"},"type":"array","title":"Columns","description":"Column names in file order."},"size_bytes":{"type":"integer","title":"Size Bytes","description":"File size in bytes."},"download_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Download Url","description":"Authenticated Sumble URL where the user can download the file."}},"type":"object","required":["id","filename","media_type","kind","row_count","columns","size_bytes","download_url"],"title":"ApiFileResponse","description":"Metadata for a file created by the API for the user."},"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":{"/v9/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":"file_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File Name"}}],"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 /v9/contact-lists

> Create a contact list

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"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":{"/v9/contact-lists":{"post":{"tags":["contact-lists"],"summary":"Create a contact list","operationId":"create_contact_list__api_version__contact_lists_post","parameters":[],"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.

One request can add up to 10,000 people. Larger batches are rejected with a validation error, so split them across requests.

You can obtain person IDs from the [People](/api/core-data/people.md) endpoint.

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

> Add people to a contact list

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"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":{"/v9/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"}}],"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"}}}}}}}}}
```