Docs

Search the docs

Guides, sections and API endpoints

API reference

Candidates

The people you're considering, one per person across all your jobs, with their resumes.

List candidates

get/candidates

Needs the candidates:read scope

Newest first. q matches part of the name or email.

Query parameters

  • qstring
    Matches part of the name or email.
  • limitinteger
    How many to return.
    min 1max 100Default 50
  • offsetinteger
    How many to skip. See Pagination.
    Default 0

Returns 200

A page of objects like this one, in items, with the total count. Pagination

  • iduuid
  • created_atdatetime
  • updated_atdatetimenullable
  • first_namestring
  • last_namestring
  • emailstringnullable
    Unique within the organization.
  • phonestringnullable
  • locationstringnullable
  • linkedin_urlstringnullable
  • sourcestringnullable
    Where they came from: "careers_page" for the job board, or whatever was set ("referral", "linkedin", ...).
  • resume_urlstringnullable
    Their resume (PDF); null when there's none.

Errors

  • 401The key is wrong, expired or revoked (api_key_required when missing) invalid_api_key
  • 403The key isn't allowed candidates:read insufficient_scope
  • 422A parameter or field doesn't validate missing, uuid_parsing, …
curl "https://api.hirehappy.io/v1/candidates?q=ribeiro" \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY"
Response 200
{
  "items": [
    {
      "id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
      "created_at": "2026-10-26T09:30:00Z",
      "updated_at": "2026-10-27T14:05:00Z",
      "first_name": "Ana",
      "last_name": "Ribeiro",
      "email": "[email protected]",
      "phone": "+49 30 901820",
      "location": "Lisbon, Portugal",
      "linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
      "source": "referral",
      "resume_url": "https://files.hirehappy.io/0b6f3c2e/resume-ana-ribeiro.pdf"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Create a candidate

post/candidates

Needs the candidates:write scope

Add a candidate, to put forward for a job with POST /applications. 409 when another candidate has the email.

Bodyapplication/json

  • first_namestringRequired
    min 1 charsmax 100 chars
  • last_namestringRequired
    min 1 charsmax 100 chars
  • emailemailnullable
    409 when another candidate has it.
  • phonestringnullable
    max 50 chars
  • locationstringnullable
    max 200 chars
  • linkedin_urlstringnullable
    max 500 chars
  • sourcestringnullable
    Where they came from, in your own words: referral, linkedin, agency, ...
    max 100 chars

Returns 201

  • iduuid
  • created_atdatetime
  • updated_atdatetimenullable
  • first_namestring
  • last_namestring
  • emailstringnullable
    Unique within the organization.
  • phonestringnullable
  • locationstringnullable
  • linkedin_urlstringnullable
  • sourcestringnullable
    Where they came from: "careers_page" for the job board, or whatever was set ("referral", "linkedin", ...).
  • resume_urlstringnullable
    Their resume (PDF); null when there's none.

Errors

  • 400A value is out of place validation_error
  • 401The key is wrong, expired or revoked (api_key_required when missing) invalid_api_key
  • 403The key isn't allowed candidates:write insufficient_scope
  • 409When another candidate has the email conflict
  • 422A parameter or field doesn't validate missing, uuid_parsing, …
curl -X POST "https://api.hirehappy.io/v1/candidates" \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Ana",
    "last_name": "Ribeiro",
    "email": "[email protected]",
    "linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
    "source": "referral"
  }'
Response 201
{
  "id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
  "created_at": "2026-10-26T09:30:00Z",
  "updated_at": "2026-10-27T14:05:00Z",
  "first_name": "Ana",
  "last_name": "Ribeiro",
  "email": "[email protected]",
  "phone": "+49 30 901820",
  "location": "Lisbon, Portugal",
  "linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
  "source": "referral",
  "resume_url": "https://files.hirehappy.io/0b6f3c2e/resume-ana-ribeiro.pdf"
}

Retrieve a candidate

get/candidates/{candidate_id}

Needs the candidates:read scope

Path parameters

  • candidate_iduuidRequired

Returns 200

  • iduuid
  • created_atdatetime
  • updated_atdatetimenullable
  • first_namestring
  • last_namestring
  • emailstringnullable
    Unique within the organization.
  • phonestringnullable
  • locationstringnullable
  • linkedin_urlstringnullable
  • sourcestringnullable
    Where they came from: "careers_page" for the job board, or whatever was set ("referral", "linkedin", ...).
  • resume_urlstringnullable
    Their resume (PDF); null when there's none.

Errors

  • 401The key is wrong, expired or revoked (api_key_required when missing) invalid_api_key
  • 403The key isn't allowed candidates:read insufficient_scope
  • 404It isn't there, or belongs to another organization resource_not_found
  • 422A parameter or field doesn't validate missing, uuid_parsing, …
curl "https://api.hirehappy.io/v1/candidates/c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f" \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY"
Response 200
{
  "id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
  "created_at": "2026-10-26T09:30:00Z",
  "updated_at": "2026-10-27T14:05:00Z",
  "first_name": "Ana",
  "last_name": "Ribeiro",
  "email": "[email protected]",
  "phone": "+49 30 901820",
  "location": "Lisbon, Portugal",
  "linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
  "source": "referral",
  "resume_url": "https://files.hirehappy.io/0b6f3c2e/resume-ana-ribeiro.pdf"
}

Update a candidate

patch/candidates/{candidate_id}

Needs the candidates:write scope

Path parameters

  • candidate_iduuidRequired

Bodyapplication/json

  • first_namestringnullable
    min 1 charsmax 100 chars
  • last_namestringnullable
    min 1 charsmax 100 chars
  • emailemailnullable
  • phonestringnullable
    max 50 chars
  • locationstringnullable
    max 200 chars
  • linkedin_urlstringnullable
    max 500 chars
  • sourcestringnullable
    max 100 chars

Returns 200

  • iduuid
  • created_atdatetime
  • updated_atdatetimenullable
  • first_namestring
  • last_namestring
  • emailstringnullable
    Unique within the organization.
  • phonestringnullable
  • locationstringnullable
  • linkedin_urlstringnullable
  • sourcestringnullable
    Where they came from: "careers_page" for the job board, or whatever was set ("referral", "linkedin", ...).
  • resume_urlstringnullable
    Their resume (PDF); null when there's none.

Errors

  • 400A value is out of place validation_error
  • 401The key is wrong, expired or revoked (api_key_required when missing) invalid_api_key
  • 403The key isn't allowed candidates:write insufficient_scope
  • 404It isn't there, or belongs to another organization resource_not_found
  • 422A parameter or field doesn't validate missing, uuid_parsing, …
curl -X PATCH "https://api.hirehappy.io/v1/candidates/c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f" \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+49 30 901820",
    "location": "Lisbon, Portugal"
  }'
Response 200
{
  "id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
  "created_at": "2026-10-26T09:30:00Z",
  "updated_at": "2026-10-27T14:05:00Z",
  "first_name": "Ana",
  "last_name": "Ribeiro",
  "email": "[email protected]",
  "phone": "+49 30 901820",
  "location": "Lisbon, Portugal",
  "linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
  "source": "referral",
  "resume_url": "https://files.hirehappy.io/0b6f3c2e/resume-ana-ribeiro.pdf"
}

Delete a candidate

del/candidates/{candidate_id}

Needs the candidates:write scope

Delete a candidate for good, with their applications and notes (a request to erase their data, say).

Path parameters

  • candidate_iduuidRequired

Returns 204

No content.

Errors

  • 401The key is wrong, expired or revoked (api_key_required when missing) invalid_api_key
  • 403The key isn't allowed candidates:write insufficient_scope
  • 404It isn't there, or belongs to another organization resource_not_found
  • 422A parameter or field doesn't validate missing, uuid_parsing, …
curl -X DELETE "https://api.hirehappy.io/v1/candidates/c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f" \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY"

Upload a candidate's resume

put/candidates/{candidate_id}/resume

Needs the candidates:write scope

Set the candidate's resume, a PDF sent as multipart/form-data (resume), replacing any they had. It's searchable at once; scorecards use it from the next scoring on.

Path parameters

  • candidate_iduuidRequired

Bodymultipart/form-data

  • resumestringRequired

Returns 200

  • iduuid
  • created_atdatetime
  • updated_atdatetimenullable
  • first_namestring
  • last_namestring
  • emailstringnullable
    Unique within the organization.
  • phonestringnullable
  • locationstringnullable
  • linkedin_urlstringnullable
  • sourcestringnullable
    Where they came from: "careers_page" for the job board, or whatever was set ("referral", "linkedin", ...).
  • resume_urlstringnullable
    Their resume (PDF); null when there's none.

Errors

  • 400A value is out of place validation_error
  • 401The key is wrong, expired or revoked (api_key_required when missing) invalid_api_key
  • 403The key isn't allowed candidates:write insufficient_scope
  • 404It isn't there, or belongs to another organization resource_not_found
  • 422A parameter or field doesn't validate missing, uuid_parsing, …
curl -X PUT "https://api.hirehappy.io/v1/candidates/c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f/resume" \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY" \
  -F "[email protected];type=application/pdf"
Response 200
{
  "id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
  "created_at": "2026-10-26T09:30:00Z",
  "updated_at": "2026-10-27T14:05:00Z",
  "first_name": "Ana",
  "last_name": "Ribeiro",
  "email": "[email protected]",
  "phone": "+49 30 901820",
  "location": "Lisbon, Portugal",
  "linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
  "source": "referral",
  "resume_url": "https://files.hirehappy.io/0b6f3c2e/resume-ana-ribeiro.pdf"
}