---
title: "List your lists"
method: GET
path: "/lists/list"
tags: ["Lists"]
---

# List your lists

`GET /lists/list`

## Request

- Base URL: `https://api.emelia.io`
- URL: `https://api.emelia.io/lists/list`
- Auth: API key in header `Authorization`

Returns the contact lists of the account (top-level lists only: lists attached to a parent list are not returned).

Pagination is opt-in. Send `page` and/or `limit` to get the paginated envelope `{ items, total, page, pageSize, totalLeads }`. Without both parameters the endpoint returns a bare JSON array with ALL your lists, unpaginated, newest first, and every filter parameter is ignored. Integrations should always send `page` and `limit`.

To find which lists contain a person, pass `leadSearch` with a full email address (case-insensitive match) or a LinkedIn profile URL (matched on the profile handle, so trailing slashes and `www` do not matter). Any other value returns zero lists.

Each item is the stored list document. Besides the documented fields it can contain internal fields (column preferences, AI action settings, CRM integration settings, linked lists): do not rely on them.

## Query parameters

- `page` integer
- `limit` integer
- `search` string
- `leadSearch` string
- `source` string
- `status` 'mapped' | 'pending mapping'
- `tags` string
- `sortBy` 'name' | 'leads' | 'emails' | 'phones' | 'createdAt'
- `sortDir` 'asc' | 'desc'

## Response `200`

Paginated envelope when `page` or `limit` is sent, otherwise a bare array of all lists.

- union
  - ListsListsPage
    - `items` ListsList[], required
      - `_id` string, required: List id.
      - `userId` string
      - `name` string, required
      - `source` string: Import source: `API`, `Manual`, `CSV`, `Sales Navigator`, `HubSpot`, `Pipedrive`, `Filter`, or a legacy value.
      - `status` string: `mapped` when the list is usable, `pending mapping` while a file import waits for its column mapping.
      - `companiesOnly` boolean: True for company-only lists (Sales Navigator account scraps): no contact, no enrichment.
      - `numberOfContacts` integer
      - `numberOfEmails` integer
      - `numberOfPhones` integer
      - `numberOfLinkedins` integer: May be absent on old lists in the unpaginated mode.
      - `emailFindRunAt` string, date-time, nullable
      - `phoneFindRunAt` string, date-time, nullable
      - `enrichmentRun` ListsEnrichmentRunLock: Bulk job currently running on a list.
        - `tool` 'find-email' | 'find-phone' | 'verify-email' | 'normalize' | 'remove-emojis' | 'remove-spaces' | 'mapping' | 'crm-sync', required
        - `startedAt` string, date-time, required
        - `processed` integer, required
        - `total` integer, required
        - `found` integer, required
      - `tagIds` string[]
      - `fileId` string, nullable
      - `scrapId` string, nullable
      - `parentListId` string, nullable
      - `linkedLists` string[]
      - `createdAt` string, date-time
      - `updatedAt` string, date-time
    - `total` integer, required: Number of lists matching the filters.
    - `page` integer, required
    - `pageSize` integer, required
    - `totalLeads` integer, required: Sum of `numberOfContacts` over all matching lists.
  - ListsList[]
    - `_id` string, required: List id.
    - `userId` string
    - `name` string, required
    - `source` string: Import source: `API`, `Manual`, `CSV`, `Sales Navigator`, `HubSpot`, `Pipedrive`, `Filter`, or a legacy value.
    - `status` string: `mapped` when the list is usable, `pending mapping` while a file import waits for its column mapping.
    - `companiesOnly` boolean: True for company-only lists (Sales Navigator account scraps): no contact, no enrichment.
    - `numberOfContacts` integer
    - `numberOfEmails` integer
    - `numberOfPhones` integer
    - `numberOfLinkedins` integer: May be absent on old lists in the unpaginated mode.
    - `emailFindRunAt` string, date-time, nullable
    - `phoneFindRunAt` string, date-time, nullable
    - `enrichmentRun` ListsEnrichmentRunLock: Bulk job currently running on a list.
      - `tool` 'find-email' | 'find-phone' | 'verify-email' | 'normalize' | 'remove-emojis' | 'remove-spaces' | 'mapping' | 'crm-sync', required
      - `startedAt` string, date-time, required
      - `processed` integer, required
      - `total` integer, required
      - `found` integer, required
    - `tagIds` string[]
    - `fileId` string, nullable
    - `scrapId` string, nullable
    - `parentListId` string, nullable
    - `linkedLists` string[]
    - `createdAt` string, date-time
    - `updatedAt` string, date-time

## Other responses

- `401`: Missing, unknown or disabled API key, or the account of the key no longer exists. Note the body shape: `error` and `code`, not `message`.
- `500`: Unexpected server error. `error`, when present, is a raw internal message: do not parse it. Retry later.

---

[API](https://skmtc.dev/emelia/apis/emelia-api.md) · [All operations](https://skmtc.dev/emelia/apis/emelia-api/llms.txt) · [OpenAPI document](https://skmtc.dev/emelia/apis/emelia-api/revisions/8c0cb435f2c4?raw)