Jobs API (dealer)

Create, update, publish, and unpublish job listings via the bearer-authenticated API.

Overview

The same GET /api/v1/jobs path behaves differently depending on authentication:

Auth	Behaviour
None	Public marketplace search — published jobs only
Bearer	Your organisation's jobs — including drafts

Dealer write routes:

Method	Path	Purpose
`GET`	`/api/v1/jobs`	List org jobs (optional `published=true/false`)
`POST`	`/api/v1/jobs`	Create a draft job
`GET`	`/api/v1/jobs/{id}`	Get org job (any status)
`PATCH`	`/api/v1/jobs/{id}`	Update a job
`POST`	`/api/v1/jobs/{id}/publish`	Publish
`POST`	`/api/v1/jobs/{id}/unpublish`	Unpublish / close

Public unauthenticated read is documented in Public read.

Pass organisationId when the user belongs to multiple organisations — see Accounts.

Plan gates

Creating and publishing jobs requires a plan with the job board enabled (canPostJobs). Active published job count is capped by your plan's job limit. Attempts without permission return 403.

List org jobs (bearer)

curl "https://hgvtraders.com/api/v1/jobs?published=false&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Drafts only:

curl "https://hgvtraders.com/api/v1/jobs?organisationId=clorg123abc&published=false" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "data": {
    "jobs": [
      {
        "id": "cljob789ghi",
        "slug": "class-1-hgv-driver-manchester",
        "title": "Class 1 HGV Driver",
        "department": "Transport",
        "contractType": "Permanent",
        "status": "DRAFT",
        "salaryType": "RANGE",
        "salaryFrom": 3200000,
        "salaryTo": 3800000,
        "locationCity": "Manchester",
        "createdAt": "2024-06-01T09:00:00.000Z"
      }
    ],
    "total": 5,
    "page": 1,
    "pages": 1
  }
}

Query parameters: published (true / false), page, limit (max 100). See Pagination.

Salaries are stored as integer pence (e.g. £32,000/year = 3200000). Option fields such as department and contractType must match values configured on the platform (same as the dashboard job form).

curl -X POST "https://hgvtraders.com/api/v1/jobs" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organisationId": "clorg123abc",
    "title": "Class 1 HGV Driver",
    "department": "Transport",
    "contractType": "Permanent",
    "salaryType": "RANGE",
    "salaryFrom": 3200000,
    "salaryTo": 3800000,
    "locationCity": "Manchester",
    "locationPostcode": "M1 1AA",
    "remote": false,
    "aboutCompany": "Family-run haulage firm established 1985.",
    "closingDate": "2024-07-31"
  }'

Response (201 Created):

{
  "data": {
    "id": "cljob789ghi",
    "slug": "class-1-hgv-driver-manchester",
    "title": "Class 1 HGV Driver",
    "status": "DRAFT"
  }
}

Create fields

Field	Required	Notes
`organisationId`	When multi-org
`title`	Yes	Min 3 characters
`department`	Yes	Platform-configured option
`contractType`	Yes	Platform-configured option
`salaryType`	Yes	`RANGE`, `FROM`, `UP_TO`, `COMPETITIVE`, `DOE`
`salaryFrom`, `salaryTo`	Depends on type	Pence; required for `RANGE`
`locationCity`, `locationPostcode`	Optional
`remote`	Optional	Boolean
`aboutCompany`, `closingDate`	Optional
`externalLink`, `contactEmail`	Optional
`categoryId`, `manufacturerId`	Optional	CUID references
`experienceLevel`, `recruiterType`	Optional	Platform-configured options

Get a single job

curl "https://hgvtraders.com/api/v1/jobs/cljob789ghi?organisationId=clorg123abc" \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns the full job record for your organisation regardless of publish status. 404 if not found or wrong org.

Update a job

Send at least one field besides organisationId:

curl -X PATCH "https://hgvtraders.com/api/v1/jobs/cljob789ghi" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organisationId": "clorg123abc",
    "salaryTo": 4000000,
    "closingDate": "2024-08-15"
  }'

{
  "data": {
    "id": "cljob789ghi",
    "title": "Class 1 HGV Driver",
    "salaryTo": 4000000,
    "closingDate": "2024-08-15T00:00:00.000Z"
  }
}

Publish and unpublish

curl -X POST "https://hgvtraders.com/api/v1/jobs/cljob789ghi/publish" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "organisationId": "clorg123abc" }'

Success:

{ "data": { "id": "cljob789ghi" } }

Unpublish with POST /api/v1/jobs/{id}/unpublish — same body shape. Published jobs appear on the public GET /api/v1/jobs marketplace search.

Typical integration flow

Create draft — POST /api/v1/jobs
Review in your system — GET /api/v1/jobs/{id}
Publish — POST …/publish when ready
Update — PATCH for salary or closing date changes
Close — POST …/unpublish when filled

Rate limits and errors

Write routes: 120 requests/minute per user. See Rate limits and Errors.

Status	Typical cause
400	Invalid body or missing `organisationId` for multi-org users
403	Plan does not include job board, or job limit reached on publish
404	Job not found or wrong organisation
429	Write rate limit exceeded

On this page