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

# Custom Fields

> Store additional candidate data with 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

```json theme={null}
"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](/webhooks/response-structure), 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:

```json Webhook payload excerpt theme={null} theme={null}
{
  "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

```json Response excerpt theme={null} theme={null}
{
  "candidate_id": "ats-candidate-001",
  "name": "John Doe",
  "status": "success",
  "custom_fields": {
    "years_of_experience": "5",
    "current_company": "Acme Corp",
    "source": "linkedin"
  }
}
```

<Tip>
  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.
</Tip>


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