> ## 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.

# Update a new hire monitor

> Rename a monitor, change its frequency, pause or resume checks, change its webhook, or rotate the signing secret. 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.

Update one or more monitor fields with `PATCH`. The body accepts `name`, `frequency` (`daily`, `weekly`, `every_30_days`, `every_90_days`), `action` (`pause` or `resume`), `webhook_url`, and `rotate_signing_secret: true`, and they can be combined in one request, for example `{"name": "Target accounts (Q4)", "action": "pause"}`. Any other field returns `422 invalid_monitor_update`.

> [!WARNING]
>
> Filters and the audience cannot be edited: `job_titles`, `seniorities`, `hire_types`, and the market filters are create-only. Create a new monitor to change them. Company lists change through [Add companies](https://docs.airscale.io/api-reference/new-hire-monitors/companies/add.md) and [Remove a company](https://docs.airscale.io/api-reference/new-hire-monitors/companies/remove.md).

The response returns the complete updated monitor.

## Pause and resume

Pausing stops checks and clears `next_check_at`; webhooks queued for a paused monitor are cancelled, so [redeliver](https://docs.airscale.io/api-reference/new-hire-monitors/events/redeliver.md) them after resuming. Resuming schedules a check. Resuming a monitor that was paused because its filters matched too many people (`run_block_reason: "audience_needs_review"`) retries its first check. While new hire monitoring is closed, resuming returns `503 monitoring_not_enabled`.

Renaming renames the results table while it still has its generated `<name> — New hires` title. Legacy monitors (`legacy: true`) cannot switch to `daily` checks.

## Change the webhook or recover a lost signing secret

`webhook_url` accepts a public HTTPS URL without embedded credentials, or `null`. Invalid URLs return `422 invalid_monitor_update`.

* Setting or changing the URL generates a fresh signing secret.
* `{"rotate_signing_secret": true}` alone rotates the secret of the current webhook. Rotating without a webhook returns `422 webhook_not_configured`; combining rotation with `webhook_url: null` returns `422 invalid_monitor_update`.
* `{"webhook_url": null}` disables the webhook and clears its stored secret.
* Setting the same URL without rotation keeps the existing secret and returns no secret.

When a new secret is generated, the response includes `signing_secret` and `signing_secret_warning`. Store the secret immediately; list and get never return it.

Changing the URL, disabling, or rotating cancels queued deliveries made with the previous configuration (`error_code: "webhook_configuration_changed"`). When a send is in flight, the request returns `409 webhook_delivery_in_progress` and nothing changes; retry after it settles. Webhook changes keep the monitor, its baseline, schedule, and results table, and spend no credits.

## Next step

Use [List new hire events](https://docs.airscale.io/api-reference/new-hire-monitors/events.md) to redeliver events after a webhook change.


## OpenAPI

````yaml openapi.json PATCH /v1/new-hire-monitors/{monitor_id}
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}:
    patch:
      tags:
        - New hire monitoring
      summary: Rename, reschedule, pause, or resume a monitor, or change its webhook
      description: >-
        Changes the name or frequency, pauses or resumes checks, sets, changes,
        or disables the webhook, or rotates the signing secret. Fields can be
        combined in one request. Filters and the audience cannot be changed;
        create a new monitor instead. Setting a new webhook URL or rotating
        returns a one-time signing_secret. Requires a V2 workspace API key.
        Legacy V1 API keys are not supported. Monitors and their credits belong
        to the V2 workspace.
      operationId: updateNewHireMonitor
      parameters:
        - name: monitor_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: 61111111-1111-4111-8111-111111111111
      requestBody:
        required: true
        description: >-
          Send at least one of name, frequency, action, webhook_url, or
          rotate_signing_secret. Any other field is rejected.
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              minProperties: 1
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 120
                frequency:
                  type: string
                  enum:
                    - daily
                    - weekly
                    - every_30_days
                    - every_90_days
                action:
                  type: string
                  enum:
                    - pause
                    - resume
                webhook_url:
                  type:
                    - string
                    - 'null'
                  format: uri
                  maxLength: 2048
                  description: >-
                    Set or change the webhook (a public HTTPS URL without
                    embedded credentials), or send null to disable it and clear
                    its signing secret. Setting a new URL returns a fresh
                    signing_secret.
                rotate_signing_secret:
                  type: boolean
                  const: true
                  description: >-
                    Generate a new signing secret for the enabled webhook.
                    Cannot be combined with webhook_url: null.
            examples:
              frequency:
                summary: Change the check frequency
                value:
                  frequency: every_30_days
              pause:
                summary: Rename and pause checks
                value:
                  name: Target accounts (Q4)
                  action: pause
              resume:
                summary: Resume checks
                value:
                  action: resume
              webhook:
                summary: Set a webhook and get a new signing secret
                value:
                  webhook_url: https://hooks.example.com/airscale/new-hires
              rotate:
                summary: Rotate the signing secret
                value:
                  rotate_signing_secret: true
              disableWebhook:
                summary: Disable the webhook
                value:
                  webhook_url: null
      responses:
        '200':
          description: >-
            The updated monitor. signing_secret and signing_secret_warning
            appear only when a new secret was generated.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - monitor
                properties:
                  monitor:
                    $ref: '#/components/schemas/NewHireMonitor'
                  signing_secret:
                    type: string
                    description: >-
                      Present only when the request set a new webhook URL or
                      rotated the secret. Store it immediately.
                  signing_secret_warning:
                    type: string
              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: '2026-11-02T10:05:00.000Z'
                      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: 2
                      unresolved_company_count: 0
                      new_hire_count: 1
                      unread_event_count: 1
                    signing_secret: example-signing-secret
                    signing_secret_warning: Store this secret now. It is not returned again.
        '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
        '409':
          description: >-
            webhook_delivery_in_progress: a webhook send is in flight. The
            configuration was not changed; retry after the delivery settles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorApiError'
        '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_monitor_update (for example no supported field, an unknown
            field such as job_titles, a webhook_url that is not a public HTTPS
            destination, rotation combined with webhook_url: null, or daily
            checks on a legacy monitor) or webhook_not_configured when rotating
            without a webhook.
          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: >-
            monitoring_not_enabled when resuming while new hire monitoring is
            closed, or service_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
    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.