Data and account

Workspaces and account

List, create, rename and erase the workspaces that keep each customer apart, read the credits left, and check that the API is up.

Workspaces

A workspace holds the resumes, jobs and scores of one of your customers. Every call names it in the HireLayer-Workspace header, default when the header is absent, and creates it on first use: see Workspaces. These endpoints list the workspaces, give one a display name or impose the no-storage mode on it, and erase one with everything it holds. They are free.

List workspaces

GET/api/v4/workspaces

default first, then the others, oldest first. Free.

Authentication: X-API-Key header
Billing: Free
Client timeout: Client timeout ≥ 30 s

Response

200The workspaces.

dataobject[]
›Show 6 child fieldsHide child fields
- workspace_idstring
- namestring | null
- do_not_store_databoolean
  Every call of this workspace runs without storage.
- jobs_countinteger
  ≥ 0
- resumes_countinteger
  ≥ 0
- created_atstring (date-time) | null

Errors

401
missing_api_keyThe X-API-Key header is missing.
No X-API-Key header.
Fix, then retry
401
missing_api_keyAuthorization: Bearer is not accepted: send the key in the X-API-Key header.
The key sent as Authorization: Bearer: it goes in X-API-Key.
Fix, then retry
401
missing_api_keyThe key goes in the X-API-Key header, not in the URL.
The key sent in the URL: it goes in X-API-Key.
Fix, then retry
401
invalid_api_keyInvalid API key: it is unknown, malformed or revoked.
The key is unknown, malformed or revoked.
Fix, then retry
500
internal_errorInternal error: retry later. If it persists, contact support with the request_id.
An unexpected error.
Retry with backoff
502
internal_errorThe service could not be reached: retry later.
The service could not be reached.
Retry with backoff
503
internal_errorThe credit service is briefly unavailable: retry in a second.
The credit service is briefly unavailable. Header Retry-After: <seconds>.
Retry with backoff
504
internal_errorThe service did not answer in time. The change may still be applied: read it before sending it again.
No answer in time.
Retry with backoff

Request

curl https://hirelayer.co/api/v4/workspaces \
  -H "X-API-Key: $HIRELAYER_API_KEY"

import os

import requests

response = requests.get(
    "https://hirelayer.co/api/v4/workspaces",
    headers={"X-API-Key": os.environ["HIRELAYER_API_KEY"]},
    timeout=30,
)
response.raise_for_status()

data = response.json()
print(data["data"])

const response = await fetch('https://hirelayer.co/api/v4/workspaces', {
  headers: {
    'X-API-Key': process.env.HIRELAYER_API_KEY!,
  },
  signal: AbortSignal.timeout(30_000),
})

if (!response.ok) {
  throw new Error(`HireLayer ${response.status}: ${await response.text()}`)
}

const data = await response.json()
console.log(data.data)

Response

{
  "error": {
    "code": "missing_api_key",
    "message": "The X-API-Key header is missing.",
    "doc_url": "https://hirelayer.co/api-docs/errors#missing_api_key"
  },
  "request_id": "6f1c2a4e-1d2b-4c3a-9e8f-0a1b2c3d4e5f"
}

Create or rename a workspace

PUT/api/v4/workspaces/{workspace_id}

Creates a workspace for one of your customers, gives it a new display name, or imposes the no-storage mode on it. Its id never changes. Free.

`do_not_store_data: false` lifts it; nothing processed meanwhile was kept.
A field left out keeps its current value.

Authentication: X-API-Key header
Billing: Free
Client timeout: Client timeout ≥ 30 s

Path parameters

workspace_idstringrequired
Letters, digits and . _ : ~ -, up to 200 characters.

Request body

Content type application/json

namestring
1–200 characters
do_not_store_databoolean
Enterprise plan only. Impose the no-storage mode on every call of this workspace.

Response

200Renamed.

workspace_idstring
namestring | null
do_not_store_databoolean
Every call of this workspace runs without storage.
jobs_countinteger
≥ 0
resumes_countinteger
≥ 0
created_atstring (date-time) | null

201Created.

workspace_idstring
namestring | null
do_not_store_databoolean
Every call of this workspace runs without storage.
jobs_countinteger
≥ 0
resumes_countinteger
≥ 0
created_atstring (date-time) | null

Errors

400
invalid_requestname must be 200 characters or less.
param: name. name over 200 characters.
Fix, then retry
400
invalid_requestThe default workspace always exists and has no name to set.
param: workspace_id. A name for the workspace default.
Fix, then retry
400
invalid_requestdo_not_store_data must be true or false.
param: do_not_store_data. do_not_store_data is not a boolean.
Fix, then retry
400
invalid_requestworkspace_id must contain letters, digits and . _ : ~ -, up to 200 characters.
param: workspace_id. workspace_id in the path is not a valid id.
Fix, then retry
400
invalid_requestUnknown field label.
param: label. A field the call does not take.
Fix, then retry
400
invalid_requestThe request body is not valid JSON.
The body is not valid JSON, not an object, or not sent as application/json.
Fix, then retry
401
missing_api_keyThe X-API-Key header is missing.
No X-API-Key header.
Fix, then retry
401
missing_api_keyAuthorization: Bearer is not accepted: send the key in the X-API-Key header.
The key sent as Authorization: Bearer: it goes in X-API-Key.
Fix, then retry
401
missing_api_keyThe key goes in the X-API-Key header, not in the URL.
The key sent in the URL: it goes in X-API-Key.
Fix, then retry
401
invalid_api_keyInvalid API key: it is unknown, malformed or revoked.
The key is unknown, malformed or revoked.
Fix, then retry
403
enterprise_plan_requireddo_not_store_data is available on the Enterprise plan only. Nothing was processed or billed.
param: do_not_store_data. do_not_store_data: true below the Enterprise plan.
Do not retry
413
payload_too_largeThe request body must be 10 MB or less.
The body is over 10 MB.
Fix, then retry
500
internal_errorInternal error: retry later. If it persists, contact support with the request_id.
An unexpected error.
Retry with backoff
502
internal_errorThe service could not be reached: retry later.
The service could not be reached.
Retry with backoff
503
internal_errorThe credit service is briefly unavailable: retry in a second.
The credit service is briefly unavailable. Header Retry-After: <seconds>.
Retry with backoff
504
internal_errorThe service did not answer in time. The change may still be applied: read it before sending it again.
No answer in time.
Retry with backoff

Behavior

do_not_store_data: true (Enterprise plan only, else 403 enterprise_plan_required): every later call sent with this workspace runs as with do_not_store_data=true, whatever the call sends; both searches, and the writes that would store something in it (PUT /resumes/{application_id}, PUT /jobs/{job_id}, POST /jobs/{job_id}/criteria, PATCH /jobs/{job_id}/criteria/{criterion_id}), answer 400 storage_required. What the workspace already holds stays until you erase it (DELETE /workspaces/{workspace_id}). Calls sent without the HireLayer-Workspace header go to default: they are covered only when default itself is set this way.

Request

curl -X PUT https://hirelayer.co/api/v4/workspaces/acme \
  -H "X-API-Key: $HIRELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme"
  }'

import os

import requests

response = requests.put(
    "https://hirelayer.co/api/v4/workspaces/acme",
    headers={"X-API-Key": os.environ["HIRELAYER_API_KEY"]},
    json={
        "name": "Acme",
    },
    timeout=30,
)
response.raise_for_status()

data = response.json()
print(data["workspace_id"])

const response = await fetch('https://hirelayer.co/api/v4/workspaces/acme', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.HIRELAYER_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Acme',
  }),
  signal: AbortSignal.timeout(30_000),
})

if (!response.ok) {
  throw new Error(`HireLayer ${response.status}: ${await response.text()}`)
}

const data = await response.json()
console.log(data.workspace_id)

Response

{
  "error": {
    "code": "invalid_request",
    "message": "name must be 200 characters or less.",
    "param": "name",
    "doc_url": "https://hirelayer.co/api-docs/errors#invalid_request"
  },
  "request_id": "6f1c2a4e-1d2b-4c3a-9e8f-0a1b2c3d4e5f"
}

Erase a workspace

DELETE/api/v4/workspaces/{workspace_id}

Erases every job, resume, file and score of the workspace, for example when your customer leaves. Free.

Authentication: X-API-Key header
Billing: Free
Client timeout: Client timeout ≥ 60 s

Path parameters

workspace_idstringrequired
Letters, digits and . _ : ~ -, up to 200 characters.

Response

204Erased.

Errors

400
invalid_requestworkspace_id must contain letters, digits and . _ : ~ -, up to 200 characters.
param: workspace_id. workspace_id in the path is not a valid id.
Fix, then retry
401
missing_api_keyThe X-API-Key header is missing.
No X-API-Key header.
Fix, then retry
401
missing_api_keyAuthorization: Bearer is not accepted: send the key in the X-API-Key header.
The key sent as Authorization: Bearer: it goes in X-API-Key.
Fix, then retry
401
missing_api_keyThe key goes in the X-API-Key header, not in the URL.
The key sent in the URL: it goes in X-API-Key.
Fix, then retry
401
invalid_api_keyInvalid API key: it is unknown, malformed or revoked.
The key is unknown, malformed or revoked.
Fix, then retry
404
not_foundNo workspace acme: it was never created, and nothing was ever stored in it.
param: workspace_id. The workspace was never created or used.
Do not retry
500
internal_errorInternal error: retry later. If it persists, contact support with the request_id.
An unexpected error.
Retry with backoff
502
internal_errorThe service could not be reached: retry later.
The service could not be reached.
Retry with backoff
503
internal_errorThe erasure could not be finished: send the same call again to finish it.
An erasure could not be finished: the same call finishes it. Header Retry-After: <seconds>.
Retry with backoff
504
internal_errorThe service did not answer in time. The change may still be applied: read it before sending it again.
No answer in time.
Retry with backoff

Request

curl -X DELETE https://hirelayer.co/api/v4/workspaces/acme \
  -H "X-API-Key: $HIRELAYER_API_KEY"

import os

import requests

response = requests.delete(
    "https://hirelayer.co/api/v4/workspaces/acme",
    headers={"X-API-Key": os.environ["HIRELAYER_API_KEY"]},
    timeout=60,
)
response.raise_for_status()
print(response.status_code)

const response = await fetch('https://hirelayer.co/api/v4/workspaces/acme', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.HIRELAYER_API_KEY!,
  },
  signal: AbortSignal.timeout(60_000),
})

if (!response.ok) {
  throw new Error(`HireLayer ${response.status}: ${await response.text()}`)
}

console.log(response.status)

Response

{
  "error": {
    "code": "invalid_request",
    "message": "workspace_id must contain letters, digits and . _ : ~ -, up to 200 characters.",
    "param": "workspace_id",
    "doc_url": "https://hirelayer.co/api-docs/errors#invalid_request"
  },
  "request_id": "6f1c2a4e-1d2b-4c3a-9e8f-0a1b2c3d4e5f"
}

Account and status

GET /account gives the plan and the credits left of the key’s account. GET /health answers without a key, for a monitoring probe. Both are free.

Get the account

GET/api/v4/account

The plan and the credits left of the key's account. Free.

Authentication: X-API-Key header
Billing: Free
Client timeout: Client timeout ≥ 30 s

Response

200The account.

accountobject
›Show 2 child fieldsHide child fields
- emailstring | null
- planstring
  "free""starter""scale""pay_as_you_go""enterprise"
creditsobject
›Show 2 child fieldsHide child fields
- availableinteger | null
  null on an unlimited plan.
- unlimitedboolean

Errors

401
missing_api_keyThe X-API-Key header is missing.
No X-API-Key header.
Fix, then retry
401
missing_api_keyAuthorization: Bearer is not accepted: send the key in the X-API-Key header.
The key sent as Authorization: Bearer: it goes in X-API-Key.
Fix, then retry
401
missing_api_keyThe key goes in the X-API-Key header, not in the URL.
The key sent in the URL: it goes in X-API-Key.
Fix, then retry
401
invalid_api_keyInvalid API key: it is unknown, malformed or revoked.
The key is unknown, malformed or revoked.
Fix, then retry
500
internal_errorInternal error: retry later. If it persists, contact support with the request_id.
An unexpected error.
Retry with backoff
502
internal_errorThe service could not be reached: retry later.
The service could not be reached.
Retry with backoff
503
internal_errorThe credit service is briefly unavailable: retry in a second.
The credit service is briefly unavailable. Header Retry-After: <seconds>.
Retry with backoff
504
internal_errorThe service did not answer in time. The change may still be applied: read it before sending it again.
No answer in time.
Retry with backoff

Request

curl https://hirelayer.co/api/v4/account \
  -H "X-API-Key: $HIRELAYER_API_KEY"

import os

import requests

response = requests.get(
    "https://hirelayer.co/api/v4/account",
    headers={"X-API-Key": os.environ["HIRELAYER_API_KEY"]},
    timeout=30,
)
response.raise_for_status()

data = response.json()
print(data["credits"])

const response = await fetch('https://hirelayer.co/api/v4/account', {
  headers: {
    'X-API-Key': process.env.HIRELAYER_API_KEY!,
  },
  signal: AbortSignal.timeout(30_000),
})

if (!response.ok) {
  throw new Error(`HireLayer ${response.status}: ${await response.text()}`)
}

const data = await response.json()
console.log(data.credits)

Response

{
  "account": {
    "email": "dev@example.com",
    "plan": "scale"
  },
  "credits": {
    "available": 4210,
    "unlimited": false
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "The X-API-Key header is missing.",
    "doc_url": "https://hirelayer.co/api-docs/errors#missing_api_key"
  },
  "request_id": "6f1c2a4e-1d2b-4c3a-9e8f-0a1b2c3d4e5f"
}

Service health

GET/api/v4/health

No key needed. Free.

Authentication: No API key
Billing: Free
Client timeout: Client timeout ≥ 10 s

Response

200The service answers.

statusstring
"healthy"
servicestring
timestampstring (date-time)

Request

curl https://hirelayer.co/api/v4/health

import requests

response = requests.get(
    "https://hirelayer.co/api/v4/health",
    timeout=10,
)
response.raise_for_status()

data = response.json()
print(data["status"])

const response = await fetch('https://hirelayer.co/api/v4/health', {
  signal: AbortSignal.timeout(10_000),
})

if (!response.ok) {
  throw new Error(`HireLayer ${response.status}: ${await response.text()}`)
}

const data = await response.json()
console.log(data.status)

Response

{
  "status": "healthy",
  "service": "hirelayer-api",
  "timestamp": "2026-10-27T09:00:00Z"
}