Versioning and deprecation
Statement
Section titled “Statement”The published Recruso API is version 1, and every business route says so: /v1/workers,
/v1/clients, /v1/reference/genders. Recruso will not make a breaking change to it. Version 1
will gain new endpoints and new fields over time; it will not lose or alter the ones it already has.
Where new behaviour cannot be added compatibly, it is given a new operation rather than imposed on
an existing one — and only where even that proves impossible would a new version be created, served
alongside version 1 under its own prefix rather than in place of it.
Anything that is ever withdrawn is announced first, dated in the changelog, and left in place for at least twelve months afterwards.
This policy covers the published API — the operations described in the version 1 OpenAPI document at
/openapi/v1.json, which are the operations reachable with a client id and
secret. That document is the contract; this page describes how it is allowed to change.
One endpoint sits outside the prefix by design: POST /apiauth, which exchanges your credentials for
an access token. Issuing a token is the authentication mechanism the contract rests on rather than
part of the contract itself, and it is shared by every version — so a future version would not give
you a second token endpoint or a different way to authenticate.
It does not cover the Recruso web application or the endpoints behind it, which are not a published contract and are not intended for integration. It does not cover the wording of error messages, the contents of the reference lists, or the documentation site itself. Each of those is addressed below.
What we guarantee
Section titled “What we guarantee”Version 1 will not break. For as long as version 1 is published, Recruso will not:
- remove or rename an endpoint, a request field, or a response field
- change the type of an existing field, or the meaning of the data in it
- make an optional request field required, or add a new required request field
- tighten validation so that a request which succeeds today would be rejected
- change the success status code of an operation, or the shape of a paged response
- change what an existing operation does on the server
Behaviour is part of the contract, not just the schema. An operation’s observable effect is covered by the guarantee above even where no schema describes it. A deletion that can be reversed today will not quietly become one that cannot; an operation that leaves related records untouched will not begin cascading; a call that is safe to retry will not stop being safe. Where Recruso needs genuinely different behaviour, it will appear as a new operation with its own name, and the existing one will be left alone.
Additive changes can appear at any time, without notice. New endpoints, new optional fields on a request, and new fields on a response are not breaking changes and are released as they are ready. Your integration must tolerate them — see What this asks of you below.
New reference values are data, not contract changes. The lists behind /reference/*, and an
agency’s own configurable lookups, gain entries as the business changes — a new nationality, a new
worker type, a new compliance document type. The API deliberately describes these as identifiers
rather than as fixed sets of values, precisely so that adding one cannot break you. A new entry
appearing in a list is normal operation and is not announced.
Deprecation is dated and published. If an endpoint or a field is to be withdrawn, it is marked deprecated in the OpenAPI document and recorded in the changelog with the date it was deprecated, the earliest date it may be removed, and what to use instead. It keeps working unchanged throughout that period.
A new version would run alongside this one. Should a change ever prove impossible to make compatibly, the successor is published as a separate version at its own address. Version 1 continues to be served for at least twelve months after that, under this same policy.
What we do not guarantee
Section titled “What we do not guarantee”Stating these plainly is what makes the guarantees above worth relying on.
- Error message wording is not a contract. The
titleanddetailof an error can change at any time. Branch on the HTTP status code. See Errors. - The contents of reference and lookup lists are not fixed. Entries can be added, and an agency can change its own configurable lists at any time. Read them from the API rather than hard-coding them.
- The order of items in a collection is not guaranteed unless the operation documents an order or accepts a sort parameter.
- Undocumented behaviour is not covered. A field that is not in the OpenAPI document, or an observed detail that the documentation does not state, can change without notice.
- No date is committed for a version 2, and no roadmap is published. Nothing on this page should be read as one being planned.
- Urgent security fixes are excepted. Where a change is required to close a security or data protection risk, Recruso may make it without the notice period below, and will publish it in the changelog as soon as it is safe to do so. This is the only exception to the guarantees above.
- This policy covers the contract, not availability. There is no SLA on this API. See Security.
Notice periods
Section titled “Notice periods”| Change | Notice |
|---|---|
| A new endpoint, or a new optional field | None — released when ready |
| A new entry in a reference or lookup list | None — this is data, not a contract change |
| An endpoint or field marked deprecated | Published in the changelog on the day it is deprecated |
| Removing a deprecated endpoint or field | At least 12 months after it was deprecated |
| Withdrawing version 1 after a successor is published | At least 12 months after the successor |
| An urgent security or data protection fix | As much as is safe to give, and possibly none |
Twelve months is a minimum, not a target. Nothing has been deprecated to date.
How you will be told
Section titled “How you will be told”Changes are published in the API changelog, which is the authoritative record. A deprecation is also marked in the OpenAPI document itself, so it is visible in the API reference and to any tooling that reads the specification.
Recruso does not hold a technical contact address for an integration — an API app carries a name and the Recruso user who owns it, not a developer’s address. If you maintain an integration, check the changelog periodically rather than relying on being contacted directly.
What this asks of you
Section titled “What this asks of you”The guarantees above only hold if your integration is built to accept additive change. Two habits matter more than any others:
- Ignore fields you do not recognise. A response gaining a field must not break your client. Most JSON libraries do this by default; strict schema validation, generated clients configured to reject unknown properties, and tests asserting exact response equality all defeat it. This is the most common way an integration breaks on a change that was not breaking.
- Treat reference values as open sets. Look identifiers up rather than hard-coding them, and make sure an unfamiliar value degrades gracefully instead of throwing.
Beyond those: send only the fields you mean to set, branch on status codes rather than on error text, and do not depend on the order of a collection you did not ask to have sorted.
Contact and escalation
Section titled “Contact and escalation”Contact Recruso support at support@recruso.co.uk with any question about a published change, a deprecation, or a migration. If a change has broken an integration of yours, say so explicitly — that is treated as an incident rather than a support question.
Effective date: 12 September 2026