> ## Documentation Index > Fetch the complete documentation index at: https://docs.companyenrich.com/llms.txt > Use this file to discover all available pages before exploring further. # Create list > **Cost:** - For search: 1 credit per company returned. 1 credit if no results are found. - For similar: 5 credits per company returned. 5 credits if no results are found. Creates a new list based on a search or similar company request. Up to first 5000 results can be selected to be added to the list. If no companies are found, the list is not created. ## OpenAPI ````yaml openapi/v1.json POST /lists/companies openapi: 3.0.4 info: title: Company Enrich API description: >- The Company Enrich API provides programmatic access to a comprehensive database of company and person data for enrichment, search, and lead generation. ## Key Features - **Company Enrichment** — Enrich company profiles by domain, ID, or matching properties. Supports single lookups, batch requests, and bulk background jobs. - **Company Search** — Search and filter companies by industry, location, size, technology usage, keywords, and more. Supports page-based, cursor-based, and async export pagination. - **People Search** — Search for professionals by job title, company, location, and other criteria. Export results in CSV or JSON. - **Similar Companies** — Find companies similar to a given company based on shared attributes. - **Company Lists** — Create and manage saved lists of companies for organizing and exporting your data. ## Authentication All API requests require a Bearer token passed in the `Authorization` header: ``` Authorization: Bearer YOUR_API_TOKEN ``` You can generate API tokens from your [dashboard](https://companyenrich.com/dashboard). ## Credits Most API calls consume credits. The credit cost for each endpoint is documented in its description. You can check your remaining credit balance using the User endpoint. ## Rate Limiting The global API limiter allows **500 requests per minute** per IP address. Authenticated API routes also use a per-user route limiter based on plan capabilities. Supplementary lookup endpoints (such as keyword/technology/industry autocompletes) use a separate per-user route-level bucket. termsOfService: https://companyenrich.com/terms-and-conditions contact: url: https://companyenrich.com/ email: support@companyenrich.com version: 1.0.0 servers: - url: https://api.companyenrich.com security: - Bearer: [] tags: - name: Company / Enrichment description: >- Enrich company data by domain, properties, or in batch. Get company details by ID. - name: Company / Bulk Enrichment description: >- Create and manage asynchronous bulk enrichment jobs for large domain lists. - name: Company / Search description: Search companies by filters with pagination and cursor scrolling. - name: Company / Export description: Create and manage asynchronous company search export jobs. - name: Company / Similar description: Find companies similar to a given company by domain or ID. - name: People / Search description: >- Search people by various criteria with page-based or cursor-based pagination. - name: People / Enrichment description: >- Resolve work email addresses for individual people in realtime or background jobs. - name: People / Export description: Create and manage asynchronous people search export jobs. - name: Jobs description: >- Endpoints for listing and monitoring background processing jobs such as bulk enrichments and async exports. - name: Company / Lists description: Endpoints for creating and managing company lists and export lists. - name: Geo description: >- Endpoints for looking up geographic data including regions, countries, states, and cities. - name: Industries description: >- Endpoints for listing available industry classifications used in company search filters. - name: Keywords description: Endpoints for looking up keywords used in company search filters. - name: Technologies description: Endpoints for looking up technologies used in company search filters. - name: User description: >- Endpoints for retrieving information about the authenticated user, including credit balance and account details. - name: Positions description: >- Endpoints for looking up job positions and titles used in people search filters. paths: /lists/companies: post: tags: - Company / Lists summary: Create list description: >- **Cost:** - For search: 1 credit per company returned. 1 credit if no results are found. - For similar: 5 credits per company returned. 5 credits if no results are found. Creates a new list based on a search or similar company request. Up to first 5000 results can be selected to be added to the list. If no companies are found, the list is not created. requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateListInput' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CompanyListInfo' '400': description: Bad Request content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '401': description: Unauthorized content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '402': description: Payment Required content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '422': description: Unprocessable Entity content: application/problem+json: schema: $ref: '#/components/schemas/HttpValidationProblemDetails' '429': description: Too Many Requests content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' components: schemas: CreateListInput: required: - name - count type: object properties: name: maxLength: 1024 type: string description: The name of the list count: maximum: 10000 minimum: 1 type: integer description: The number of companies to add to the list format: int32 search: $ref: '#/components/schemas/CompanySearchInput2' similar: $ref: '#/components/schemas/CompanySimilarInput' CompanyListInfo: required: - id - name - createdAt - originalCount - type type: object properties: id: type: string format: uuid name: type: string createdAt: type: string format: date-time originalCount: type: integer format: int32 type: $ref: '#/components/schemas/CompanyListType' ProblemDetails: type: object properties: type: type: string nullable: true title: type: string nullable: true status: type: integer format: int32 nullable: true detail: type: string nullable: true instance: type: string nullable: true HttpValidationProblemDetails: type: object properties: type: type: string nullable: true title: type: string nullable: true status: type: integer format: int32 nullable: true detail: type: string nullable: true instance: type: string nullable: true errors: type: object additionalProperties: type: array items: type: string CompanySearchInput2: type: object properties: lists: type: array items: type: string format: uuid description: The list IDs to filter by nullable: true semanticQuery: maxLength: 500 type: string description: >- The semantic search query to find companies with. More natural language version of the standard query. nullable: true semanticWeight: maximum: 1 minimum: 0 type: number description: >- The semantic weight to apply to the results. Must be between 0 and 1. 0.7 is default. Larger values will prioritize semantic similarity, smaller values will prioritize traditional search factors. format: double nullable: true exclude: $ref: '#/components/schemas/CompanyExcludeFilters' query: maxLength: 250 type: string description: The search query to apply on the company name and domain nullable: true foundedYear: $ref: '#/components/schemas/YearRange' fundingAmount: $ref: '#/components/schemas/CompanyFundingAmountRange' fundingYear: $ref: '#/components/schemas/YearRange' categoryOperator: $ref: '#/components/schemas/NullableOfFilterOperator' keywordsOperator: $ref: '#/components/schemas/NullableOfFilterOperator' technologiesOperator: $ref: '#/components/schemas/NullableOfFilterOperator' workforceGrowth: $ref: '#/components/schemas/CompanyWorkforceGrowthInput' workforceSize: type: array items: $ref: '#/components/schemas/CompanyWorkforceSizeInput' description: >- Filter companies by absolute workforce headcount. Multiple entries can be provided to filter on different departments simultaneously. nullable: true require: type: array items: $ref: '#/components/schemas/FeatureRequirement' description: The features that must exist for the company nullable: true regions: type: array items: type: string description: The region IDs to filter by nullable: true countries: type: array items: type: string description: The 2 letter country codes to filter by nullable: true states: type: array items: type: integer format: int32 description: The state IDs to filter by nullable: true cities: type: array items: type: integer format: int32 description: The city IDs to filter by nullable: true type: type: array items: $ref: '#/components/schemas/CompanyType' description: The list of company types to filter by nullable: true category: type: array items: $ref: '#/components/schemas/CompanyCategory' description: The list of company categories to filter by nullable: true employees: type: array items: $ref: '#/components/schemas/CompanyEmployees' description: The list of employee counts to filter by nullable: true reportedEmployees: type: array items: $ref: '#/components/schemas/CompanyEmployees' description: The list of externally reported employee counts to filter by nullable: true revenue: type: array items: $ref: '#/components/schemas/CompanyRevenue' description: The list of revenue ranges to filter by nullable: true naicsCode: type: array items: type: integer format: int32 description: >- The NAICS codes to filter by. Can be 2 to 6 digit codes. In case of a 2-5 digit code, all 6 digit codes under it will be included nullable: true keywords: type: array items: type: string description: The keywords to filter by nullable: true technologies: type: array items: type: string description: The technologies to filter by nullable: true fundingRounds: type: array items: $ref: '#/components/schemas/CompanyFundingRound' description: The funding rounds to filter by nullable: true description: The filters to be applied on the companies nullable: true CompanySimilarInput: type: object properties: domains: maxItems: 10 minItems: 1 type: array items: type: string description: >- The domains to find similar companies for. Up to 10 domains are allowed. similarityWeight: maximum: 1 minimum: -1 type: number description: >- The similarity weight to apply to the results. Must be between -1 and 1. 0 is default. Larger values will prioritize more similar companies, smaller values will prioritize more established companies. format: double minScore: maximum: 1 minimum: 0 type: number description: >- The minimum similarity score required for results. Must be between 0 and 1. When omitted, the default cutoff is used. format: double nullable: true exclude: $ref: '#/components/schemas/CompanyExcludeFilters' query: maxLength: 250 type: string description: The search query to apply on the company name and domain nullable: true foundedYear: $ref: '#/components/schemas/YearRange' fundingAmount: $ref: '#/components/schemas/CompanyFundingAmountRange' fundingYear: $ref: '#/components/schemas/YearRange' categoryOperator: $ref: '#/components/schemas/NullableOfFilterOperator' keywordsOperator: $ref: '#/components/schemas/NullableOfFilterOperator' technologiesOperator: $ref: '#/components/schemas/NullableOfFilterOperator' workforceGrowth: $ref: '#/components/schemas/CompanyWorkforceGrowthInput' workforceSize: type: array items: {} description: >- Filter companies by absolute workforce headcount. Multiple entries can be provided to filter on different departments simultaneously. nullable: true require: type: array items: $ref: '#/components/schemas/FeatureRequirement' description: The features that must exist for the company nullable: true regions: type: array items: type: string description: The region IDs to filter by nullable: true countries: type: array items: type: string description: The 2 letter country codes to filter by nullable: true states: type: array items: type: integer format: int32 description: The state IDs to filter by nullable: true cities: type: array items: type: integer format: int32 description: The city IDs to filter by nullable: true type: type: array items: $ref: '#/components/schemas/CompanyType' description: The list of company types to filter by nullable: true category: type: array items: $ref: '#/components/schemas/CompanyCategory' description: The list of company categories to filter by nullable: true employees: type: array items: $ref: '#/components/schemas/CompanyEmployees' description: The list of employee counts to filter by nullable: true reportedEmployees: type: array items: $ref: '#/components/schemas/CompanyEmployees' description: The list of externally reported employee counts to filter by nullable: true revenue: type: array items: $ref: '#/components/schemas/CompanyRevenue' description: The list of revenue ranges to filter by nullable: true naicsCode: type: array items: type: integer format: int32 description: >- The NAICS codes to filter by. Can be 2 to 6 digit codes. In case of a 2-5 digit code, all 6 digit codes under it will be included nullable: true keywords: type: array items: type: string description: The keywords to filter by nullable: true technologies: type: array items: type: string description: The technologies to filter by nullable: true fundingRounds: type: array items: $ref: '#/components/schemas/CompanyFundingRound' description: The funding rounds to filter by nullable: true description: The filters used to find similar companies nullable: true CompanyListType: enum: - Manual - Export CompanyExcludeFilters: type: object properties: domains: type: array items: type: string description: The domain names of companies to exclude from the results nullable: true regions: type: array items: type: string description: The region IDs to filter by nullable: true countries: type: array items: type: string description: The 2 letter country codes to filter by nullable: true states: type: array items: type: integer format: int32 description: The state IDs to filter by nullable: true cities: type: array items: type: integer format: int32 description: The city IDs to filter by nullable: true type: type: array items: $ref: '#/components/schemas/CompanyType' description: The list of company types to filter by nullable: true category: type: array items: $ref: '#/components/schemas/CompanyCategory' description: The list of company categories to filter by nullable: true employees: type: array items: $ref: '#/components/schemas/CompanyEmployees' description: The list of employee counts to filter by nullable: true reportedEmployees: type: array items: $ref: '#/components/schemas/CompanyEmployees' description: The list of externally reported employee counts to filter by nullable: true revenue: type: array items: $ref: '#/components/schemas/CompanyRevenue' description: The list of revenue ranges to filter by nullable: true naicsCode: type: array items: type: integer format: int32 description: >- The NAICS codes to filter by. Can be 2 to 6 digit codes. In case of a 2-5 digit code, all 6 digit codes under it will be included nullable: true keywords: type: array items: type: string description: The keywords to filter by nullable: true technologies: type: array items: type: string description: The technologies to filter by nullable: true fundingRounds: type: array items: $ref: '#/components/schemas/CompanyFundingRound' description: The funding rounds to filter by nullable: true description: >- Exclusion filters to apply on the companies. If a company matches any of the filters here, it will be excluded from the results. nullable: true YearRange: type: object properties: min: type: integer description: The minimum year (inclusive) format: int32 nullable: true max: type: integer description: The maximum year (inclusive) format: int32 nullable: true description: The range of years nullable: true CompanyFundingAmountRange: type: object properties: min: type: number description: The minimum funding amount (inclusive) format: double nullable: true max: type: number description: The maximum funding amount (inclusive) format: double nullable: true description: The funding amount range to filter by nullable: true NullableOfFilterOperator: enum: - And - Or - null description: The operator to apply to the filters. Defaults to And. nullable: true CompanyWorkforceGrowthInput: type: object properties: period: $ref: '#/components/schemas/NullableOfCompanyWorkforceGrowthPeriod' department: $ref: '#/components/schemas/NullableOfCompanyWorkforceGrowthDepartment' minPercent: type: number description: >- The minimum workforce growth percentage (inclusive). Example: 15 means 15% growth, -10 means 10% decline. format: double nullable: true maxPercent: type: number description: >- The maximum workforce growth percentage (inclusive). Example: 15 means 15% growth, -10 means 10% decline. format: double nullable: true description: >- Filter companies by workforce growth percentage over a selected period and department. nullable: true CompanyWorkforceSizeInput: type: object properties: department: $ref: '#/components/schemas/NullableOfCompanyWorkforceGrowthDepartment2' min: type: integer description: The minimum headcount (inclusive). format: int32 nullable: true max: type: integer description: The maximum headcount (inclusive). format: int32 nullable: true FeatureRequirement: enum: - linkedin - twitter - facebook - instagram - angellist - crunchbase - youtube - country - city - state - revenue - foundedYear - anyFunding CompanyType: enum: - private - public - self-employed - self-owned - partnership - nonprofit - educational - government CompanyCategory: enum: - b2b - b2c - b2g - e-commerce - media - service-provider - mobile - saas - local-business CompanyEmployees: enum: - 1-10 - 11-50 - 51-200 - 201-500 - 501-1K - 1K-5K - 5K-10K - over-10K CompanyRevenue: enum: - under-1m - 1m-10m - 10m-50m - 50m-100m - 100m-200m - 200m-1b - over-1b CompanyFundingRound: enum: - seed - debt_financing - angel - venture - series_a - series_b - series_c - series_d - series_e - series_f - series_g - series_h - other NullableOfCompanyWorkforceGrowthPeriod: enum: - m6 - y1 - y2 - null description: The period to measure workforce growth over. nullable: true NullableOfCompanyWorkforceGrowthDepartment: enum: - overall - c_suite - product_management - engineering_technical - design - education - finance - human_resources - information_technology - legal - marketing - medical_health - operations - sales - consulting - null description: The department to measure workforce growth for. nullable: true NullableOfCompanyWorkforceGrowthDepartment2: enum: - overall - c_suite - product_management - engineering_technical - design - education - finance - human_resources - information_technology - legal - marketing - medical_health - operations - sales - consulting - null description: >- The department to filter headcount for. Defaults to overall if not specified. nullable: true securitySchemes: Bearer: type: apiKey description: >- API Token used for authentication. Example: "Authorization: Bearer {token}" name: Authorization in: header x-bearer-format: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.