All guides

Ways to connect

Post jobs by API

A simple POST per job. Each job you send becomes the employer's own listing here, in front of the residents who live closest to the work, and every application comes back through our site so it counts for the employer and the place. Coming

Who it is for

  • ATS vendors who want a "post to Opportunity Platform" option for their customers.
  • Multiposters such as idibu, LogicMelon and Broadbean, sending one job to many boards. Broadbean has its own receiver: see Multiposters.
  • An employer's own developers, posting straight from in-house systems.

Not a developer? You do not need this page. An employer can post jobs from their dashboard, or give us the address of their careers page or a job feed once and we keep their roles in step (see the feed option below).

Get a key

  1. The employer needs an account here (an employer, developer or training provider organisation). If they do not have one, they can start one, or we can set it up.
  2. Ask us for a key with the jobs:write scope: email connect@opportunityplatform.co.uk with the employer's name and who will hold the key. Our team issues it from our integrations hub, on a key owned by that employer. It is never given to a key by default and cannot be added from the dashboard's self-serve API access page, because it publishes in the employer's name.
  3. A key acts for exactly one employer. A multiposter sending jobs for several employers holds one key per employer, which also keeps each employer's jobs, limits and audit trail apart.
  4. Send the key on every request as Authorization: Bearer <key>. See Authentication. Build against our test site first: Sandbox.

The endpoints

  • Endpoint
    POST /v1/jobs
    What it does
    Post a job. 201 with the job; 200 when it updated one you posted before with the same external_reference.
  • Endpoint
    PATCH /v1/jobs/{id}
    What it does
    Change some fields of a job you posted through the API. Only the fields you send change.
  • Endpoint
    POST /v1/jobs/{id}/close
    What it does
    Take a job down. Optional body: {"outcome": "filled"} when the role was filled.
  • Endpoint
    GET /v1/jobs/mine
    What it does
    Every job of your employer, in every status, newest first, with cursor paging. Filter with ?status= or ?external_reference=.

All four need jobs:write. Another employer's job id answers 404, exactly like an id that does not exist. You can change and close only jobs created through the API; the employer's other jobs are listed with editable: false and answer 409. Every response carries the rate limit headers and an X-Request-Id; errors have the standard shape (see Errors).

Post a job
curl -X POST https://opportunityplatform.co.uk/api/v1/jobs \
  -H "Authorization: Bearer $OP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Site Carpenter",
    "description": "<p>Second-fix carpentry on a residential block.</p><ul><li>CSCS card</li><li>Own hand tools</li></ul>",
    "location": "Bermondsey, London",
    "postcode": "SE16 4DG",
    "type": "job",
    "employment_type": "full_time",
    "salary": { "min": 38000, "max": 44000, "period": "year" },
    "hours_per_week": 40,
    "closing_date": "2026-12-31",
    "external_reference": "ATS-48213"
  }'
Response (201)
{
  "data": {
    "id": "3f1a9c2e-5b41-4a7e-9c3d-1e2f4a6b8c0d",
    "public_ref": "OPP-082267",
    "title": "Site Carpenter",
    "type": "job",
    "status": "live",
    "location": "Bermondsey, London",
    "postcode": "SE16 4DG",
    "borough": "southwark",
    "scheme_slug": null,
    "salary": "£38,000 to £44,000 a year",
    "hours_per_week": "40",
    "employment_type": "full_time",
    "closing_date": "2026-12-31T00:00:00.000Z",
    "start_date": null,
    "notify_emails": [],
    "external_reference": "ATS-48213",
    "external_apply_url": null,
    "social_share_opt_out": false,
    "source": "api",
    "editable": true,
    "url": "https://opportunityplatform.co.uk/opportunities/site-carpenter-1760000000000",
    "apply_url": "https://opportunityplatform.co.uk/opportunities/site-carpenter-1760000000000/apply",
    "created_at": "2026-10-15T09:00:00.000Z",
    "updated_at": "2026-10-15T09:00:00.000Z"
  },
  "meta": { "created": true, "status_reason": null }
}
Close it when it is filled
curl -X POST https://opportunityplatform.co.uk/api/v1/jobs/3f1a9c2e-5b41-4a7e-9c3d-1e2f4a6b8c0d/close \
  -H "Authorization: Bearer $OP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "filled" }'

The fields

  • Field
    title
    Required
    Yes
    Notes
    3 to 200 characters.
  • Field
    description
    Required
    Yes
    Notes
    At least 20 characters, up to 20,000. Plain text or simple HTML (paragraphs, line breaks, lists).
  • Field
    location
    Required
    Yes
    Notes
    Where the work is, the way a resident would read it.
  • Field
    postcode
    Required
    Unless scheme_slug is given
    Notes
    UK postcode of the workplace. It decides which area's residents see the job first.
  • Field
    scheme_slug
    Required
    No
    Notes
    Attach the job to a development scheme your organisation is already linked to (by us or the scheme's developer). Any other scheme is refused.
  • Field
    type
    Required
    No
    Notes
    job (default), apprenticeship, work_placement or training.
  • Field
    employment_type
    Required
    No
    Notes
    full_time, part_time, contract, temporary, fixed_term, casual or zero_hours.
  • Field
    salary
    Required
    No
    Notes
    Pay in pounds: {"min", "max", "period"}, period one of year, month, week, day, hour. Shown as "£38,000 to £44,000 a year".
  • Field
    salary_text
    Required
    No
    Notes
    Free text pay when it is not a range, up to 120 characters. salary wins when both are sent.
  • Field
    hours_per_week
    Required
    No
    Notes
    A number, up to 80.
  • Field
    closing_date, start_date
    Required
    No
    Notes
    YYYY-MM-DD or an ISO 8601 date-time. A closing date cannot be in the past.
  • Field
    requirements
    Required
    No
    Notes
    Up to 5,000 characters, cleaned like the description.
  • Field
    notify_emails
    Required
    If the employer has no contact email
    Notes
    Up to 5 addresses told about applications, all on the employer's own email domain (422 otherwise). Without it, the employer's contact email is used.
  • Field
    external_reference
    Required
    Recommended
    Notes
    Your id for the job, up to 200 characters. Makes posting idempotent.
  • Field
    external_apply_url
    Required
    No
    Notes
    Your own apply page, kept for the employer's records. Residents still apply here.
  • Field
    social_share_opt_out
    Required
    No
    Notes
    true keeps the job off our social channels. Default false.
  • Field
    status
    Required
    No
    Notes
    live (default) or draft.
  • Field
    key_skills
    Required
    No
    Notes
    The skills the job needs, from our skills list: [{"skill": "plumbing", "essential": true}], up to 20. A name not on the list is refused. See below.
  • Field
    licences
    Required
    No
    Notes
    Licences and cards: [{"kind": "cscs", "detail": "blue", "essential": true}]. Kinds: cscs, sia, driving, dbs, food_hygiene, first_aid.
  • Field
    role_level
    Required
    No
    Notes
    entry, experienced, senior or supervisor_manager.
  • Field
    experience_needed
    Required
    No
    Notes
    none, under_1_year, 1_to_3_years or 3_plus_years.
  • Field
    open_to_new_starters
    Required
    No
    Notes
    true when you will train someone new to this work.
  • Field
    soc2020
    Required
    No
    Notes
    The occupation as an ONS SOC 2020 unit group code, for example 5315.

An unknown field is refused rather than ignored, so a typo shows up at once. A refusal is 400 validation_failed with error.issues, one entry per field naming the problem; we never repeat the value you sent.

What the job needs

These fields are being switched on environment by environment: where they are not on yet, they are refused as unknown fields, so leave them out until we tell you they are live.

Every one of these is optional, and each makes matching better: we match residents on what you state before anything we read from the description. Send key_skills named from our skills list (case does not matter); once a job has at least one, that list is the job's whole skill list, and an empty list hands it back to the description. An essential licence or card is required to be matched, except a DBS check, which you run for the job. With open_to_new_starters: true we treat experience as something you will teach (licences still count), and residents are told you will train. Residents see the essential licences, the experience needed and that line on the job page. The occupation you send in soc2020 stays when you change the title; send null to go back to the one we read from the title. In a PATCH, a list replaces the job's list and null clears a field.

What the job needs
{
  "key_skills": [{ "skill": "carpentry", "essential": true }, { "skill": "dry lining", "essential": false }],
  "licences": [{ "kind": "cscs", "detail": "blue", "essential": true }],
  "role_level": "experienced",
  "experience_needed": "1_to_3_years",
  "open_to_new_starters": false,
  "soc2020": "5316"
}

Send it twice, get one job

Give every job an external_reference. Posting the same reference again for the same employer updates the job you posted before instead of creating a second one, and answers 200 with meta.created: false. That makes retries safe: if a request times out, send it again. The reference belongs to the employer, so it holds across a key rotation or a second key. Fields you leave out of a repeat post keep their values, except type and status, which take their defaults. To find a job by your reference, use GET /v1/jobs/mine?external_reference=ATS-48213.

Before the employer is verified

Jobs go live in the employer's name, so we check the organisation first: for an employer or developer, that its contact email reaches a person; for a training provider, that its provider verification is approved. Until then, a job you send as live is saved as a draft, and the response says so with meta.status_reason: "employer_not_verified". When the organisation has a contact address, we email it a confirmation link. Once it is confirmed, send PATCH /v1/jobs/{id} with {"status": "live"} (or post the same reference again) and the job goes live. A job that is already live is never taken down by this.

Apply always comes back to us

Every job has an apply_url on our site. That is where residents apply, wherever they found the job, so the application is recorded for the employer and, on a scheme, counts towards the local jobs the development promised. Send your own apply page as external_apply_url if you like: we keep it for the employer's records, and applications are emailed to the employer's contact (or your notify_emails) as they arrive.

Applications carry the applicant's details, so notify_emails must be on the employer's own email domain: the one its contact email or its verified team members use (hr@acme.co.uk for an employer whose contact is jobs@acme.co.uk). A free-mail address counts only when it is exactly one of those. Anything else is refused with 422 validation_failed and error.issues naming the address. These addresses get the application emails only; posting a job never gives anyone access to the employer's account.

Jobs posted this way are the employer's own direct jobs. They appear on the employer's careers page, in the jobs widget, in our job board feeds, and can be shared on our social channels unless you set social_share_opt_out.

What we do to the text

  • HTML in description and requirements becomes plain text: paragraphs, line breaks and list items keep their shape, every tag is removed, and scripts and styles are dropped with their content.
  • Control characters and invisible ones (zero-width spaces, direction overrides, byte order marks) are removed from every field.
  • Titles and locations become a single line.
  • The limits above apply to the cleaned text, so markup does not count against them.

Limits

  • Your key's hourly limit and monthly quota, as on every endpoint (Rate limits).
  • At most 200 new jobs per employer in any 24 hours, across all its keys. Over it, 429 rate_limited with Retry-After. Updates and closes are not counted. Need more? Ask us.
  • A body of at most 64 KB: one job per request.

Prefer a feed? We can read yours

If your system already publishes jobs as XML, there may be nothing to build. The employer pastes the feed address once under Connect your jobs (or we do it for them) and we read it twice a day. We read the <source><job> layout most ATSs can publish, plus RSS (<item>) and Atom (<entry>). Field names are matched without regard to case, values may be wrapped in CDATA, and the first non-empty field in each row wins:

  • We read
    Each job
    From these elements, in order
    <job>, <item> or <entry>
    Notes
    Up to 500 per feed.
  • We read
    Title
    From these elements, in order
    title, jobtitle, name
    Notes
    Required. Tags removed, up to 300 characters.
  • We read
    Link
    From these elements, in order
    url, joburl, applyurl, apply_url, link_ext, then an Atom <link href>, then link, guid
    Notes
    Required, http or https. A row repeating a link already read is skipped.
  • We read
    Reference
    From these elements, in order
    referencenumber, reference, requisitionid, jobreference, id, guid
    Notes
    Keeps the job the same one between reads. Without one, the link is used.
  • We read
    Location
    From these elements, in order
    city, state (or region, county), country, joined; else location
    Notes
  • We read
    Postcode
    From these elements, in order
    postalcode, postcode, zip, zipcode
    Notes
  • We read
    Company
    From these elements, in order
    company, hiringorganization, employer, companyname
    Notes
  • We read
    Description
    From these elements, in order
    description, summary, content, jobdescription
    Notes
    Tags removed, up to 4,000 characters.
  • We read
    Salary
    From these elements, in order
    salary, salaryrange, compensation
    Notes
    As written.
  • We read
    Closing date
    From these elements, in order
    expirationdate, validthrough, enddate, closingdate
    Notes
    Any date format a browser understands; ignored if it does not parse.
A minimal feed
<?xml version="1.0" encoding="UTF-8"?>
<source>
  <job>
    <title><![CDATA[Site Carpenter]]></title>
    <referencenumber><![CDATA[ATS-48213]]></referencenumber>
    <url><![CDATA[https://careers.example.co.uk/jobs/48213]]></url>
    <company><![CDATA[Example Construction]]></company>
    <city><![CDATA[London]]></city>
    <postalcode><![CDATA[SE16 4DG]]></postalcode>
    <description><![CDATA[Second-fix carpentry on a residential block.]]></description>
    <salary><![CDATA[£38,000 to £44,000]]></salary>
    <expirationdate><![CDATA[2026-12-31]]></expirationdate>
  </job>
</source>

The difference: roles read from a feed stay yours. Residents go through a short step here and then on to your own apply page, and feed roles are not added to our job board feeds. Roles posted with the API are the employer's listing here, applied for here. More on feeds in Connect your jobs.

Questions

Can I post for an employer that has no account?

Not with the API: a key always belongs to one employer's organisation. Ask us and we will set the employer up, or have them start an account first.

Can I change a job the employer posted on the dashboard?

No. GET /v1/jobs/mine lists them (source: "dashboard", editable: false) so you can avoid posting them twice, but they are changed in the dashboard: they can carry evidence for the commitments a development made, which the API must not disturb. PATCH and close answer 409 with error.reason: "not_api_job". Jobs read from a connected feed (source: "feed") are changed at the source.

How do I test?

On our test site, https://qa.opportunityplatform.co.uk/api, with a key we issue there. It is a separate database: nothing you post there reaches residents.

Is there a delete?

No. Close the job instead: it leaves the site at once, and the record of who applied stays with the employer, which councils rely on.

Post jobs by API | Opportunity Platform Developers