> ## 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. # Get company workforce insights > **Cost:** 1 credit per successful page, including each earlier year of history. Provide exactly one lookup parameter: `id` or `domain`. Returns current observed employee count, employee range, and department headcounts, together with the latest 12 months of workforce history. Pass `nextCursor` from this endpoint or a company's `workforce` expansion with the same company to retrieve the preceding 12-month page. Cursors expire 30 minutes after the first page. Invalid cursors and missing companies or historical pages do not consume credits. ## OpenAPI ````yaml openapi/v2.json GET /v2/companies/workforce openapi: 3.0.4 info: title: Company Enrich API v2 description: >- The Company Enrich API v2 provides programmatic access to company and person data for enrichment, search, and lead generation. ## Key Features - **Company Enrichment** — Enrich company profiles by domain or identifying properties, and retrieve stored companies by ID. - **Company Search** — Search and filter companies with cursor pagination, counts, and previews. - **Semantic and Lookalike Search** — Find companies using natural-language queries or similar company domains. - **People Enrichment** — Retrieve people by ID, identify people from their email address, and find work email addresses. - **People Search** — Search people by position, seniority, department, location, education, and company with cursor pagination, counts, and previews. - **Reference Data** — Look up industries, geographic data, keywords, technologies, and job titles. V2 intentionally excludes saved company lists, list-based exports, and filtering searches by saved-list IDs. These features remain available in V1 and are not planned for V2. ## 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: 2.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: 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: 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. paths: /v2/companies/workforce: get: tags: - Company / Enrichment summary: Get company workforce insights description: >- **Cost:** 1 credit per successful page, including each earlier year of history. Provide exactly one lookup parameter: `id` or `domain`. Returns current observed employee count, employee range, and department headcounts, together with the latest 12 months of workforce history. Pass `nextCursor` from this endpoint or a company's `workforce` expansion with the same company to retrieve the preceding 12-month page. Cursors expire 30 minutes after the first page. Invalid cursors and missing companies or historical pages do not consume credits. parameters: - name: id in: query description: The CompanyEnrich company ID. Provide exactly one of id or domain. schema: type: string format: uuid - name: domain in: query description: The company domain. Provide exactly one of id or domain. schema: maxLength: 1024 type: string - name: cursor in: query description: >- The nextCursor from a previous workforce response or company expansion. Omit for the latest 12 months. schema: maxLength: 1024 type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CompanyWorkforceResponse2' '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' '404': description: Not Found 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: CompanyWorkforceResponse2: required: - companyId - domain - observedEmployeeCount - departmentHeadcount - unclassifiedHeadcount - historyFrom - historyTo type: object properties: companyId: type: string description: The CompanyEnrich ID of the company format: uuid domain: type: string description: The canonical company domain observedEmployeeCount: type: integer description: >- The observed number of distinct current employees in the people dataset format: int32 employeeCountRange: $ref: '#/components/schemas/NullableOfCompanyEmployees' departmentHeadcount: $ref: '#/components/schemas/CompanyWorkforceDepartmentResponse' unclassifiedHeadcount: type: integer description: Observed headcount that could not be classified by department format: int32 historyFrom: type: string description: The inclusive first month of the returned 12-month history window format: date historyTo: type: string description: The exclusive end of the returned 12-month history window format: date history: type: array items: $ref: '#/components/schemas/CompanyWorkforceHistoryResponse' description: >- Workforce change points within the history window, newest first. A point at the start carries forward the last known earlier headcount when available. nullable: true nextCursor: type: string description: >- Pass this cursor with the company ID or domain to GET /v2/companies/workforce to fetch the preceding year for 1 credit. Omitted when no older history is available. Expires 30 minutes after the first page. nullable: true 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 NullableOfCompanyEmployees: enum: - 1-10 - 11-50 - 51-200 - 201-500 - 501-1K - 1K-5K - 5K-10K - over-10K - null description: The estimated employee count range nullable: true CompanyWorkforceDepartmentResponse: type: object properties: cSuite: type: integer description: Observed c-suite headcount format: int32 nullable: true productManagement: type: integer description: Observed product management headcount format: int32 nullable: true engineeringTechnical: type: integer description: Observed engineering and technical headcount format: int32 nullable: true design: type: integer description: Observed design headcount format: int32 nullable: true education: type: integer description: Observed education headcount format: int32 nullable: true finance: type: integer description: Observed finance headcount format: int32 nullable: true humanResources: type: integer description: Observed human resources headcount format: int32 nullable: true informationTechnology: type: integer description: Observed information technology headcount format: int32 nullable: true legal: type: integer description: Observed legal headcount format: int32 nullable: true marketing: type: integer description: Observed marketing headcount format: int32 nullable: true medicalHealth: type: integer description: Observed medical and health headcount format: int32 nullable: true operations: type: integer description: Observed operations headcount format: int32 nullable: true sales: type: integer description: Observed sales headcount format: int32 nullable: true consulting: type: integer description: Observed consulting headcount format: int32 nullable: true description: Observed headcount grouped by department CompanyWorkforceHistoryResponse: required: - date - observedEmployeeCount - departmentHeadcount - unclassifiedHeadcount type: object properties: date: type: string description: The first day of the snapshot month format: date observedEmployeeCount: type: integer description: The observed number of distinct employees in the people dataset format: int32 employeeCountRange: $ref: '#/components/schemas/NullableOfCompanyEmployees' departmentHeadcount: $ref: '#/components/schemas/CompanyWorkforceDepartmentResponse' unclassifiedHeadcount: type: integer description: Observed headcount that could not be classified by department format: int32 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.