Update a branch

PUT

/v1/branches/{id}

const url = 'https://api2.recruso.co.uk/v1/branches/1';
const options = {
  method: 'PUT',
  headers: {Authorization: '<Authorization>', 'Content-Type': 'application/json'},
  body: '{"branchLocation":"Manchester Central","address1":"Unit 7, Ashton House","address2":"14 Deansgate","town":"Manchester","county":"Greater Manchester","postcode":"M3 2BW","country":"United Kingdom","telephone1":"0161 496 0114","telephone2":"0161 496 0115","mobile":"07700 900432","fax":"0161 496 0116","email":"manchester@example-recruitment.co.uk","website":"https://www.example-recruitment.co.uk","sageDepartmentId":21,"clientName":"example","agencyNameForEmail":"Example Recruitment (Manchester)","displayInSelfRegistration":true}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PUT \
  --url https://api2.recruso.co.uk/v1/branches/1 \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "branchLocation": "Manchester Central", "address1": "Unit 7, Ashton House", "address2": "14 Deansgate", "town": "Manchester", "county": "Greater Manchester", "postcode": "M3 2BW", "country": "United Kingdom", "telephone1": "0161 496 0114", "telephone2": "0161 496 0115", "mobile": "07700 900432", "fax": "0161 496 0116", "email": "manchester@example-recruitment.co.uk", "website": "https://www.example-recruitment.co.uk", "sageDepartmentId": 21, "clientName": "example", "agencyNameForEmail": "Example Recruitment (Manchester)", "displayInSelfRegistration": true }'

Replaces the mutable details of a branch: name, address, contact details, Sage department, and the self-registration settings. This is a full replacement — a field omitted from the request is written as null, not left at its current value, so send the complete object.

branchLocation is required and must stay unique across the agency’s branches; a clash with another branch returns 400. Deleted branches keep their names, so a clash with one of those is rejected too. A branch outside your agency, already deleted, or not in your accessible-branch list returns 404.

Access. Requires a client-credentials access token. Tokens issued through the interactive user login are rejected.

Authorizations

Bearer

Parameters

Path Parameters

required

integer format: int32

The id path parameter

Request Body^required

application/json

The replacement state of a branch. This is a full replacement, not a merge: any optional field you omit is written as null rather than left alone, so send the complete object. The branch is identified by the route id; it cannot be moved to another agency.

object

branchLocation

The branch name. Required, up to 50 characters, and unique across the agency’s branches — a name held by another branch returns 400. Leading and trailing whitespace is trimmed.

string

Example

Manchester Central

address1

First line of the branch address. Up to 50 characters.

string

nullable

Example

Unit 7, Ashton House

address2

Second line of the branch address. Up to 50 characters.

string

nullable

Example

14 Deansgate

town

Town or city of the branch address. Up to 255 characters.

string

nullable

Example

Manchester

county

County of the branch address. Up to 255 characters.

string

nullable

Example

Greater Manchester

postcode

Postcode of the branch address. Up to 10 characters.

string

nullable

Example

M3 2BW

country

Country of the branch address. Up to 255 characters.

string

nullable

Example

United Kingdom

telephone1

Primary contact telephone number. Up to 50 characters; the format is not validated.

string

nullable

Example

0161 496 0114

telephone2

Secondary contact telephone number. Up to 50 characters.

string

nullable

Example

0161 496 0115

mobile

Mobile contact number. Up to 50 characters.

string

nullable

Example

07700 900432

fax

Fax number. Up to 50 characters.

string

nullable

Example

0161 496 0116

email

Contact email address for the branch. Up to 100 characters; stored as given and not validated as an email address.

string

nullable

Example

manchester@example-recruitment.co.uk

website

Website address for the branch. Up to 255 characters.

string

nullable

Example

https://www.example-recruitment.co.uk

sageDepartmentId

The branch’s Sage department. Not verified against Sage by this endpoint — an unknown department is accepted here and fails later at posting time.

integer format: int32

nullable

Example

clientName

Up to 70 characters.

string

nullable

agencyNameForEmail

The agency name used as the sender identity on emails sent from this branch. Up to 100 characters.

string

nullable

Example

Example Recruitment (Manchester)

displayInSelfRegistration

Whether the branch is offered as a choice when a worker self-registers. Omitted means null, not false.

boolean

nullable

Example

true

Responses

200

application/json

The branch as it stands after the update.

object

branchId

The branch’s identifier. Use this on the cost-centre endpoints as branchId.

integer format: int16

branchLocation

The branch name. Unique across the agency’s branches, and the field branches are ordered by in ListBranches.

string

address1

First line of the branch address.

string

nullable

address2

Second line of the branch address.

string

nullable

town

Town or city of the branch address.

string

nullable

county

County of the branch address.

string

nullable

postcode

Postcode of the branch address.

string

nullable

country

Country of the branch address.

string

nullable

telephone1

Primary contact telephone number for the branch.

string

nullable

telephone2

Secondary contact telephone number for the branch.

string

nullable

mobile

Mobile contact number for the branch.

string

nullable

fax

Fax number for the branch.

string

nullable

email

Contact email address for the branch.

string

nullable

website

Website address for the branch.

string

nullable

sageDepartmentId

The branch’s Sage department. Cost centres carry a sageDepartmentId of their own; which one a posting uses is decided by the Sage integration, not by this endpoint.

integer format: int32

nullable

clientName

string

nullable

agencyNameForEmail

The agency name used as the sender identity on emails sent from this branch.

string

nullable

displayInSelfRegistration

Whether the branch is offered as a choice when a worker self-registers.

boolean

nullable

modifiedBy

The Recruso user who last changed the branch, as a tblUsers user id rendered as a string. Set to the user behind your API app by this call.

string

nullable

modifiedOn

The date the branch was last changed, in UK local time (GMT/BST) — not UTC. Set to the date of this call; the underlying column stores a date, so the time is always midnight.

string format: date-time

nullable

Example

{
  "branchId": 4,
  "branchLocation": "Manchester Central",
  "address1": "Unit 7, Ashton House",
  "address2": "14 Deansgate",
  "town": "Manchester",
  "county": "Greater Manchester",
  "postcode": "M3 2BW",
  "country": "United Kingdom",
  "telephone1": "0161 496 0114",
  "telephone2": "0161 496 0115",
  "mobile": "07700 900432",
  "fax": "0161 496 0116",
  "email": "manchester@example-recruitment.co.uk",
  "website": "https://www.example-recruitment.co.uk",
  "sageDepartmentId": 21,
  "agencyNameForEmail": "Example Recruitment (Manchester)",
  "displayInSelfRegistration": true,
  "modifiedBy": "87",
  "modifiedOn": "2026-08-14T00:00:00"
}

400

Bad Request

application/problem+json

object

type

string

nullable

title

string

nullable

status

integer format: int32

nullable

detail

string

nullable

instance

string

nullable

Example^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

401

Unauthorized

application/problem+json

object

type

string

nullable

title

string

nullable

status

integer format: int32

nullable

detail

string

nullable

instance

string

nullable

Example^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

403

Forbidden

application/problem+json

object

type

string

nullable

title

string

nullable

status

integer format: int32

nullable

detail

string

nullable

instance

string

nullable

Example^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

404

Not Found

application/problem+json

object

type

string

nullable

title

string

nullable

status

integer format: int32

nullable

detail

string

nullable

instance

string

nullable

Example^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

Update a branch

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Responses

200

Example

400

Examplegenerated

401

Examplegenerated

403

Examplegenerated

404

Examplegenerated

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated