CompanyEnrich Positions API

openapi: 3.2.0
info:
  title: Company Enrich API v2 Positions API
  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.


    ## 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: Positions
  description: Endpoints for looking up job positions and titles.
paths:
  /v2/positions/autocomplete:
    get:
      tags:
      - Positions
      summary: Lookup positions
      description: Returns up to 10 position or job title suggestions in `items`, ordered by popularity. An empty query returns an empty list. No credits are deducted.
      parameters:
      - name: query
        in: query
        description: The position or job title prefix to look up. At most 100 characters; surrounding whitespace is ignored.
        required: true
        schema:
          maxLength: 100
          type: string
      responses:
        '422':
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/HttpValidationProblemDetails'
        '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'
        '429':
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupportListResponseOfstring'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: getV2PositionsAutocomplete
      x-operation-id-source: derived
components:
  schemas:
    ProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
          format: int32
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
    SupportListResponseOfstring:
      required:
      - items
      type: object
      properties:
        items:
          type: array
          items:
            type: string
          description: The reference values or suggestions returned by the request
    HttpValidationProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
          format: int32
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
  securitySchemes:
    Bearer:
      type: apiKey
      description: 'API Token used for authentication. Example: "Authorization: Bearer {token}"'
      name: Authorization
      in: header
      x-bearer-format: bearer