Skip to content

Status and Custom Fields

Carv can act on more than the standard fields: on an application's status in your ATS, and on the custom fields your ATS keeps for candidates, vacancies and applications. Both are optional fields on the entity you already send.

Application status

status on an application is its current status in your ATS, under the name your ATS uses (for example Interview), at most 255 characters. Carv can act on it and on changes to it.

Carv keeps the last status you sent: an update without status leaves it as it is, and "status": null clears it.

Custom fields

custom_fields is an object on a candidate, a vacancy or an application:

"custom_fields": {
  "contract_type": "Temp",
  "hours_per_week": 32,
  "has_drivers_license": false,
  "languages": ["nl", "en"],
  "notes": null
}
Rule Limit
Number of fields At most 50 per entity
Keys Start with a letter, then letters, digits and underscores only; at most 64 characters
Values A string of at most 500 characters, a number, a boolean, a list of at most 20 of those, or null for no value
Numbers Integers between -9007199254740991 and 9007199254740991

A payload outside these limits is answered 422 and nothing is processed.

Send the full set of custom fields every time

Each create and update replaces the custom fields Carv holds for the entity: a custom field you leave out is removed, and leaving custom_fields out removes them all. Send the complete set with every update, also when only another field changed.

curl -X POST "https://api.carvos.io/v1/applications" \
  -H "X-API-Key: your-api-key" \
  -H "X-ATS-Client-ID: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
    "application_id": "app-789",
    "candidate_id": "candidate-123",
    "vacancy_id": "vacancy-456",
    "status": "Interview",
    "custom_fields": {
      "contract_type": "Temp",
      "hours_per_week": 32
    }
  }'
curl -X POST "https://api.carvos.io/v1/webhooks/your-ats-id" \
  -H "X-Webhook-Signature: t=1234567890,v1=abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "event": "application.updated",
    "event_id": "evt-004",
    "client_id": "acme-corp",
    "user_id": "admin-user",
    "application": {
      "application_id": "app-789",
      "candidate_id": "candidate-123",
      "vacancy_id": "vacancy-456",
      "status": "Interview",
      "custom_fields": {
        "contract_type": "Temp",
        "hours_per_week": 32
      }
    }
  }'

What comes back

Outgoing application webhooks carry status and custom_fields, and vacancy webhooks carry custom_fields, as Carv holds them. Carv holds every custom field as text, so each comes back as a string: 32 as "32", false as "false", and a list as its JSON text, "[\"nl\",\"en\"]". Candidate webhooks do not include custom fields.

An application.updated that delivers a score carries status, custom_fields, apply_date and source as null: it reports the score only.

Data Carv writes back

When Carv produces data for an application, such as a screening summary or a score, it writes it back to the application. Outgoing application webhooks carry it in carv_data, keyed by what it is:

"carv_data": {
  "summary": "Strong match: three years of forklift experience, available from May.",
  "scoring": { "score": 82, "reason": "Meets all knock-out criteria" }
}

Values keep their JSON type. carv_data is separate from custom_fields: your updates replace your custom fields but never touch carv_data, and Carv's writes never touch your custom fields. Store what you need from it; you do not send it back.

See the API Reference for Candidates, Vacancies and Applications for the full schemas.