Lists API

The Lists API lets you read people/lead lists for the authenticated account (owned lists and lists shared with the account or seat). Each list includes a product URL of the form https://theorg.com/people/lists/{slug} (for example https://theorg.com/people/lists/empty-list).

💡

Creating a list and adding people are available as free MCP tools (create_list, add_to_list). See the MCP API. Position IDs for those tools come from the Position API or MCP find_positions.

List people lists


GET https://api.theorg.com/v1.1/lists

Also available on v1.2:


GET https://api.theorg.com/v1.2/lists

Parameter	Value
Url	https://api.theorg.com/v1.1/lists
Method	`GET`
Auth	`X-Api-Key`
Cost	Free

Parameters

Parameter	Type	Description	Required
`limit`	integer	Max lists to return (1–100, default 30)	`false`
`offset`	integer	Pagination offset (default 0)	`false`

Returns owned lists and lists shared with the account or seat for the API key’s Vision seat.

Example

List people/lead lists


curl --location 'https://api.theorg.com/v1.1/lists?limit=30&offset=0' \
  --header 'X-Api-Key: **********************a02e'

Show response


{
  "lists": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Empty List",
      "slug": "empty-list",
      "url": "https://theorg.com/people/lists/empty-list",
      "positionCount": 0
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Fintech CTOs",
      "slug": "fintech-ctos",
      "url": "https://theorg.com/people/lists/fintech-ctos",
      "positionCount": 12
    }
  ],
  "total": 2
}

Response fields

Field	Type	Description
`lists`	array	Page of lists
`lists[].id`	UUID	List id
`lists[].name`	string	Display name
`lists[].slug`	string	URL slug (unique within the account)
`lists[].url`	string	Product link: `https://theorg.com/people/lists/{slug}`
`lists[].positionCount`	integer	Number of people on the list when available; may be omitted
`total`	integer	Total lists visible to this seat (for pagination)

MCP API – get_lists, create_list, add_to_list (create/add; max 25 position IDs per call)
Position API – search people and obtain position ids to add to lists