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.