---
title: "POST /v2/lists"
method: POST
path: "/v2/lists"
tags: ["lists"]
---

# POST /v2/lists

`POST /v2/lists`

## Request

- Base URL: `https://api.thecompaniesapi.com`
- URL: `https://api.thecompaniesapi.com/v2/lists`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/thecompaniesapi/apis/the-companies-api/docs/v2/lists/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a new list.

## Request body

- object
  - `dynamic` boolean
  - `imported` boolean
  - `mailFrequency` 'disabled' | 'daily' | 'weekly' | 'monthly'
  - `maxCompanies` number
  - `name` string, required
  - `processInitialized` boolean
  - `query` SegmentationCondition[]
    - `attribute` 'about.businessType' | 'about.industries' | 'about.industry' | 'about.name' | 'about.totalEmployees' | 'about.yearFounded' | 'ai.search' | 'analytics.monthlyVisitors' | 'apps' | 'codes.naics' | 'codes.sic' | 'contacts' | 'domain.domain' | 'domain.tld' | 'finances.revenue' | 'finances.stockExchange' | 'locations.headquarters.city.code' | 'locations.headquarters.continent.code' | 'locations.headquarters.country.code' | 'locations.headquarters.county.code' | 'locations.headquarters.state.code' | 'meta.listIds' | 'meta.score' | 'meta.syncedAt' | 'socials' | 'socials.linkedin.id' | 'technologies.active' | 'technologies.categories' | 'urls', required
    - `blockedOperator` boolean
    - `operator` 'and' | 'or', required
    - `sign` 'equals' | 'exactEquals' | 'greater' | 'lower' | 'notEquals', required
    - `values` union[], required
      - union
        - string
        - number
  - `similarDomains` string[]

## Response `200`

Create a new list.

- List: A collection of companies saved or imported by a team.
  - `analytics` ListAnalytics: Analytics collection of a list.
    - `companiesCount` number, nullable
    - `id` number
    - `listId` number, nullable
  - `companyListId` number, nullable
  - `createdAt` string, nullable, required
  - `dynamic` boolean, nullable, required
  - `exporting` boolean, required
  - `exportingAt` string, nullable, required
  - `id` number, required
  - `imported` boolean, required
  - `mailFrequencies` object, nullable
  - `maxCompanies` number, nullable, required
  - `name` string, required
  - `processActive` boolean, required
  - `processDisabled` boolean, nullable
  - `processingAt` string, nullable, required
  - `processInitialized` boolean, required
  - `processMessage` string, nullable, required
  - `query` SegmentationCondition[]
    - `attribute` 'about.businessType' | 'about.industries' | 'about.industry' | 'about.name' | 'about.totalEmployees' | 'about.yearFounded' | 'ai.search' | 'analytics.monthlyVisitors' | 'apps' | 'codes.naics' | 'codes.sic' | 'contacts' | 'domain.domain' | 'domain.tld' | 'finances.revenue' | 'finances.stockExchange' | 'locations.headquarters.city.code' | 'locations.headquarters.continent.code' | 'locations.headquarters.country.code' | 'locations.headquarters.county.code' | 'locations.headquarters.state.code' | 'meta.listIds' | 'meta.score' | 'meta.syncedAt' | 'socials' | 'socials.linkedin.id' | 'technologies.active' | 'technologies.categories' | 'urls', required
    - `blockedOperator` boolean
    - `operator` 'and' | 'or', required
    - `sign` 'equals' | 'exactEquals' | 'greater' | 'lower' | 'notEquals', required
    - `values` union[], required
      - union
        - string
        - number
  - `querySimilar` string[], required
  - `teamId` string, nullable
  - `unseenActions` Action[]
    - `attempts` number
    - `cost` number, nullable
    - `createdAt` string, nullable
    - `data` object
      - `cleanedUp` number
      - `completed` string[]
      - `completedDomains` number
      - `completedDomainsSample` string[]
      - `count` number
      - `domain` string
      - `domains` string[]
      - `domainsSample` string[]
      - `elasticQuery` unknown
      - `failed` string[]
      - `failedDomains` number
      - `failedDomainsSample` string[]
      - `fields` object[]
        - `description` string
        - `key` string, required
        - `type` 'array|boolean' | 'array|number' | 'array|string' | 'boolean' | 'number' | 'string', required
        - `values` string[]
      - `grounded` boolean
      - `job` 'ask-domain' | 'ask-list' | 'enrich-companies' | 'enrich-list' | 'cleanup-list'
      - `model` 'claude' | 'claude-mini' | 'cousteau' | 'cousteau2' | 'cousteau2-thinking' | 'gpt' | 'gpt-mini' | 'groq' | 'groq-mini' | 'llama4'
      - `query` SegmentationCondition[]
        - `attribute` 'about.businessType' | 'about.industries' | 'about.industry' | 'about.name' | 'about.totalEmployees' | 'about.yearFounded' | 'ai.search' | 'analytics.monthlyVisitors' | 'apps' | 'codes.naics' | 'codes.sic' | 'contacts' | 'domain.domain' | 'domain.tld' | 'finances.revenue' | 'finances.stockExchange' | 'locations.headquarters.city.code' | 'locations.headquarters.continent.code' | 'locations.headquarters.country.code' | 'locations.headquarters.county.code' | 'locations.headquarters.state.code' | 'meta.listIds' | 'meta.score' | 'meta.syncedAt' | 'socials' | 'socials.linkedin.id' | 'technologies.active' | 'technologies.categories' | 'urls', required
        - `blockedOperator` boolean
        - `operator` 'and' | 'or', required
        - `sign` 'equals' | 'exactEquals' | 'greater' | 'lower' | 'notEquals', required
        - `values` union[], required
          - union
            - string
            - number
      - `question` string
      - `team` Team: A collection of users that can access the same resources.
        - `admin` boolean, nullable, required
        - `country` string, nullable, required
        - `createdAt` string, nullable, required
        - `credits` number, required
        - `creditsPack` number, required
        - `id` number, required
        - `name` string, nullable, required
        - `role` string, nullable
        - `stripeCustomerId` string, nullable, required
        - `stripeProductId` string, nullable, required
        - `stripeSubscribed` boolean, required
        - `stripeSubscriptionId` string, nullable, required
        - `stripeSubscriptionStatus` string, nullable, required
        - `websiteUrl` string, nullable, required
      - `totalDomains` number
      - `user` User: A user of the platform.
        - `colorMode` 'dark' | 'light' | 'system'
        - `createdAt` string, nullable
        - `currentTeamId` number, nullable, required
        - `email` string, required
        - `emailFree` boolean, nullable, required
        - `emailVerified` boolean, nullable, required
        - `emailVerifiedResentAt` string, nullable, required
        - `fullName` string, nullable, required
        - `hasPassword` boolean, nullable, required
        - `id` number, required
        - `locale` unknown
        - `pictureUrl` string, nullable, required
        - `referral` string, nullable
        - `role` 'owner' | 'user', nullable
    - `id` number, required
    - `listId` number
    - `promptId` number
    - `result` object
      - `answers` LLMAnswer[]
        - `companyId` number, required
        - `explanation` string
        - `fields` object[]
          - `description` string
          - `key` string, required
          - `type` 'array|boolean' | 'array|number' | 'array|string' | 'boolean' | 'number' | 'string', required
          - `values` string[]
        - `grounded` boolean
        - `output` object, required
        - `question` string, required
        - `score` number, required
      - `cleanedUp` number
      - `domains` string[]
    - `status` 'active' | 'completed' | 'failed' | 'pending', required
    - `teamId` number
    - `type` 'companies:added' | 'jobs:request'
    - `updatedAt` string, nullable
  - `userId` number, nullable
  - `vectors` array[]
    - number[]

## Other responses

- `401`: The error message

---

[API](https://skmtc.dev/thecompaniesapi/apis/the-companies-api.md) - [All operations](https://skmtc.dev/thecompaniesapi/apis/the-companies-api/llms.txt) - [OpenAPI document](https://skmtc.dev/thecompaniesapi/apis/the-companies-api/revisions/f8bfc2d10b71?raw)