🎯 Purpose

Additional Fields let you define account-level, typed candidate attributes (e.g. score, source, is_referred) and reuse them across candidate ingestion, bulk invite, interview detail views, and API filtering.

🛠️ Supported Field Types

To ensure data integrity and proper filtering, each field must be assigned a specific type:

Type Description
text Free-form string values (e.g. "LinkedIn", "Referral")
number Numeric values (e.g. 85, 42)
boolean True/false values (e.g. true, false)

📥 Ingesting Data into Additional Fields

To successfully populate these fields during candidate onboarding, naming must be exact across all ingestion methods.

1. Programmatic Ingestion via API

When using the Ingestion API, include a metadata object in your payload. All custom additional fields must be nested inside metadata using the exact keys defined in your settings.

Example Payload:

curl -X POST "<https://api.interviewflowai.com/api/external/ingest/candidates>" \\
  -H "Content-Type: application/json" \\
  -H "X-API-KEY: your_api_key_here" \\
  -d '{
    "status": "shortlisted",
    "jobId": "304c0cfb-324f-4b2c-ac89-c93725c00399",
    "data": [
      {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "additionalFields": {
          "Manual Score": 72,
          "isSynced": "true"
        },
        "metadata": {
          "External ID": "candidate_12345",
          "Phone": "+1-555-123-4567"
        }
      }
    ]
  }'

2. Bulk Invite via CSV

When importing candidates via CSV, column headers must match the Additional Field Key exactly as defined in your settings.

Rule Example
Column header = field key If the key is source, the CSV column must be named source
Auto-mapping The system uses headers to automatically map CSV values into the correct metadata fields

🔍 Usage & Visibility

Once data is ingested, custom fields become a powerful tool across your hiring workflow:

Where How It's Used
Interview Detail Views Custom fields appear directly on the candidate profile for quick reference.
API Filtering Use additionalFields in Fetch API calls to slice your data.