Custom Fields

Candidate Custom Fields

Each candidate object accepts an optional custom_fields object containing key-value pairs. These fields are stored on the candidate record.

Keys are strings
Values can be a string, number, or boolean

"custom_fields": {
  "years_of_experience": "5",
  "current_company": "Acme Corp"
}

Purpose

Custom fields allow you to attach additional candidate data from your ATS/CRM that does not map to a dedicated API field. When Tidyhire delivers an interview.ended or call.ended webhook, the candidate’s custom fields are included in the payload. By passing an internal identifier — such as your ATS candidate ID, application ID, or request UID — you can reliably match each webhook to the corresponding record in your system:

Webhook payload excerpt

{
  "event": "call.ended",
  "data": {
    "candidate": {
      "id": "ats-candidate-001",
      "name": "John Doe",
      "custom_fields": {
        "ats_candidate_id": "ATS-456",
        "application_id": "APP-99123"
      }
    }
  }
}

This provides a deterministic primary key for webhook processing. Without it, webhook payloads would need to be matched against phone numbers or email addresses.

Primary Use Cases

Webhook correlation — pass an internal identifier and use it as the lookup key when processing webhook events
ATS context — candidate source (linkedin, referral), current stage, requisition links
Screening inputs — experience summaries, notice periods, current compensation
Tracking — campaign IDs, application timestamps, cost per source

Field Lifecycle

Stored on the candidate record and visible in the candidate’s profile in the Tidyhire dashboard
Returned in the API response (candidates[].custom_fields) after the request is processed
Echoed in webhook payloads (data.candidate.custom_fields) for correlation
Updated when a subsequent request contains the same candidate id, keeping fields in sync with your ATS

Response excerpt

{
  "candidate_id": "ats-candidate-001",
  "name": "John Doe",
  "status": "success",
  "custom_fields": {
    "years_of_experience": "5",
    "current_company": "Acme Corp",
    "source": "linkedin"
  }
}

Use stable, snake_case key names (for example, current_company). The same keys appear in API responses and webhook payloads, so consistent naming simplifies downstream lookups.

API Reference

API Key

Interview

Call

Others

Candidate Custom Fields

Purpose

Primary Use Cases

Field Lifecycle

​Candidate Custom Fields

​Purpose

​Primary Use Cases

​Field Lifecycle

Candidate Custom Fields

Purpose

Primary Use Cases

Field Lifecycle