API Reference

POST Create Candidate

v1Updated 2026-03-07

Create candidate

POST/api/v1/public/:tenant_slug/candidates

Header	Required	Description
Authorization	yes	`Bearer <API_KEY>`
Idempotency-Key	recommended	Safe retry key.

Body field	Type	Required
full_name	string	yes
headline	string	no
company	string	no
location_id	integer	no
recruiter_id	integer	no
candidate_source_id	integer	no

Request


curl -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Idempotency-Key: cand-create-001" \
  -H "Content-Type: application/json" \
  -d '{"full_name":"Ana Novak","headline":"QA Engineer"}' \
  "http://localhost:3333/api/v1/public/agado-ats/candidates"

201 Response


{ "data": { "id": 504, "full_name": "Ana Novak", "headline": "QA Engineer" } }

400 Response


{
  "error": {
    "code": "bad_request",
    "message": "Validation failed for request payload",
    "request_id": "req_123"
  }
}

500 Response


{
  "error": {
    "code": "internal_error",
    "message": "Unexpected server error",
    "request_id": "req_500"
  }
}