Recruitment REST API

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", "created_by": 1, "created_at": "2026-06-15", "candidate_count": 0 }
    ]
  }
}

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": "[email protected]",
        "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.

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"}'

{
  "message": "Stage created successfully",
  "stage": {
    "id": 5,
    "title": "Interview",
    "created_by": 1,
    "created_at": "2026-07-01",
    "candidate_count": 0
  }
}

PUT /stages/{id}

Parameter	Type	Required	Description
`id`	int	Yes	Stage ID (in URL path).
`title`	string	No	New stage title.

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"
  }
}

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"

{
  "message": "Stage deleted successfully",
  "stage_id": 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": "[email protected]",
    "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: JSON object with cv_files array containing id, url, filename, and type fields.

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).

This endpoint takes no body parameters. It marks the candidate as shortlisted for the current job. To move a candidate to a different stage, use POST /candidates/{id}/stage with stage_id.

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_name`	string	Yes	`nostatus`, `rejected`, `withdrawn`, or `decline_offer`.

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?

HRM Pro

Recruitment REST API

Authentication

Public Endpoints

GET /jobs

GET /stages

GET /candidates

GET /statuses

Authenticated Endpoints

POST /jobs

GET /jobs/{id}

PUT /jobs/{id}/status

POST /stages

PUT /stages/{id}

DELETE /stages/{id}

GET /candidates/{id}

GET /candidates/{id}/interviews

GET /candidates/{id}/cv/download

GET /candidates/{id}/cv/preview

POST /candidates/{id}/shortlist

PUT /candidates/{id}/status

GET /jobs/{id}/candidates

GET /stages/{id}/candidates

Error Codes

Was this article helpful to you?

Products

Company

Resources

Documentation

How can we help you?

HRM Pro

Authentication

Public Endpoints

GET /jobs

GET /stages

GET /candidates

GET /statuses

Authenticated Endpoints

POST /jobs

GET /jobs/{id}

PUT /jobs/{id}/status

POST /stages

PUT /stages/{id}

DELETE /stages/{id}

GET /candidates/{id}

GET /candidates/{id}/interviews

GET /candidates/{id}/cv/download

GET /candidates/{id}/cv/preview

POST /candidates/{id}/shortlist

PUT /candidates/{id}/status

GET /jobs/{id}/candidates

GET /stages/{id}/candidates

Error Codes

Was this article helpful to you?

How can we help?

Products

Company

Resources

We received your query