Recruitment REST API Reference

Recruitment REST API Reference

This is the REST API reference for the WP ERP Recruitment module. It covers the available endpoints, request parameters, and response formats for managing jobs, hiring stages, and candidates.

  • Base URL: https://{your-site-domain}/wp-json/erp/v1/hrm/recruitment/
  • Protocol: HTTPS only
  • Response format: JSON, with a top-level success boolean and a data object

Authentication

Write requests (POST, PUT, DELETE) need a user with the manage_recruitment capability, authenticated with a WordPress Application Password. Read-only endpoints below don’t need authentication.

Public Endpoints

GET /jobs

Parameter Type Required Description
per_page int No Results per page. Default 10.
page int No Page number. Default 1.
status string No Filter by post status: publish, draft, pending, expired.
search_key string No Search jobs by keyword. 
curl "https://example.com/wp-json/erp/v1/hrm/recruitment/jobs?per_page=10&page=1"
{
  "success": true,
  "data": {
    "jobs": [...],
    "departments": {...}
  }
}

GET /stages

Parameter Type Required Description
job_id int No Filter stages by job. 
curl "https://example.com/wp-json/erp/v1/hrm/recruitment/stages"
{
  "success": true,
  "data": {
    "stages": [
      { "id": 1, "title": "Applied", "order": 1 }
    ]
  }
}

GET /candidates

Parameter Type Required Description
per_page int No Results per page. Default 10.
page int No Page number. Default 1.
search_key string No Search candidates by keyword.
job_id int No Filter by job.
stage_id int No Filter by hiring stage.
sort_by string No applied_date or relevance.
sort_order string No asc or desc. 
curl "https://example.com/wp-json/erp/v1/hrm/recruitment/candidates?job_id=185&sort_by=applied_date"
{
  "success": true,
  "data": {
    "candidates": [
      {
        "id": 101,
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane@example.com",
        "phone": "+123****7890",
        "job_id": 185,
        "stage_id": 1,
        "stage_title": "Applied",
        "has_resume": true,
        "applied_date": "2026-07-01"
      }
    ],
    "pagination": {...}
  }
}

GET /statuses

No parameters.

curl "https://example.com/wp-json/erp/v1/hrm/recruitment/statuses"
{
  "success": true,
  "data": {
    "statuses": [...]
  }
}

Authenticated Endpoints

POST /jobs

Parameter Type Required Description
title string Yes Job title.
description string No Job description.
department_id int No Department ID.
employment_type string No Employment type.
minimum_experience string No Minimum experience required.
remote_job string No yes or no.
location string No Job location.
vacancy int No Number of open positions.
salary string No Salary amount.
salary_type string No yearly, monthly, weekly, hourly.
expire_date string No Expiry date, format YYYY-MM-DD. 
curl -X POST "https://example.com/wp-json/erp/v1/hrm/recruitment/jobs" \
  -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{"title": "PHP Developer", "department_id": 3}'
{
  "success": true,
  "data": {
    "id": 185,
    "title": "PHP Developer",
    "status": "draft"
  }
}

GET /jobs/{id}

Parameter Type Required Description
id int Yes Job ID (in URL path). 
curl "https://example.com/wp-json/erp/v1/hrm/recruitment/jobs/185" \
  -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx"
{
  "success": true,
  "data": {
    "id": 185,
    "title": "...",
    ...
  }
}

PUT /jobs/{id}/status

Parameter Type Required Description
id int Yes Job ID (in URL path).
status string Yes publish, draft, pending, expired, closed. 
curl -X PUT "https://example.com/wp-json/erp/v1/hrm/recruitment/jobs/185/status" \
  -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{"status": "publish"}'
{
  "success": true,
  "data": {
    "id": 185,
    "status": "publish"
  }
}

POST /stages

Parameter Type Required Description
title string Yes Stage title.
order int Yes Stage order. 
curl -X POST "https://example.com/wp-json/erp/v1/hrm/recruitment/stages" \
  -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{"title": "Interview", "order": 5}'
{
  "success": true,
  "data": {
    "id": 5,
    "title": "Interview",
    "order": 5
  }
}

PUT /stages/{id}

Parameter Type Required Description
id int Yes Stage ID (in URL path).
title string No New stage title.
order int No New stage order. 
curl -X PUT "https://example.com/wp-json/erp/v1/hrm/recruitment/stages/5" \
  -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{"title": "Final Interview"}'
{
  "success": true,
  "data": {
    "id": 5,
    "title": "Final Interview",
    "order": 5
  }
}

DELETE /stages/{id}

Parameter Type Required Description
id int Yes Stage ID (in URL path). Fails if candidates are still assigned. 
curl -X DELETE "https://example.com/wp-json/erp/v1/hrm/recruitment/stages/5" \
  -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx"
{
  "success": true,
  "data": {
    "deleted": 5
  }
}

GET /candidates/{id}

Parameter Type Required Description
id int Yes Candidate ID (in URL path). 
curl "https://example.com/wp-json/erp/v1/hrm/recruitment/candidates/101" \
  -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx"
{
  "success": true,
  "data": {
    "id": 101,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "phone": "+123****7890",
    "job_id": 185,
    "stage_id": 1,
    "stage_title": "Applied",
    "status": "active",
    "applied_date": "2026-07-01",
    "resume_url": "https://example.com/resume.pdf",
    "ai_analysis": {...}
  }
}

GET /candidates/{id}/interviews

Parameter Type Required Description
id int Yes Candidate ID (in URL path). 
curl "https://example.com/wp-json/erp/v1/hrm/recruitment/candidates/101/interviews" \
  -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx"
{
  "success": true,
  "data": {
    "interviews": [...]
  }
}

GET /candidates/{id}/cv/download

Parameter Type Required Description
id int Yes Candidate ID (in URL path). 
curl "https://example.com/wp-json/erp/v1/hrm/recruitment/candidates/101/cv/download" \
  -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx" -O

Response: binary file (PDF/DOCX) with Content-Disposition: attachment.

GET /candidates/{id}/cv/preview

Parameter Type Required Description
id int Yes Candidate ID (in URL path). 
curl "https://example.com/wp-json/erp/v1/hrm/recruitment/candidates/101/cv/preview" \
  -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx"

Response: binary file with Content-Disposition: inline.

POST /candidates/{id}/shortlist

Parameter Type Required Description
id int Yes Candidate ID (in URL path).
stage_id int Yes Stage to move the candidate to. 
curl -X POST "https://example.com/wp-json/erp/v1/hrm/recruitment/candidates/101/shortlist" \
  -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{"stage_id": 3}'
{
  "success": true,
  "data": {
    "candidate_id": 101,
    "stage_id": 3
  }
}

PUT /candidates/{id}/status

Parameter Type Required Description
id int Yes Candidate ID (in URL path).
status string Yes active or rejected.
reason string Required if status=rejected Rejection reason. 
curl -X PUT "https://example.com/wp-json/erp/v1/hrm/recruitment/candidates/101/status" \
  -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{"status": "rejected", "reason": "Not a fit"}'
{
  "success": true,
  "data": {
    "candidate_id": 101,
    "status": "rejected",
    "reason": "Not a fit"
  }
}

GET /jobs/{id}/candidates

Parameter Type Required Description
id int Yes Job ID (in URL path).
per_page int No Results per page. Default 10.
page int No Page number. Default 1. 
curl "https://example.com/wp-json/erp/v1/hrm/recruitment/jobs/185/candidates" \
  -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx"
{
  "success": true,
  "data": {
    "candidates": [...],
    "pagination": {...}
  }
}

GET /stages/{id}/candidates

Parameter Type Required Description
id int Yes Stage ID (in URL path).
per_page int No Results per page. Default 10.
page int No Page number. Default 1. 
curl "https://example.com/wp-json/erp/v1/hrm/recruitment/stages/5/candidates" \
  -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx"
{
  "success": true,
  "data": {
    "candidates": [...],
    "pagination": {...}
  }
}

Error Codes

Code Meaning
400 Missing or invalid parameters
401 Invalid or missing credentials
403 User lacks the manage_recruitment capability
404 Resource does not exist
409 Duplicate stage title, or stage still has candidates assigned
500 Unexpected server-side failure

Still stuck? How can we help?

Leave a Reply

Your email address will not be published. Required fields are marked *