All guides

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

  1. 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.
  2. Send it on every request as Authorization: Bearer <token>.
  3. 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
    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
    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.

Post an advert (JSON)
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"
  }'
The same advert as XML
<?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>
Take it down
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

Success (200)
{
  "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
    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.

Multiposters | Opportunity Platform Developers