# Organization lists

Create, manage, and access organization lists in your Sumble account via the API.

Organization lists let you group target accounts for tracking, enrichment, or export. You can create lists, add organizations to them, and retrieve their contents programmatically.

See [Account lists](https://docs.sumble.com/web-application/account-lists) for how lists are created and managed in the web application.

## Credit cost

| Operation                     | Cost                               |
| ----------------------------- | ---------------------------------- |
| List organization lists       | 1 credit per list returned         |
| Get organization list details | 1 credit per organization returned |
| Create organization list      | No credit cost                     |
| Add organizations to a list   | No credit cost                     |

## List organization lists

Returns your saved organization lists with each list's ID, name, and organization count.

## GET /v5/organization-lists

> List organization 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":{"OrganizationListsResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"organization_lists":{"items":{"$ref":"#/components/schemas/OrganizationListSummary"},"type":"array","title":"Organization Lists"}},"type":"object","required":["id","credits_used","credits_remaining","organization_lists"],"title":"OrganizationListsResponse"},"OrganizationListSummary":{"properties":{"id":{"type":"integer","title":"Id"},"name":{"type":"string","title":"Name"},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"},"organizations_count":{"type":"integer","title":"Organizations Count"},"type":{"$ref":"#/components/schemas/OrganizationListType"}},"type":"object","required":["id","name","url","organizations_count","type"],"title":"OrganizationListSummary"},"OrganizationListType":{"type":"string","enum":["group","user"],"title":"OrganizationListType"},"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/organization-lists":{"get":{"tags":["organization-lists"],"summary":"List organization lists","operationId":"list_organization_lists__api_version__organization_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/OrganizationListsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

***

## Get organization list details

Returns one organization list and the organizations currently in it.

Use the `list_id` returned from the list endpoint.

## GET /v5/organization-lists/{list\_id}

> Get organization 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":{"OrganizationListResponse":{"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/OrganizationListSummary"},"organizations":{"items":{"$ref":"#/components/schemas/OrganizationListOrganization"},"type":"array","title":"Organizations"}},"type":"object","required":["id","credits_used","credits_remaining","list_info","organizations"],"title":"OrganizationListResponse"},"OrganizationListSummary":{"properties":{"id":{"type":"integer","title":"Id"},"name":{"type":"string","title":"Name"},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"},"organizations_count":{"type":"integer","title":"Organizations Count"},"type":{"$ref":"#/components/schemas/OrganizationListType"}},"type":"object","required":["id","name","url","organizations_count","type"],"title":"OrganizationListSummary"},"OrganizationListType":{"type":"string","enum":["group","user"],"title":"OrganizationListType"},"OrganizationListOrganization":{"properties":{"id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"employee_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Employee Count"}},"type":"object","title":"OrganizationListOrganization"},"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/organization-lists/{list_id}":{"get":{"tags":["organization-lists"],"summary":"Get organization list details","operationId":"get_organization_list__api_version__organization_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/OrganizationListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

***

## Create organization list

Create a new, empty organization list. Use the returned `id` to add organizations to it.

## POST /v5/organization-lists

> Create an organization 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":{"CreateOrganizationListRequest":{"properties":{"name":{"type":"string","title":"Name"}},"type":"object","required":["name"],"title":"CreateOrganizationListRequest"},"CreateOrganizationListResponse":{"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":"CreateOrganizationListResponse"},"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/organization-lists":{"post":{"tags":["organization-lists"],"summary":"Create an organization list","operationId":"create_organization_list__api_version__organization_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/CreateOrganizationListRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrganizationListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

***

## Add organizations to a list

Add organizations to an existing list by their Sumble IDs or slugs. Organizations that are already in the list are silently skipped. Invalid IDs or slugs are returned in the failure arrays.

If you have company names or domains but not Sumble IDs or slugs, use the [match endpoint](https://docs.sumble.com/organizations#match-organizations) first to resolve them.

## POST /v5/organization-lists/{list\_id}/organizations

> Add organizations to a 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":{"AddOrganizationsRequest":{"properties":{"organization_ids":{"items":{"type":"integer"},"type":"array","title":"Organization Ids","default":[]},"organization_slugs":{"items":{"type":"string"},"type":"array","title":"Organization Slugs","default":[]}},"type":"object","title":"AddOrganizationsRequest"},"AddOrganizationsResponse":{"properties":{"added":{"items":{"type":"integer"},"type":"array","title":"Added"},"failed_ids":{"items":{"type":"integer"},"type":"array","title":"Failed Ids"},"failed_slugs":{"items":{"type":"string"},"type":"array","title":"Failed Slugs"}},"type":"object","required":["added","failed_ids","failed_slugs"],"title":"AddOrganizationsResponse"},"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/organization-lists/{list_id}/organizations":{"post":{"tags":["organization-lists"],"summary":"Add organizations to a list","operationId":"add_organizations_to_list__api_version__organization_lists__list_id__organizations_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/AddOrganizationsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddOrganizationsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```