OHUB External API
Programmatic access to The Opportunity Hub. Post jobs, provision employers, and receive matched candidate applications from your own platform.
https://www.theohub.global/api/external/v1Endpoints
/employers/provisionProvision employer account + API key partner key
/jobsCreate a job employer key
/jobsList jobs (paginated) employer key
/jobs/{id}Get full job details + stats employer key
/jobs/{id}Update job (re-tags if title/description changed) employer key
/jobs/{id}Close a job employer key
/billingBilling status and card-on-file check employer key
/jobs/{id}/campaignCampaign status and spend breakdown employer key
/jobs/{id}/campaignActivate a performance campaign employer key
/jobs/{id}/campaignAdjust budget, daily cap, or pause/resume employer key
/jobs/{id}/campaignPause a campaign (preserves budget) employer key
Authentication
All requests require an API key passed as a Bearer token in the Authorization header.
Employer-level key (all job endpoints):
Authorization: Bearer ohub_live_sk_<32-char-hex>Partner-level key (provisioning only):
Authorization: Bearer <PARTNER_KEY>- Employer keys are scoped to a single employer account
- Keys are shown only once at creation. Store securely
- Keys can be generated from the OHUB dashboard → Settings → Integrations, or via the provisioning endpoint
- Partner keys are issued by OHUB. Get in touch to request access
Rate Limits
| Method | Limit | Window |
|---|---|---|
| POST /jobs | 100 requests | 1 hour |
| GET /jobs, GET /jobs/{id} | 500 requests | 1 hour |
| PUT /jobs/{id}, DELETE /jobs/{id} | 200 requests | 1 hour |
Rate limit status is returned on every response:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1747393200000 // Unix ms timestamp when window resetsOn limit exceeded, the API returns 429:
{ "error": "Rate limit exceeded", "message": "Too many requests. Please wait and try again." }POST /employers/provision
Create a new employer account with a LITE subscription. Returns an API key for the employer. Partner-level auth required.
Request body:
| Field | Type | Default | Notes |
|---|---|---|---|
| company_name* | string | — | Max 500 chars |
| contact_email* | string | — | Max 320 chars. Must be a valid email |
| contact_first_name* | string | — | Max 200 chars |
| contact_last_name* | string | — | Max 200 chars |
| phone | string | — | Max 50 chars |
| website | string | — | Max 500 chars |
| industry | string | — | Max 200 chars |
| company_size | string | — | e.g. "11-50", "51-200" |
| source | string | external | Tag source for tracking. Use "idibu" for idibu integrations |
* Required
Response 201 Created:
{
"success": true,
"existing": false,
"employer_id": "cmp760p5w006ela04v25egiai",
"user_id": "usr123abc",
"api_key": "ohub_live_sk_a1b2c3d4e5f6...",
"api_key_note": "Store this key securely. It will not be shown again.",
"setup_url": "https://www.theohub.global/dashboard/company/settings",
"login_url": "https://www.theohub.global/auth/forgot-password",
"message": "Employer account created with LITE tier."
}Response 200 OK (employer already exists):
{
"success": true,
"existing": true,
"employer_id": "cmp760p5w006ela04v25egiai",
"message": "Employer already exists. API key provided.",
"api_key": "ohub_live_sk_...",
"login_url": "https://www.theohub.global/auth/login"
}api_key will not be returned. Contact OHUB support to rotate an existing key.login_url.POST /jobs
Create a new job. Jobs are AI-enhanced on creation: skills, industry, job function tags and an AI overview are generated automatically. Jobs go live immediately.
| Field | Type | Default | Notes |
|---|---|---|---|
| title* | string | — | Max 500 chars |
| description* | string | — | Max 50,000 chars. HTML is sanitised |
| location | string | — | City/region. AI-detected from description if omitted |
| salary_min | number | — | Annual salary in base currency |
| salary_max | number | — | Must be >= salary_min |
| currency | string | GBP | ISO 4217. GBP, USD, EUR, CAD, AUD, NZD, CHF, SEK, NOK, DKK, SGD, HKD, JPY, INR, AED, ZAR, BRL, MXN, PLN, CZK |
| job_type | string | FULL_TIME | PERMANENT, FULL_TIME, PART_TIME, CONTRACT, FREELANCE, INTERNSHIP, TEMPORARY, SEASONAL, VOLUNTEER |
| experience_level | string | — | e.g. Junior, Mid-Level, Senior, Director. Overrides AI detection when supplied. |
| is_remote | boolean | false | Accepts true/false or 1/0 |
| is_hybrid | boolean | false | Mark as hybrid working. Shown as a badge on the OHUB listing. |
| hide_salary | boolean | false | Hide salary from candidates. Listing shows "Negotiable". salary_min/max are still stored for internal filtering and matching. |
| apply_email | string | — | Tracking email for CV delivery. Supports + addressing (e.g. [email protected]) |
| expiry_date | string | — | ISO 8601 date (e.g. "2026-08-01"). Job is hidden from listings after this date. |
| duration_weeks | integer | — | Contract/temp duration in weeks. Informational, shown on listing. |
| external_reference | string | — | Your internal job ID for cross-referencing |
| company_name | string | — | Displayed on listing. Defaults to employer account name |
| contact_number | string | — | Max 50 chars |
| postcode | string | — | Strongly recommended. UK postcode (e.g. "SW1A 1AA"). Without this, the job will not appear in commute time searches. AI will attempt to infer from description but supply explicitly for accuracy. Max 20 chars. |
| visa_sponsorship | boolean | false | Accepts true/false or 1/0 |
* Required
<p>, <br>, <ul>, <li>, <strong>, <em>, <h1>–<h3>, <a href>. Script tags, inline styles, and iframes are stripped. Standard job board HTML renders correctly.Response 201 Created:
{
"success": true,
"message": "Ad successfully posted",
"request_id": "3f7a9c1d-...",
"job": {
"id": "clr1a2b3c4d5e6f7",
"title": "Senior Software Engineer",
"location": "London",
"status": "ACTIVE",
"is_remote": false,
"is_hybrid": true,
"hide_salary": false,
"external_reference": "JOB-2026-001",
"company_name": "Acme Recruitment",
"company_logo_url": "https://www.theohub.global/logo.png",
"live_url": "https://www.theohub.global/jobs/clr1a2b3c4d5e6f7",
"created_at": "2026-05-18T12:00:00.000Z",
"ai_enhanced": {
"experience_level": "Senior",
"salary": { "min": 70000, "max": 90000, "currency": "GBP", "display": "£70,000 – £90,000" },
"skills_tagged": 12,
"industries_tagged": 2,
"job_functions_tagged": 3
}
}
}moderation_status: "pending_review" field and live_url will be null until the OHUB team approves it (typically under 2 hours). The job ID is valid and can be polled via GET /jobs/{id}.GET /jobs
List all jobs for the authenticated employer, with pagination and filtering. All filter params are optional and combinable.
| Field | Type | Default | Notes |
|---|---|---|---|
| page | number | 1 | Pagination |
| limit | number | 20 | Max 100 per page |
| status | string | all | ACTIVE, PAUSED, CLOSED, DRAFT, QUEUED |
| job_type | string | all | PERMANENT, FULL_TIME, PART_TIME, CONTRACT, FREELANCE, INTERNSHIP, TEMPORARY, SEASONAL, VOLUNTEER |
| experience_level | string | all | Partial match, e.g. "Senior" matches "Senior" and "Senior Manager" |
| is_remote | boolean | all | true or false |
| is_hybrid | boolean | all | true or false |
| location | string | all | Partial city match, e.g. "London" or "Manchester" |
| external_reference | string | all | Exact match on your own job ID. Use this to look up a specific job without knowing the OHUB ID. |
| salary_min | number | all | Filter to jobs where salary_min is at least this value (e.g. 50000) |
| salary_max | number | all | Filter to jobs where salary_max is at most this value (e.g. 100000) |
| created_after | string | all | ISO 8601 date. Returns jobs created on or after this date |
| created_before | string | all | ISO 8601 date. Returns jobs created on or before this date |
* Required
GET /api/external/v1/jobs?status=ACTIVE&job_type=CONTRACT&is_remote=true&page=1&limit=20
// Look up a specific job by your own reference:
GET /api/external/v1/jobs?external_reference=JOB-2026-001
// Jobs created in a date range:
GET /api/external/v1/jobs?created_after=2026-05-01&created_before=2026-05-31Response 200 OK:
{
"success": true,
"request_id": "3f7a9c1d-...",
"jobs": [
{
"id": "clr1a2b3c4d5e6f7",
"title": "Senior Software Engineer",
"location": "London",
"job_type": "PERMANENT",
"experience_level": "Senior",
"is_remote": false,
"is_hybrid": true,
"salary": { "min": 70000, "max": 90000, "currency": "GBP" },
"status": "ACTIVE",
"is_active": true,
"impressions": 142,
"clicks": 38,
"applications": 7,
"company_logo_url": "https://www.theohub.global/logo.png",
"external_reference": "JOB-2026-001",
"source": "IDIBU_API",
"live_url": "https://www.theohub.global/jobs/clr1a2b3c4d5e6f7",
"created_at": "2026-05-18T12:00:00.000Z",
"updated_at": "2026-05-18T12:00:00.000Z"
}
],
"pagination": { "page": 1, "limit": 20, "total": 43, "pages": 3 }
}GET /jobs/{id}
Full job details including AI tags, traits, and performance stats.
GET /api/external/v1/jobs/clr1a2b3c4d5e6f7Response 200 OK:
{
"success": true,
"request_id": "3f7a9c1d-...",
"job": {
"id": "clr1a2b3c4d5e6f7",
"title": "Senior Software Engineer",
"description": "<p>We are looking for an experienced engineer...</p>",
"location": "London",
"salary": { "min": 70000, "max": 90000, "currency": "GBP" },
"job_type": "PERMANENT",
"experience_level": "Senior",
"is_remote": false,
"is_hybrid": true,
"hide_salary": false,
"country": "United Kingdom",
"postcode": "EC2A 1NT",
"company_name": "Acme Recruitment",
"company_logo_url": "https://www.theohub.global/logo.png",
"visa_sponsorship": false,
"contact_number": "020 7123 4567",
"status": "ACTIVE",
"is_active": true,
"external_reference": "JOB-2026-001",
"apply_email": "[email protected]",
"duration_weeks": null,
"expiry_date": null,
"source": "IDIBU_API",
"live_url": "https://www.theohub.global/jobs/clr1a2b3c4d5e6f7",
"stats": { "impressions": 142, "clicks": 38, "applications": 7 },
"ai_tags": {
"skills": ["Python", "AWS", "Docker"],
"industries": ["Technology"],
"job_functions": ["Software Engineering"]
},
"traits": null,
"created_at": "2026-05-18T12:00:00.000Z",
"updated_at": "2026-05-18T12:00:00.000Z",
"activated_at": "2026-05-18T12:01:00.000Z"
}
}company_logo_url: the employer's uploaded logo. Falls back to the OHUB default logo if no logo has been uploaded. Use this to display the employer brand alongside the job listing on your platform.
PUT /jobs/{id}
Partially update a job. All fields are optional, only include what you want to change. Cannot update a closed job.
title or description is updated, all AI tags are automatically regenerated. The response includes ai_retagged: true."status": "PAUSED" to take a job off the live listings without permanently closing it. Pass "status": "ACTIVE" to re-activate. To permanently close a job use DELETE instead.| Field | Type | Default | Notes |
|---|---|---|---|
| title | string | — | Max 500 chars |
| description | string | — | Max 50,000 chars. HTML sanitised. Re-runs AI tagging if changed. |
| location | string | — | City/region |
| salary_min | number | — | Annual salary in base currency |
| salary_max | number | — | Must be >= salary_min |
| currency | string | — | ISO 4217 code |
| job_type | string | — | PERMANENT, FULL_TIME, PART_TIME, CONTRACT, etc. |
| experience_level | string | — | Overrides AI detection |
| is_remote | boolean | — | true/false or 1/0 |
| is_hybrid | boolean | — | true/false or 1/0 |
| hide_salary | boolean | — | true = show "Negotiable" to candidates; salary values still stored for matching |
| status | string | — | ACTIVE or PAUSED. Use DELETE to permanently close. |
| apply_email | string | — | Tracking email for CV delivery |
| external_reference | string | — | Your internal job ID |
| company_name | string | — | Override displayed company name |
| postcode | string | — | UK postcode. Max 20 chars. |
| visa_sponsorship | boolean | — | true/false |
| expiry_date | string | — | ISO 8601 date |
| duration_weeks | integer | — | Contract duration in weeks |
* Required
PUT /api/external/v1/jobs/clr1a2b3c4d5e6f7
{
"title": "Lead Software Engineer",
"salary_max": 100000,
"is_hybrid": true,
"hide_salary": false
}Response 200 OK:
{
"success": true,
"message": "Ad successfully updated",
"request_id": "3f7a9c1d-...",
"job": {
"id": "clr1a2b3c4d5e6f7",
"title": "Lead Software Engineer",
"location": "London",
"status": "ACTIVE",
"is_active": true,
"live_url": "https://www.theohub.global/jobs/clr1a2b3c4d5e6f7",
"updated_at": "2026-05-18T13:00:00.000Z",
"ai_retagged": true
}
}Response when pausing { "status": "PAUSED" }:
{
"success": true,
"message": "Ad successfully paused",
"request_id": "3f7a9c1d-...",
"job": {
"id": "clr1a2b3c4d5e6f7",
"title": "Lead Software Engineer",
"location": "London",
"status": "PAUSED",
"is_active": false,
"live_url": null,
"updated_at": "2026-05-18T13:00:00.000Z",
"ai_retagged": false
}
}DELETE /jobs/{id}
Close a job. Sets status: CLOSED and removes it from public listings. Does not permanently delete the record.
DELETE /api/external/v1/jobs/clr1a2b3c4d5e6f7Response 200 OK:
{
"success": true,
"job": {
"id": "clr1a2b3c4d5e6f7",
"status": "CLOSED",
"is_active": false,
"message": "Job has been closed and is no longer visible on the platform."
}
}Attempting to DELETE an already-closed job returns 404.
GET /billing
Check whether the employer has a payment card on file and can activate campaigns. Use this to determine billing readiness before calling POST /jobs/{id}/campaign.
GET /api/external/v1/billingResponse 200 OK:
{
"billing": {
"card_on_file": true,
"card_added_at": "2026-05-20T14:30:00.000Z",
"billing_mode": "AUTO",
"can_activate_campaigns": true,
"active_campaigns": 2,
"total_spend_this_month_pence": 4500,
"setup_url": "https://www.theohub.global/dashboard/company/settings?tab=billing",
"tier": "LITE"
}
}Response fields:
| Field | Type | Default | Notes |
|---|---|---|---|
| card_on_file | boolean | — | Whether a payment method is stored |
| card_added_at | string|null | — | ISO 8601 timestamp when the card was added, or null |
| billing_mode | string | — | AUTO (campaigns run automatically once card is added) |
| can_activate_campaigns | boolean | — | Whether campaigns can be activated (requires card on file) |
| active_campaigns | number | — | Count of currently active campaigns |
| total_spend_this_month_pence | number | — | Total campaign spend this calendar month in pence |
| setup_url | string | — | URL to direct employer to add a payment card |
| tier | string | — | Subscription tier: FREE, LITE, PRO, or MAX |
* Required
can_activate_campaigns is false, redirect the employer to the setup_url to add their payment card.GET /jobs/{id}/campaign
Returns campaign status and spend breakdown for a job. If no campaign has been created, the response includes default values with is_active: false.
GET /api/external/v1/jobs/clr1a2b3c4d5e6f7/campaignResponse 200 OK:
{
"campaign": {
"job_id": "clr1a2b3c4d5e6f7",
"job_title": "Senior Software Engineer",
"job_status": "ACTIVE",
"has_free_remaining": true,
"budget": {
"is_active": true,
"auto_charge_enabled": true,
"total_budget_pence": 10000,
"spent_pence": 3200,
"remaining_pence": 6800,
"daily_cap_pence": 2000,
"today_spent_pence": 800
},
"unlocks": {
"free": 3,
"paid": 8,
"total": 11
}
}
}Response fields:
| Field | Type | Default | Notes |
|---|---|---|---|
| job_id | string | — | OHUB job identifier |
| job_title | string | — | Current job title |
| job_status | string | — | ACTIVE, PAUSED, or CLOSED |
| has_free_remaining | boolean | — | Whether free application deliveries are still available for this job |
| budget | object|null | — | Campaign budget details, or null if no campaign has been created |
| budget.is_active | boolean | — | Whether the campaign is currently running |
| budget.auto_charge_enabled | boolean | — | Whether new applications are unlocked automatically |
| budget.total_budget_pence | number | — | Total campaign budget in pence |
| budget.spent_pence | number | — | Amount spent so far in pence |
| budget.remaining_pence | number | — | Budget remaining in pence |
| budget.daily_cap_pence | number|null | — | Daily spend cap in pence, or null if no cap set |
| budget.today_spent_pence | number | — | Amount spent today in pence |
| unlocks.free | number | — | Count of free application unlocks |
| unlocks.paid | number | — | Count of paid application unlocks |
| unlocks.total | number | — | Total unlocks (free + paid) |
* Required
POST /jobs/{id}/campaign
Activates a performance campaign on a job. The campaign budget controls how much you spend on unlocking matched candidates beyond the free quota.
Request body:
| Field | Type | Default | Notes |
|---|---|---|---|
| total_budget_pence* | number | — | Total campaign budget in pence. Min 500 (£5), max 100000 (£1,000) |
| daily_cap_pence | number | — | Optional daily spend cap in pence. Min 300 (£3) if provided |
* Required
POST /api/external/v1/jobs/clr1a2b3c4d5e6f7/campaign
{
"total_budget_pence": 10000,
"daily_cap_pence": 2000
}Response 201 Created:
{
"success": true,
"campaign": {
"job_id": "clr1a2b3c4d5e6f7",
"is_active": true,
"total_budget_pence": 10000,
"daily_cap_pence": 2000
}
}402 with a CARD_REQUIRED error code and a setup_url link. Direct the employer to complete card setup before retrying.// 402 Response when no card on file:
{
"error": "Payment method required",
"code": "CARD_REQUIRED",
"setup_url": "https://www.theohub.global/dashboard/company/settings?tab=billing"
}PUT /jobs/{id}/campaign
Adjust budget, daily cap, or pause/resume an existing campaign. All fields are optional, only include what you want to change.
Request body:
| Field | Type | Default | Notes |
|---|---|---|---|
| total_budget_pence | number | — | New total budget in pence. Min 500, max 100000 |
| daily_cap_pence | number|null | — | New daily cap in pence (min 300), or null to remove the cap entirely |
| is_active | boolean | — | Set false to pause, true to resume |
* Required
PUT /api/external/v1/jobs/clr1a2b3c4d5e6f7/campaign
{
"total_budget_pence": 20000,
"daily_cap_pence": null,
"is_active": true
}Response 200 OK:
{
"success": true,
"campaign": {
"job_id": "clr1a2b3c4d5e6f7",
"is_active": true,
"total_budget_pence": 20000,
"spent_pence": 3200,
"remaining_pence": 16800,
"daily_cap_pence": null
}
}DELETE /jobs/{id}/campaign
Pauses a campaign and preserves the remaining budget. The campaign can be resumed at any time via PUT /jobs/{id}/campaign with "is_active": true.
DELETE /api/external/v1/jobs/clr1a2b3c4d5e6f7/campaignResponse 200 OK:
{
"success": true,
"message": "Campaign paused. Budget preserved. Use PUT with is_active: true to resume.",
"campaign": {
"job_id": "clr1a2b3c4d5e6f7",
"is_active": false,
"total_budget_pence": 10000,
"spent_pence": 3200,
"remaining_pence": 6800
}
}Returns 404 if no campaign exists for the job.
Content Rules
These rules apply to every job posted through the API, the same as jobs posted in the dashboard. They are set out in full in our Advertising Terms.
Applications stay on the platform
Candidates apply through The Opportunity Hub's Apply button. A job whose description sends candidates elsewhere to apply (a form, an external site or an "email your CV to" line) is held until that route is removed, and the response lists what to change. apply_email is not affected: it is where completed applications are delivered to you.
Contact details on the free plan
Jobs posted on the free plan may not include contact details. Email addresses, phone numbers and messaging links in a job's title or description are removed automatically when the job is saved. The job still goes live as normal, and a note on the role in your dashboard confirms the details were removed. Paid plans may include contact details, except in jobs posted anonymously. The contact_number and apply_email fields are separate and are not shown in the advert.
Application Delivery
Free Quota
- The first few CVs per job are automatically delivered to the
apply_emailaddress - If
apply_emailis omitted, CVs are held in the OHUB employer dashboard only. No email delivery occurs - Delivery format: OHUB-branded email with candidate CV attached, video intro link, and match score
- Email structure follows the idibu deliverability spec:
- FROM:
[email protected](constant, never changes) - REPLY-TO:
"Candidate Name" <[email protected]> - ENVELOPE-FROM: managed by AWS SES with OHUB's verified domain
- FROM:
After Free Quota
- Applicants beyond the free quota are held in the OHUB employer dashboard
- A notification is sent to the employer with the count of waiting applicants
- PII is gated until unlocked. Only name initial, match score, and grade are visible
- Employer can unlock individually or set a performance budget to unlock automatically
Webhook Delivery
Webhook delivery to a configured endpoint is available for API integrations. To set up a webhook URL for your integration, use our contact form.
Error Codes
All error responses include a request_id field for support queries.
| Code | Meaning | Detail |
|---|---|---|
| 400 | Bad Request: missing or invalid fields | Response includes missing[] array or field-specific message |
| 401 | Unauthorized: invalid, missing, or revoked API key | — |
| 402 | Payment Required: no card on file for campaign activation | Response includes setup_url to redirect the employer to add a payment card |
| 403 | Forbidden: KYC not approved, or wrong employer resource | — |
| 404 | Not Found: job does not exist, is closed, or belongs to a different employer | — |
| 409 | Conflict: duplicate email on provisioning | — |
| 429 | Rate Limited: see X-RateLimit-* headers | Also returned when active job limit reached |
| 500 | Internal Server Error (transient) | Retry with exponential backoff |
curl Examples
Provision an employer
curl -X POST https://www.theohub.global/api/external/v1/employers/provision \
-H "Authorization: Bearer YOUR_PARTNER_KEY" \
-H "Content-Type: application/json" \
-d '{
"company_name": "Acme Recruitment",
"contact_email": "[email protected]",
"contact_first_name": "Sarah",
"contact_last_name": "Jones",
"source": "idibu"
}'Post a job
curl -X POST https://www.theohub.global/api/external/v1/jobs \
-H "Authorization: Bearer ohub_live_sk_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Senior Software Engineer",
"description": "We are looking for an experienced engineer...",
"location": "London",
"salary_min": 70000,
"salary_max": 90000,
"job_type": "PERMANENT",
"is_hybrid": true,
"hide_salary": false,
"apply_email": "[email protected]",
"external_reference": "JOB-2026-001"
}'List active jobs
curl "https://www.theohub.global/api/external/v1/jobs?status=ACTIVE&page=1&limit=20" \
-H "Authorization: Bearer ohub_live_sk_YOUR_KEY"Get job details
curl https://www.theohub.global/api/external/v1/jobs/JOB_ID \
-H "Authorization: Bearer ohub_live_sk_YOUR_KEY"Update a job
curl -X PUT https://www.theohub.global/api/external/v1/jobs/JOB_ID \
-H "Authorization: Bearer ohub_live_sk_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{ "salary_max": 100000 }'Check billing status
curl https://www.theohub.global/api/external/v1/billing \
-H "Authorization: Bearer ohub_live_sk_YOUR_KEY"Activate a campaign
curl -X POST https://www.theohub.global/api/external/v1/jobs/JOB_ID/campaign \
-H "Authorization: Bearer ohub_live_sk_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{ "total_budget_pence": 10000, "daily_cap_pence": 2000 }'Close a job
curl -X DELETE https://www.theohub.global/api/external/v1/jobs/JOB_ID \
-H "Authorization: Bearer ohub_live_sk_YOUR_KEY"idibu Integration Notes
- Set
apply_emailto the idibu tracking address:track+{jobref}@aptrack.co.uk - Set
external_referenceto the idibu job ID for cross-referencing - Set
sourceto"idibu"in provisioning. This tags all jobs withsource: IDIBU_API - The OHUB
live_urlreturned on POST can be used as the job's canonical link in idibu - CV delivery email uses REPLY-TO set to the candidate's email. HR can reply directly without extra configuration
- The FROM address (
[email protected]) is constant and will never change