Skip to main content
PATCH
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.
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 and Remove a company.
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 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 to redeliver events after a webhook change.

Authorizations

Authorization
string
header
required

Use an Airscale workspace API key. Never expose the key in client-side code.

Path Parameters

monitor_id
string<uuid>
required

Body

application/json

Send at least one of name, frequency, action, webhook_url, or rotate_signing_secret. Any other field is rejected.

name
string
Required string length: 1 - 120
frequency
enum<string>
Available options:
daily,
weekly,
every_30_days,
every_90_days
action
enum<string>
Available options:
pause,
resume
webhook_url
string<uri> | null

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.

Maximum string length: 2048
rotate_signing_secret
boolean

Generate a new signing secret for the enabled webhook. Cannot be combined with webhook_url: null.

Response

The updated monitor. signing_secret and signing_secret_warning appear only when a new secret was generated.

monitor
object
required
signing_secret
string

Present only when the request set a new webhook URL or rotated the secret. Store it immediately.

signing_secret_warning
string