CAREER UNIFIED PARTNER API

Build connected recruitment experiences

Publish opportunities, receive structured applications, and keep hiring systems in sync through one secure API built for South African recruitment.

Make your first request View OpenAPI spec

Choose your integration path

Start with the outcome you need. Each path leads to the relevant guide and reference.

Distribute opportunitiesRead active jobs and bursaries for approved discovery experiences. Publish from your ATSCreate, update, and close vacancies without duplicate administration. Synchronise applicationsRetrieve Direct Apply submissions and keep candidate stages current. React to recruitment eventsReceive signed notifications when jobs or applications change.

Designed for reliable partner workflows

Organisation isolation

Every key is linked to one approved recruiter organisation.

Narrow permissions

Scopes grant only the actions each integration needs.

Safe retries

Idempotency prevents duplicate jobs and duplicate credit usage.

Signed events

Webhook signatures let your system verify every delivery.

List active jobs

curl "https://careerunified.com/api/v1/jobs?limit=3"

const response = await fetch(
  'https://careerunified.com/api/v1/jobs?limit=3'
)

const { data } = await response.json()

import requests

response = requests.get(
    "https://careerunified.com/api/v1/jobs",
    params={"limit": 3},
)
jobs = response.json()["data"]

Response

{
  "data": [
    {
      "id": "job_8f4c...",
      "title": "Junior Financial Analyst",
      "location": {
        "display": "Johannesburg"
      }
    }
  ],
  "meta": {
    "hasMore": true,
    "nextCursor": "eyJ2Ijox..."
  }
}

GET STARTED

Make your first request

Read public opportunities immediately, then add an approved partner key when your integration needs to publish or manage recruitment data.

1

Use the versioned base URL

All current API requests begin with the same HTTPS base URL.

https://careerunified.com/api/v1

2

Test public discovery

The jobs and bursaries discovery endpoints do not require authentication.

Terminal

curl "https://careerunified.com/api/v1/jobs?limit=5"

3

Add your partner key

Approved organisations receive a scoped API key. Keep it on your server and send it with each protected request.

Authenticated request

curl "https://careerunified.com/api/v1/webhooks" \
  -H "X-API-Key: $CAREER_UNIFIED_API_KEY"

4

Prepare for production

Use a secret manager, handle pagination, respect Retry-After, and verify every webhook signature before processing its payload.

NextAuthentication

SECURITY

Authentication

Partner endpoints use organisation-bound API keys. Public discovery endpoints can be read without a key.

Keep keys on your server

Never expose a partner key in browser JavaScript, mobile applications, source control, Sanity, or public environment variables.

Send an API key

Use the X-API-Key header. Bearer authentication is also supported for server integrations that standardise on the Authorization header.

Recommended

X-API-Key: cu_live_<client-id>.<secret>

Use cu_test_ sandbox keys for pilot testing and cu_live_ keys for approved production traffic.

Scopes

Each API client receives only the permissions required for its integration.

Scope	Allows
`jobs:read`	Reserved protected listing integrations
`jobs:write`	Create, update, and close organisation jobs
`applications:read`	Read applications for organisation jobs
`applications:write`	Move applications through recruitment stages
`webhooks:manage`	Create, inspect, and disable webhook endpoints

Organisation isolation

An API client is permanently linked to its approved recruiter organisation. Supplying another recruiter or company identifier does not grant access to that organisation's data.

Key lifecycle

Keys are displayed once when created or rotated. Career Unified administrators can create, rotate, revoke, review usage, download usage reports, and monitor quota alerts in the protected API admin console. Revocation does not affect recruiter login credentials.

Quotas and alerts

Each API client has a per-minute limit and a monthly quota linked to its approved plan. The API records daily and monthly usage, returns 429 with Retry-After when limits are exceeded, and raises alerts for unusual activity such as repeated rate-limit hits or 80% monthly quota usage.

GUIDES

Pagination

List endpoints use opaque cursor pagination so integrations can move through results without relying on database offsets.

Request a page

Set limit between 1 and 100. Pass the returned nextCursor unchanged to request the next page.

Second page

GET /api/v1/jobs?limit=25&cursor=eyJ2IjoxLCJvZmZzZXQiOjI1fQ

Read the metadata

Response metadata

{
  "meta": {
    "total": 58,
    "limit": 25,
    "hasMore": true,
    "nextCursor": "eyJ2IjoxLCJvZmZzZXQiOjI1fQ"
  }
}

Stop when hasMore is false or nextCursor is null. Cursors are implementation details and should not be decoded or modified.

EVENTS

Webhooks

Receive signed notifications when your jobs or Direct Apply applications change, then retrieve authorised details through the API.

Supported events

job.publishedA partner job was published.

job.updatedA partner job was changed.

job.closedA partner job stopped accepting applications.

application.receivedA Direct Apply application was submitted.

application.stage_changedAn application's recruitment stage changed.

Verify each signature

Compute an HMAC-SHA256 digest over the timestamp, a period, and the exact raw request body. Compare it with the hexadecimal value after v1=.

Node.js

import crypto from 'node:crypto'

const signed = `${timestamp}.${rawBody}`
const expected = crypto
  .createHmac('sha256', process.env.CU_WEBHOOK_SECRET)
  .update(signed)
  .digest('hex')

const received = signature.replace('v1=', '')
const valid = crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(received)
)

Delivery behavior

Events are queued, retried with backoff, and carry a stable event identifier. Return a successful 2xx response quickly, then process the event asynchronously and idempotently.

Reject stale timestamps

Use the timestamp header to prevent replay. A five-minute tolerance is a practical default.

OPERATIONS

Errors and limits

All API errors use a stable envelope and include a request identifier for support and audit tracing.

Error envelope

Example

{
  "error": {
    "code": "insufficient_scope",
    "message": "The applications:read scope is required.",
    "requestId": "req_2c81..."
  }
}

HTTP status codes

Status	Meaning	Recommended action
`400`	Invalid request	Correct the parameters or payload.
`401`	Invalid or missing key	Check the server-side credential.
`403`	Scope or tenant denied	Request the required approved access.
`404`	Resource unavailable	Verify the identifier and organisation.
`409`	Idempotency conflict	Use the original payload or a new key.
`429`	Rate limit exceeded	Wait for `Retry-After`.
`500`	Unexpected server error	Retry safely and quote the request ID.

Safe retries

Retry transient 429 and 5xx responses with exponential backoff and jitter. Include an Idempotency-Key on every job creation request.

RESOURCES

API status

Use the lightweight status endpoint to confirm API routing and version availability.

Career Unified Partner APIAvailable - Version v1

Check programmatically

Request

curl https://careerunified.com/api/v1/status

Response

{
  "data": {
    "status": "available",
    "version": "v1"
  }
}