Quickstart

Time: about five minutes. Two calls, ending in a 200 carrying your own agency’s data.

Before you start

One set of credentials: an API app’s client id and client secret, issued from the Developer Console. Whoever administers your Recruso account creates the app there and mints the secret; the secret is shown once.

You do not need a Recruso user account of your own, and you never send a password to this API.

You will also need a way to make HTTP requests. The examples below use curl; the playground will run the same calls from your browser against your own credentials.

These calls hit live data

There is no sandbox. Every request below runs against production, though both are reads and change nothing. See Environments and base URLs before you start writing.

1. Exchange your client credentials

The client id and secret go in the body — not in the header, and not as basic auth.

curl -sS -X POST https://api2.recruso.co.uk/apiauth \
-H 'Content-Type: application/json' \
-d '{
      "clientId": "42.0f7b9c2e-…",
      "clientSecret": "…",
      "grantType": "client_credentials"
    }'

{ "accessToken": "eyJhbGciOi…", "expiresIn": 3600, "tokenType": "Bearer" }

This accessToken is the one every business call needs. expiresIn is its lifetime in seconds — read it rather than assuming a value.

2. Make your first call

curl -sS https://api2.recruso.co.uk/v1/branches \
-H 'Authorization: Bearer <accessToken from step 1>'

A 200 with your agency’s branches:

{
  "branches": [
    { "branchId": 4, "branchLocation": "Manchester Central", "town": "Manchester" }
  ]
}

That is a successful integration. Everything else is more of the same call with a different path.

What just happened

You exchanged a credential belonging to an API app for a token, and called the API with it. The token belongs to the app rather than to any person, which is why an integration can be revoked without touching anyone’s user account.

Notice what step 2 never sent: an agency identifier. No business endpoint takes one. Your credentials are bound to a single agency, and every response is scoped to it by the database rather than by the API — which is also why a record belonging to another agency comes back as a 404 rather than a 403. See Multi-tenancy and data isolation.

The prefix on your client id is not an exception to that. It is part of an opaque credential identifier, decides nothing about access, and changing any of it only stops the exchange working.

Request a new access token when the current one expires, not on every call. /apiauth is rate limited, so a client that re-authenticates before every request will start getting 429.

If it did not work

• 400 on step 1 — the request is the wrong shape, and nothing was looked up: check the client id is the whole string as issued, that clientSecret is not empty, and that grantType is exactly client_credentials. The body names the offending field.
• 401 on step 1 — the client id or secret is wrong, the app is inactive, the credential has been revoked or has expired, your address is outside the app’s IP allow-list, or the Recruso user the app belongs to has been disabled. All of these return the same empty 401 on purpose; check the app in the Developer Console.
• 429 on step 1 — too many exchanges from one address. Cache the token rather than re-minting it.
• 401 on step 2 — the token is missing, malformed, or has expired. Exchange again.
• An empty branches array — a valid response, not a failure. Your agency’s accessible-branch list may be empty; check it in the Recruso UI.

Endpoints

Method	Path	What it does
POST	/apiauth	Exchange client credentials for an access token
GET	/v1/branches	List branches

Where to go next

• Authentication — token lifetime and handling credentials safely.
• Responses and pagination — the conventions every endpoint follows.
• Domain model — what else there is to call.