> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airscale.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Add companies to a new hire monitor

> Add up to 10,000 LinkedIn companies to a company-list monitor; adding a new company rebuilds the baseline. Rate limit: 120 requests per fixed minute per API key, shared by all new hire monitor endpoints.

> [!NOTE]
>
> New hire monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and their credits belong to the V2 workspace associated with the key.

Add 1 to 10,000 companies per request to a company-list monitor with `{ "companies": [{ "linkedin_url": ... }] }`. Companies the monitor already watches are ignored, and the `201` response reports the monitor, its complete company list, `added_company_count`, and `baseline_reset`.

> [!WARNING]
>
> **Adding a company restarts the baseline.** Adding a company the monitor does not already watch changes its scope: the monitor discards undelivered findings, cancels an in-progress check, and rebuilds its baseline on the next check, so hires that started before the change are not reported. The response has `baseline_reset: true`. Adding only companies the monitor already watches is a no-op (`added_company_count: 0`, `baseline_reset: false`).

A monitor holds at most 10,000 companies; exceeding it returns `422 company_limit_reached`. Invalid or duplicate URLs in the request return `422 invalid_companies`. A market monitor has no company list (`422 market_monitor_has_no_companies`), and monitors created before role filters existed can only be edited in the app (`422 legacy_monitor`).

The JSON request body must fit within **8 MiB (8,388,608 bytes)**; larger bodies return `413`. Adding companies spends no credits.

## Next step

Use [Get a new hire monitor](https://docs.airscale.io/api-reference/new-hire-monitors/get.md) to follow each company's resolution.


## OpenAPI

````yaml openapi.json POST /v1/new-hire-monitors/{monitor_id}/companies
openapi: 3.1.0
info:
  title: Airscale Public API
  version: '2026-09-11'
  description: >-
    Search, enrich, resolve public business data, and monitor job changes with
    Airscale.
  x-airscale-source-repository: ViceScale/airscale-code
  x-airscale-source-sha: 1de19e1b70a052a4b8d9c2075021a7e5e7a94d51
servers:
  - url: https://api.airscale.io
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Search and discovery
    description: Search people, companies, and the web.
  - name: Contact data
    description: Find professional and personal contact data.
  - name: Profiles and reverse lookup
    description: Extract profiles or resolve a person from known contact data.
  - name: Post engagement
    description: Retrieve and enrich people who liked or commented on LinkedIn posts.
  - name: LinkedIn content
    description: >-
      Search LinkedIn posts, read profile and company feeds, and retrieve
      profile comments and comment reactions.
  - name: Job change monitoring
    description: Track LinkedIn profiles and receive job-change events.
  - name: New hire monitoring
    description: Watch companies or the market for people who start a matching role.
  - name: Post engagement monitoring
    description: >-
      Follow LinkedIn company pages and profiles and receive the people who
      engage with their posts.
  - name: Account
    description: Inspect workspace account state.
  - name: Miscellaneous
    description: >-
      Find website technologies and check WhatsApp availability, Meta ads, and
      email deliverability.
paths:
  /v1/new-hire-monitors/{monitor_id}/companies:
    post:
      tags:
        - New hire monitoring
      summary: Add companies to a monitor
      description: >-
        Adds 1–10,000 LinkedIn companies per request to a company-list monitor,
        up to 10,000 companies in total. Companies the monitor already watches
        are ignored. Adding at least one new company changes the monitor's
        scope: undelivered findings are discarded, an in-progress check is
        cancelled, and the baseline is rebuilt on the next check, so hires that
        started before the change are not reported. Requires a V2 workspace API
        key. Legacy V1 API keys are not supported. Monitors and their credits
        belong to the V2 workspace.
      operationId: addNewHireMonitorCompanies
      parameters:
        - name: monitor_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: 61111111-1111-4111-8111-111111111111
      requestBody:
        required: true
        description: >-
          Provide 1–10,000 LinkedIn company URLs in a JSON body of at most 8 MiB
          (8,388,608 bytes), without exceeding 10,000 companies in the monitor.
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - companies
              properties:
                companies:
                  type: array
                  minItems: 1
                  maxItems: 10000
                  items:
                    type: object
                    additionalProperties: false
                    required:
                      - linkedin_url
                    properties:
                      linkedin_url:
                        type: string
                        minLength: 1
                        maxLength: 500
                        description: >-
                          A LinkedIn company URL with a slug or numeric company
                          ID, such as
                          https://www.linkedin.com/company/example-company.
                          Airscale canonicalizes it to
                          https://www.linkedin.com/company/{identifier}.
                  description: >-
                    1–10,000 LinkedIn company URLs. Two entries for the same
                    company are rejected.
            examples:
              companies:
                summary: Add one company
                value:
                  companies:
                    - linkedin_url: https://www.linkedin.com/company/example-company-3
      responses:
        '201':
          description: The monitor after the addition, with its complete company list.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - monitor
                  - companies
                  - added_company_count
                  - baseline_reset
                properties:
                  monitor:
                    $ref: '#/components/schemas/NewHireMonitor'
                  companies:
                    type: array
                    items:
                      $ref: '#/components/schemas/NewHireCompany'
                    description: >-
                      The monitor's company list, sorted by URL. Empty for a
                      market monitor.
                  added_company_count:
                    type: integer
                    minimum: 0
                    maximum: 10000
                  baseline_reset:
                    type: boolean
                    description: >-
                      true when at least one company was added and the baseline
                      will be rebuilt.
              examples:
                success:
                  summary: Successful response
                  value:
                    monitor:
                      id: 61111111-1111-4111-8111-111111111111
                      name: Target accounts
                      frequency: weekly
                      status: active
                      audience: companies
                      legacy: false
                      filters:
                        job_titles:
                          - VP Sales
                          - Head of Sales
                        excluded_job_titles: []
                        title_match: strict
                        seniorities: []
                        hire_types:
                          - external
                        industries: []
                        company_size: null
                        company_location: null
                        person_location: null
                      results_table_id: 64444444-4444-4444-8444-444444444444
                      results_status: ready
                      results_error: null
                      baseline_completed_at: null
                      next_check_at: '2026-11-09T10:05:00.000Z'
                      last_successful_check_at: '2026-11-02T10:05:00.000Z'
                      run_block_reason: null
                      created_at: '2026-11-02T10:00:00.000Z'
                      updated_at: '2026-11-02T10:05:00.000Z'
                      webhook_url: https://hooks.example.com/airscale/new-hires
                      webhook_configured: true
                      company_count: 3
                      unresolved_company_count: 1
                      new_hire_count: 1
                      unread_event_count: 1
                    companies:
                      - identifier: example-company
                        linkedin_url: https://www.linkedin.com/company/example-company
                        linkedin_company_id: '1035'
                        name: Example Company
                        status: resolved
                        last_checked_at: '2026-11-02T10:05:00.000Z'
                      - identifier: example-company-2
                        linkedin_url: https://www.linkedin.com/company/example-company-2
                        linkedin_company_id: '2036'
                        name: Example Company Two
                        status: resolved
                        last_checked_at: '2026-11-02T10:05:00.000Z'
                      - identifier: example-company-3
                        linkedin_url: https://www.linkedin.com/company/example-company-3
                        linkedin_company_id: null
                        name: null
                        status: pending
                        last_checked_at: null
                    added_company_count: 1
                    baseline_reset: true
        '400':
          description: >-
            The request body is missing or is not valid JSON. The public API
            returns {"error":"Invalid JSON"}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                error:
                  summary: Error response
                  value:
                    error: Invalid JSON
        '401':
          $ref: '#/components/responses/MonitorUnauthorized'
        '404':
          description: monitor_not_found in this workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorApiError'
              examples:
                error:
                  summary: Error response
                  value:
                    error:
                      code: monitor_not_found
                      message: Monitor not found
        '413':
          description: The JSON request body exceeds the 8 MiB (8,388,608 bytes) limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            invalid_companies (for example an invalid or duplicate LinkedIn
            company URL, or an unknown field), company_limit_reached when the
            monitor would exceed 10,000 companies, legacy_monitor for a monitor
            created before role filters existed, or
            market_monitor_has_no_companies.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorApiError'
        '429':
          description: >-
            The API key has exceeded 120 requests in the current minute across
            new hire monitor endpoints. Wait for the Retry-After seconds before
            retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                error:
                  summary: Error response
                  value:
                    error: Too Many Requests
                    message: 'Rate limit exceeded: 120 requests per minute'
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: string
              example: '60'
        '503':
          description: 'service_unavailable: new hire monitoring is temporarily unavailable.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorApiError'
components:
  schemas:
    NewHireMonitor:
      type: object
      additionalProperties: false
      required:
        - id
        - name
        - frequency
        - status
        - audience
        - legacy
        - filters
        - results_table_id
        - results_status
        - results_error
        - baseline_completed_at
        - next_check_at
        - last_successful_check_at
        - run_block_reason
        - created_at
        - updated_at
        - webhook_url
        - webhook_configured
        - company_count
        - unresolved_company_count
        - new_hire_count
        - unread_event_count
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        frequency:
          type: string
          enum:
            - daily
            - weekly
            - every_30_days
            - every_90_days
        status:
          type: string
          enum:
            - active
            - paused
        audience:
          type: string
          enum:
            - companies
            - market
        legacy:
          type: boolean
          description: >-
            true for monitors created in the app before role filters existed.
            They have filters: null and can be read, paused, resumed and
            renamed, but their companies can only be edited in the app.
        filters:
          description: >-
            The role and market filters set at creation, or null for a legacy
            monitor. Filters cannot be edited.
          oneOf:
            - $ref: '#/components/schemas/NewHireMonitorFilters'
            - type: 'null'
        results_table_id:
          type: string
          description: The Airscale results table that receives one row per new hire.
        results_status:
          type: string
          enum:
            - ready
            - pending
            - blocked
          description: >-
            Whether found new hires are delivered to the results table. pending:
            deliveries are waiting. blocked: see results_error.
        results_error:
          type:
            - string
            - 'null'
          description: >-
            Why found new hires are not yet delivered, for example
            insufficient_credits, results_table_deleted,
            table_row_limit_reached, results_columns_missing, or a temporary
            credit_settlement_busy or table_mutation_locked.
        baseline_completed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the first completed check recorded the baseline. null until it
            exists, and again after a company change resets it.
        next_check_at:
          type:
            - string
            - 'null'
          format: date-time
        last_successful_check_at:
          type:
            - string
            - 'null'
          format: date-time
        run_block_reason:
          type:
            - string
            - 'null'
          description: >-
            Why checks are not progressing, for example unresolved_companies,
            audience_needs_review, unsupported_location, or a temporary
            account_pool_unavailable.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        webhook_url:
          type:
            - string
            - 'null'
          format: uri
        webhook_configured:
          type: boolean
        company_count:
          type: integer
          minimum: 0
          maximum: 10000
          description: 0 for a market monitor.
        unresolved_company_count:
          type: integer
          minimum: 0
          description: Companies that are pending or could not be found.
        new_hire_count:
          type: integer
          minimum: 0
          description: Every delivered new hire, not only the 100-event preview.
        unread_event_count:
          type: integer
          minimum: 0
    NewHireCompany:
      type: object
      additionalProperties: false
      required:
        - identifier
        - linkedin_url
        - linkedin_company_id
        - name
        - status
        - last_checked_at
      properties:
        identifier:
          type: string
          description: >-
            The lower-case company slug or numeric company ID from the LinkedIn
            URL. Use it to remove the company.
        linkedin_url:
          type: string
          format: uri
        linkedin_company_id:
          type:
            - string
            - 'null'
          description: The numeric LinkedIn company ID once the company is resolved.
        name:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - pending
            - resolved
            - unresolved
        last_checked_at:
          type:
            - string
            - 'null'
          format: date-time
    Error:
      type: object
      additionalProperties: true
      properties:
        error:
          type: string
        message:
          type: string
    MonitorApiError:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
    NewHireMonitorFilters:
      type: object
      additionalProperties: false
      required:
        - job_titles
        - excluded_job_titles
        - title_match
        - seniorities
        - hire_types
        - industries
        - company_size
        - company_location
        - person_location
      properties:
        job_titles:
          type: array
          items:
            type: string
        excluded_job_titles:
          type: array
          items:
            type: string
        title_match:
          type: string
          enum:
            - strict
            - loose
        seniorities:
          type: array
          items:
            type: string
            enum:
              - individual_contributor
              - manager
              - director
              - executive
          description: Empty means every seniority.
        hire_types:
          type: array
          items:
            type: string
            enum:
              - external
              - internal
        industries:
          type: array
          items:
            type: string
        company_size:
          type:
            - string
            - 'null'
          enum:
            - 1-10
            - 11-50
            - 51-200
            - 201-500
            - 501-1000
            - 1001-5000
            - 5001-10000
            - 10001+
            - null
        company_location:
          type:
            - string
            - 'null'
        person_location:
          type:
            - string
            - 'null'
  responses:
    MonitorUnauthorized:
      description: >-
        A missing Bearer token returns
        {"error":"Unauthorized","message":"Missing or invalid bearer token"}. An
        unknown API key returns invalid_api_key.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/MonitorApiError'
              - $ref: '#/components/schemas/Error'
          examples:
            invalidKey:
              summary: Unknown API key
              value:
                error:
                  code: invalid_api_key
                  message: The API key is not valid
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: >-
        Use an Airscale workspace API key. Never expose the key in client-side
        code.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.