> 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/organization-lists.md). # 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](/web-app/lists-monitoring/account-lists.md) 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 | | Set a list's Signals inclusion setting | No credit cost | | Set a list deleted or restored | No credit cost | ## List organization lists Returns your saved organization lists with each list's ID, web app URL, organization count, type, read-only/deletable flags, deleted status, and Signals inclusion setting. ## GET /v6/organization-lists > List organization lists ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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"},"read_only":{"type":"boolean","title":"Read Only"},"deletable":{"type":"boolean","title":"Deletable"},"deleted":{"type":"boolean","title":"Deleted","default":false},"include_in_signals":{"type":"boolean","title":"Include In Signals","default":true}},"type":"object","required":["id","name","url","organizations_count","type","read_only","deletable"],"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":{"/v6/organization-lists":{"get":{"tags":["organization-lists"],"summary":"List organization lists","operationId":"list_organization_lists__api_version__organization_lists_get","parameters":[{"name":"include_deleted","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Deleted"}}],"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. Each organization includes its Sumble profile URL as `sumble_url`; `url` is the organization's own website. Use the `list_id` returned from the list endpoint. ## GET /v6/organization-lists/{list\_id} > Get organization list details ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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"},"read_only":{"type":"boolean","title":"Read Only"},"deletable":{"type":"boolean","title":"Deletable"},"deleted":{"type":"boolean","title":"Deleted","default":false},"include_in_signals":{"type":"boolean","title":"Include In Signals","default":true}},"type":"object","required":["id","name","url","organizations_count","type","read_only","deletable"],"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"},"sumble_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Sumble Url"},"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":{"/v6/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":"include_deleted","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Deleted"}}],"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 /v6/organization-lists > Create an organization list ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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":{"/v6/organization-lists":{"post":{"tags":["organization-lists"],"summary":"Create an organization list","operationId":"create_organization_list__api_version__organization_lists_post","parameters":[],"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 [organizations endpoint](/api/core-data/organizations.md#find-match-and-enrich-organizations) first to resolve them. ## POST /v6/organization-lists/{list\_id}/organizations > Add organizations to a list ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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":{"/v6/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"}}],"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"}}}}}}}}} ``` *** ## Set a list's Signals inclusion setting Include or exclude an organization list's accounts from future Signals delivery. Lists are included by default. This mirrors the per-list Signals toggle in the web app. ## Set a list's signals inclusion setting > Include or exclude an organization list's accounts from your signals feed.\ > \ > Pass \`\`include\_in\_signals=false\`\` to exclude this list's accounts from your\ > signals, or \`\`true\`\` to include them again. Lists are included by default.\ > This mirrors the per-list signals toggle in the dashboard. ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"SetOrganizationListSignalsRequest":{"properties":{"include_in_signals":{"type":"boolean","title":"Include In Signals"}},"type":"object","required":["include_in_signals"],"title":"SetOrganizationListSignalsRequest"},"OrganizationListSignalsResponse":{"properties":{"id":{"type":"integer","title":"Id"},"include_in_signals":{"type":"boolean","title":"Include In Signals"}},"type":"object","required":["id","include_in_signals"],"title":"OrganizationListSignalsResponse"},"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":{"/v6/organization-lists/{list_id}/signals":{"post":{"tags":["organization-lists"],"summary":"Set a list's signals inclusion setting","description":"Include or exclude an organization list's accounts from your signals feed.\n\nPass ``include_in_signals=false`` to exclude this list's accounts from your\nsignals, or ``true`` to include them again. Lists are included by default.\nThis mirrors the per-list signals toggle in the dashboard.","operationId":"set_organization_list_signals__api_version__organization_lists__list_id__signals_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/SetOrganizationListSignalsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationListSignalsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` *** ## Set a list deleted or restored Soft-delete an organization list or restore a previously deleted one. Pass `{ "deleted": true }` to delete the list, or `{ "deleted": false }` to restore it. Deleting a list preserves its organizations; deleting individual organizations from a list is a separate operation. Deleted lists are hidden by default. To retrieve them with their preserved organization counts and details, pass `include_deleted=true` on the list and detail endpoints above. ## Set an organization list's deleted status > Soft-delete or restore an organization list.\ > \ > Soft-deletion is reversible: pass \`\`deleted=false\`\` to restore a list.\ > Deleting or restoring a list does not delete or restore individual\ > organizations in the list. Pass \`\`include\_deleted=true\`\` to the list/detail\ > endpoints to see deleted lists. ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"SetOrganizationListDeletedRequest":{"properties":{"deleted":{"type":"boolean","title":"Deleted"}},"type":"object","required":["deleted"],"title":"SetOrganizationListDeletedRequest"},"SetOrganizationListDeletedResponse":{"properties":{"id":{"type":"integer","title":"Id"},"deleted":{"type":"boolean","title":"Deleted"}},"type":"object","required":["id","deleted"],"title":"SetOrganizationListDeletedResponse"},"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":{"/v6/organization-lists/{list_id}/deleted":{"post":{"tags":["organization-lists"],"summary":"Set an organization list's deleted status","description":"Soft-delete or restore an organization list.\n\nSoft-deletion is reversible: pass ``deleted=false`` to restore a list.\nDeleting or restoring a list does not delete or restore individual\norganizations in the list. Pass ``include_deleted=true`` to the list/detail\nendpoints to see deleted lists.","operationId":"set_organization_list_deleted__api_version__organization_lists__list_id__deleted_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/SetOrganizationListDeletedRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetOrganizationListDeletedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.sumble.com/api/lists/organization-lists.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.