Skip to main content

Hiring Signals API

Overview​

The Hiring Signals API allows ZipRecruiter partners to report hiring-related events (interviews, offers, hires, rejections) for applications we have forwarded to them.

Authentication​

This API uses Basic authentication. Include your API key in the Authorization header of every request.

Application Identification​

Each event must reference a specific application. Provide one of the three identifier options below.

zr_application_id (Option 1) is our preferred method for identifying applicants — it is included in every Apply Webhook delivery and requires no setup on your end. Use application_id or job_id + candidate_id only when an alternative has been explicitly discussed and agreed upon with ZipRecruiter.

Use the identifier ZipRecruiter sent with the application via the Apply Webhook.

{
  "zr_application_id": "681d065d",
  "event": "contacted",
  "event_timestamp": "2021-01-25T18:46:04Z"
}

This is the preferred and simplest option — the zr_application_id is included in every webhook delivery.

note

To use options 2 or 3, your endpoint must return those fields in the Apply Webhook response as described here. If you want to use these fields but cannot return them in that response, please contact us.

Reporting an Event​

Each event requires an event_timestamp (UTC, RFC 3339 format) and at least one of:

  • event — a standardized event type (e.g. hired, rejected, interviewed)
  • status_name — your system's name for the current status
  • status_group — your system's category for the current status

When possible, provide all three. For the full list of event types, rejection reasons, and optional fields, see the API Reference.

Using the reason field

reason categorizes a rejection and is only valid with the rejected event — do not provide it for any other event. The value must be one of the published enum values; any other value (including null) will cause the event to be rejected. See the event reference for the full list of accepted values.

Quick Start​

Example request
curl https://api.ziprecruiter.com/hiring-signal/v0/event \
  -H "Authorization: Basic YOUR_API_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "zr_application_id": "681d065d",
    "event": "contacted",
    "event_timestamp": "2021-01-25T18:46:04Z"
  }'

Test Your Payload​

Validate a hiring-signal event in your browser — no request is sent and nothing is recorded. This checks your payload against the exact schema our API enforces: one application identifier, an event_timestamp, and at least one of event / status_name / status_group. Paste a payload and click Validate to catch problems before you integrate.

Loading schemas...
note

This validates the payload shape only. A schema-valid request returns 200, but a live call still returns 404 if the identifier does not match a known application in our system.

API Reference​

See the API Reference for full endpoint documentation including request/response schemas, event type enumerations, rejection reason codes, and error formats.