Clients

Recruiting for client companies as a staffing agency.

A client is the company you recruit for. If you are an agency, this is the half of the model that connects a role to the company it was opened for.

Does your organisation have clients?

Two shapes of organisation use this API.

	Hires for itself	Staffing agency
Who the role is for	The organisation	A client company
`client_id` on a role	Always absent	The client
`/v1/clients`	`403 not_a_staffing_organisation`	Works

The 403 is deliberate. An empty list would read as "no clients yet" and have you build a picker for a product that has none.

If you are integrating for an agency and omit client_id, nothing errors. The role is created with no client, and it will not appear in that client's portal or be attributable in placement reporting. Set it at creation.

Create a client, then a role for it

curl -X POST https://hiring-api.experthire.cloud/v1/clients \
  -H "Authorization: Bearer $EH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Northwind Trading", "industry": "Logistics"}'

Still a placeholder: $EH_SECRET_KEY. Add it under Your values above.

201Response

{
  "object": "client",
  "id": "8c1f0b47-3a2e-4d19-9f77-2b6c5e1d0a34",
  "name": "Northwind Trading",
  "industry": "Logistics",
  "status": "active",
  "blacklisted": false,
  "archived": false,
  "livemode": true,
  "created_at": 1767229200
}

Then pass the id as client_id on POST /v1/jobs. GET /v1/jobs returns it back, omitted when the role has none.

Rules worth knowing

Names are unique per environment. A sandbox client called Northwind does not block a live one, and the reverse, so you can build the whole flow against a test key. A duplicate inside one environment returns client_name_exists.

A blacklisted client refuses new work. Creating a role for one, or re-pointing a role at one, returns client_blacklisted. Existing roles are untouched: blacklisting stops future work rather than erasing history. It is independent of status, so a blacklisted client is usually still active.

Blacklist, archive and status are read-only here. They are relationship decisions made in the recruiter application.

Commercial terms are not on this contract. Fees, billing model, tax and payment terms are yours, not the integration's, and are configured in the application.

To detach a role, PATCH /v1/jobs/{id} with client_id set to the nil UUID.

Roles and assessments are in Assessments.

Does your organisation have clients?

Create a client, then a role for it

Rules worth knowing

Next