Create a branch

POST

/v1/branches

const url = 'https://api2.recruso.co.uk/v1/branches';
const options = {
  method: 'POST',
  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 POST \
  --url https://api2.recruso.co.uk/v1/branches \
  --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 }'

Creates a branch under your own agency. Only branchLocation is required; every other field is optional and may be filled in later with UpdateBranch.

branchLocation must be unique across the agency’s branches — a name that is already in use returns 400. A name belonging to a deleted branch is also rejected, because branches are only ever soft-deleted and a deleted branch keeps its name.

The agency is taken from your credentials, so there is no owner field on the request. The new branch is added to the accessible branches of the user behind your API app, so you can read it back straight away.

On success the response carries the new branchId and a Location header pointing at GetBranchById.

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

Authorizations

Bearer

Request Body^required

application/json

A new branch. Only branchLocation is required; everything else may be filled in later with UpdateBranch. The owning agency comes from your credentials, so there is no owner field.

object

branchLocation

The branch name. Required, up to 50 characters, and unique across the agency’s branches — a name already in use 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

201

Created

application/json

The newly created branch. ModifiedBy and ModifiedOn are absent because the branch has not been changed yet — read them back from GetBranchById after the first update.

object

branchId

The identifier allocated to the new branch. Use this on the cost-centre endpoints as branchId. It is also the id in the Location header.

integer format: int16

branchLocation

The branch name, trimmed. Unique across the agency’s branches.

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

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
}

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"
}

Create a branch

Authorizations

Request Bodyrequired

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Responses

201

Example

400

Examplegenerated

401

Examplegenerated

403

Examplegenerated

Request Body^required

Example^generated

Example^generated

Example^generated