All guides
Ways to connect
Partner API
Reference
Ways to connect
Multiposters
Recruiters already send each advert to many boards from one place. Add us as one of those boards and every advert lands here as the employer's own listing, in front of the residents who live closest to the work. Coming
Who it is for
- Broadbean (Veritone Hire), through its Instant Feed: this page is the contract its integrations team builds to.
- Other multiposters such as idibu and LogicMelon. Tell us you want to connect and we will agree the details. Until then, the jobs API works for anyone who can send JSON.
Get a token
- Email connect@opportunityplatform.co.uk with the recruiter's name. We issue one token per recruiter account, with job posting switched on. We share it through your secure intake, never by email.
- Send it on every request as
Authorization: Bearer <token>. - A recruiter that posts for its own organisation needs nothing else. A recruitment agency posting for several clients needs each client to approve the agency here first; then name the client on each advert (see Agencies and clients).
The endpoint
| Item | Value |
|---|---|
| Production | POST https://opportunityplatform.co.uk/api/integrations/broadbean/ingest |
| Test site | POST https://qa.opportunityplatform.co.uk/api/integrations/broadbean/ingest |
| Body | One advert per request, at most 256 KB, as application/json (preferred), application/xml or application/x-www-form-urlencoded. |
| Replays | Send X-Broadbean-Request-Id and we will recognise a repeat of the same request. |
| Concurrency | Safe to call in parallel. |
- Item
- Production
- Value
POST https://opportunityplatform.co.uk/api/integrations/broadbean/ingest
- Item
- Test site
- Value
POST https://qa.opportunityplatform.co.uk/api/integrations/broadbean/ingest
- Item
- Body
- Value
- One advert per request, at most 256 KB, as application/json (preferred), application/xml or application/x-www-form-urlencoded.
- Item
- Replays
- Value
- Send X-Broadbean-Request-Id and we will recognise a repeat of the same request.
- Item
- Concurrency
- Value
- Safe to call in parallel.
Post, amend and take down
Every advert carries an action: post (the default), amend or delete. Your reference is the key. Posting or amending a reference we already have updates that job rather than making a second one, so a retry is always safe. Send the whole advert each time: an optional field you leave out (a closing date, an application URL) is cleared. amend never reopens a job that was taken down; post does. delete needs only the reference: the job leaves the site at once, and the record of who applied stays with the employer.
The fields
| Field | Required | Notes |
|---|---|---|
action | No | post (default), amend or delete. |
reference | Yes | Your id for the advert, up to 200 characters. |
title | Yes | 3 to 200 characters. |
description | Yes | HTML is fine; we turn it into plain text. At least 20 characters of text. |
job_type | Yes | job, apprenticeship, training or work_placement. |
postcode | Yes | UK postcode of the workplace, anywhere in the UK. It decides which residents see the job first. |
location_text | No | Where the work is, as a resident would read it. The postcode is shown when it is missing. |
salary_description | No | Pay as text, up to 120 characters. |
hours | No | For example "Full-time" or "37.5 hours a week". We read full or part time and a single weekly figure from it, and keep the text. |
start_date, closing_date | No | YYYY-MM-DD or an ISO 8601 date-time. A closing date cannot be in the past. |
application_email | Yes, or application_url | The tracking address for this advert. We keep it for sending applications back to you. |
application_url | Instead of the email | An https address on a public host, kept for the same purpose. |
employer_name | No | The employer the advert is for. For an agency, it can name the client (below). |
employer_id | No | Our id for an agency’s client, when you have it. |
contact_name, contact_email | No | Kept for our records. We never send anything to the contact email. |
- Field
action- Required
- No
- Notes
- post (default), amend or delete.
- Field
reference- Required
- Yes
- Notes
- Your id for the advert, up to 200 characters.
- Field
title- Required
- Yes
- Notes
- 3 to 200 characters.
- Field
description- Required
- Yes
- Notes
- HTML is fine; we turn it into plain text. At least 20 characters of text.
- Field
job_type- Required
- Yes
- Notes
- job, apprenticeship, training or work_placement.
- Field
postcode- Required
- Yes
- Notes
- UK postcode of the workplace, anywhere in the UK. It decides which residents see the job first.
- Field
location_text- Required
- No
- Notes
- Where the work is, as a resident would read it. The postcode is shown when it is missing.
- Field
salary_description- Required
- No
- Notes
- Pay as text, up to 120 characters.
- Field
hours- Required
- No
- Notes
- For example "Full-time" or "37.5 hours a week". We read full or part time and a single weekly figure from it, and keep the text.
- Field
start_date, closing_date- Required
- No
- Notes
- YYYY-MM-DD or an ISO 8601 date-time. A closing date cannot be in the past.
- Field
application_email- Required
- Yes, or application_url
- Notes
- The tracking address for this advert. We keep it for sending applications back to you.
- Field
application_url- Required
- Instead of the email
- Notes
- An https address on a public host, kept for the same purpose.
- Field
employer_name- Required
- No
- Notes
- The employer the advert is for. For an agency, it can name the client (below).
- Field
employer_id- Required
- No
- Notes
- Our id for an agency’s client, when you have it.
- Field
contact_name, contact_email- Required
- No
- Notes
- Kept for our records. We never send anything to the contact email.
Field names are matched without regard to case. Any other field is kept with the advert for our records and otherwise ignored. In XML, each field is a child element of the root (any root name), and the description can be wrapped in CDATA. XML with a DOCTYPE or entity declarations is refused, so send the body of an HTML description, not a whole HTML document. We read the body in the character set you declare (the charset of the Content-Type, or the XML declaration), UTF-8 when you declare none, and refuse bytes that do not fit it. A form must be UTF-8.
curl -X POST https://opportunityplatform.co.uk/api/integrations/broadbean/ingest \
-H "Authorization: Bearer $OP_TOKEN" \
-H "Content-Type: application/json" \
-H "X-Broadbean-Request-Id: 7f3c2a10-0001" \
-d '{
"action": "post",
"reference": "FRC-12345",
"title": "Site Supervisor",
"description": "<p>Supervise a residential block.</p><ul><li>SMSTS</li><li>CSCS</li></ul>",
"job_type": "job",
"postcode": "SE16 4DG",
"location_text": "Bermondsey, London",
"salary_description": "45,000 pounds a year",
"hours": "Full-time",
"closing_date": "2026-12-31",
"application_email": "frc12345.abc@aplitrak.com"
}'<?xml version="1.0" encoding="UTF-8"?>
<advert>
<action>post</action>
<reference>FRC-12345</reference>
<title>Site Supervisor</title>
<description><![CDATA[<p>Supervise a residential block.</p>]]></description>
<job_type>job</job_type>
<postcode>SE16 4DG</postcode>
<application_email>frc12345.abc@aplitrak.com</application_email>
</advert>curl -X POST https://opportunityplatform.co.uk/api/integrations/broadbean/ingest \
-H "Authorization: Bearer $OP_TOKEN" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "action=delete&reference=FRC-12345"Responses
{
"ok": true,
"opportunity_id": "0d9d35f1-62de-4aad-96c5-d61992662c21",
"public_url": "https://opportunityplatform.co.uk/opportunities/site-supervisor-1760000000000",
"expires_at": "2026-12-31T00:00:00.000Z",
"action": "post",
"status": "live",
"created": true,
"status_reason": null,
"reference": "FRC-12345",
"request_id": "req_4b1f0c2e9d8a4f6b8c7d6e5f4a3b2c1d"
}| Status | error | When |
|---|---|---|
| 400 | validation_failed | A field is missing or not valid. fields names each one and what is wrong; we never repeat the value you sent. |
| 401 | unauthorised | The token is missing or not recognised. |
| 403 | forbidden | The token cannot post jobs. |
| 404 | not_found | delete for a reference we do not have, or the receiver is not switched on. |
| 409 | duplicate_reference | The reference belongs to a job this token cannot change. existing_opportunity_id names it when we can. |
| 409 | request_id_reused | The X-Broadbean-Request-Id was already used for a different advert. |
| 409 | another reason | The employer’s account does not allow it right now, for example a free trial at its live job limit. message says why. |
| 422 | out_of_scope_location | The postcode is not a UK postcode we can find. Correct it rather than retrying; any real UK postcode is accepted. |
| 429 | rate_limited | Too many requests, or too many new jobs for the employer today. Wait for Retry-After. |
| 500 | internal | Our fault. Retry with exponential backoff: 1, 2, 4 and 8 seconds, then tell us. |
| 503 | temporarily_unavailable | The check on the application address could not run, or the same request id is still being handled. Nothing was saved: send the same request again after Retry-After. |
- Status
- 400
- error
validation_failed- When
- A field is missing or not valid. fields names each one and what is wrong; we never repeat the value you sent.
- Status
- 401
- error
unauthorised- When
- The token is missing or not recognised.
- Status
- 403
- error
forbidden- When
- The token cannot post jobs.
- Status
- 404
- error
not_found- When
- delete for a reference we do not have, or the receiver is not switched on.
- Status
- 409
- error
duplicate_reference- When
- The reference belongs to a job this token cannot change. existing_opportunity_id names it when we can.
- Status
- 409
- error
request_id_reused- When
- The X-Broadbean-Request-Id was already used for a different advert.
- Status
- 409
- error
- another reason
- When
- The employer’s account does not allow it right now, for example a free trial at its live job limit. message says why.
- Status
- 422
- error
out_of_scope_location- When
- The postcode is not a UK postcode we can find. Correct it rather than retrying; any real UK postcode is accepted.
- Status
- 429
- error
rate_limited- When
- Too many requests, or too many new jobs for the employer today. Wait for Retry-After.
- Status
- 500
- error
internal- When
- Our fault. Retry with exponential backoff: 1, 2, 4 and 8 seconds, then tell us.
- Status
- 503
- error
temporarily_unavailable- When
- The check on the application address could not run, or the same request id is still being handled. Nothing was saved: send the same request again after Retry-After.
An advert for an employer we have not verified yet is saved as a draft, not refused: the response has status: "draft" and status_reason: "employer_not_verified", and the job goes live once the employer confirms its contact address and you send the advert again.
Replays
If you send X-Broadbean-Request-Id (up to 128 letters, digits, dots, colons, hyphens or underscores), we remember each successful request for 30 days. Sending the same id with the same body again returns the first response, marked with X-Replayed: true, and changes nothing. The same id with a different body is refused. A request that failed is not remembered, so you can retry it with the same id.
Agencies and clients
A recruitment agency's token posts for its clients, and only for clients who have approved the agency here. We work out the client for each advert in this order: employer_id when you send it; else the client of an earlier advert with the same reference (so amends and deletes need nothing extra); else the one approved client whose name matches employer_name. If none of those settles it, the advert is refused with a field error on employer_id.
Applications
Residents apply on our site, so the application counts for the employer and the place. We keep your application_email or application_url with the job so applications can be sent back to your tracking address.
Limits
- Your token's hourly limit and monthly quota (Rate limits).
- The same daily cap on new jobs per employer as the jobs API. Amends and deletes are not counted.
- A body of at most 256 KB.
Questions
Do you support signed requests instead of a token?
Not yet. Every request is authenticated with the bearer token over HTTPS. Ask us if you need a signature as well.
How do I test?
On our test site, https://qa.opportunityplatform.co.uk/api, with a token we issue there. Nothing you post there reaches residents.
What happens to the HTML in the description?
We turn it into plain text: paragraphs, line breaks and list items keep their shape, every tag is removed, and scripts and styles are dropped with their content. Details in What we do to the text.