Skip to content
Recruso API

Create a cost centre

POST
/v1/branches/{branchId}/cost-centres
curl --request POST \
  --url https://api2.recruso.co.uk/v1/branches/1/cost-centres \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "branchId": 4, "costCentreName": "Warehouse Operatives", "sageDepartmentId": 21, "nominalCode": 4001 }'

Creates a cost centre under a branch. Only costCentreName is required; sageDepartmentId and nominalCode are the optional accounting fields.

The name must be unique within the branch — the same name may be reused in a different branch. A clash with an active cost centre returns 400.

A clash with a deleted cost centre returns 409 instead, because the underlying unique constraint covers deleted rows too. The 409 body carries the deleted record’s costCentreId, so you can either call RestoreCostCentre on it or pick a different name.

A branch outside your agency or outside your accessible-branch list returns 404.

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

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
branchId
required
integer format: int32

The branchId path parameter

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

A new cost centre under a branch. The owning agency comes from your credentials, so there is no owner field.

object
branchId

The branch to create the cost centre under. Bound from the route, not the body — the value in the URL is the one that applies.

integer format: int16
Example
4
costCentreName

The cost centre name. Required, up to 50 characters, and unique among the branch’s cost centres including deleted ones: a clash with an active one returns 400, a clash with a deleted one returns 409. Leading and trailing whitespace is trimmed.

string
Example
Warehouse Operatives
sageDepartmentId

The cost centre’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
21
nominalCode

The nominal (general-ledger) code this cost centre posts against.

integer format: int64
nullable
Example
4001

Responses

Section titled “Responses”

201

Section titled “201”

Created

Media typeapplication/json

The newly created cost centre.

object
costCentreId

The identifier allocated to the new cost centre. Unique within the agency, not within the branch. It is also the id in the Location header.

integer format: int16
branchId

The branch the cost centre was created under, taken from the route.

integer format: int16
costCentreName

The cost centre name, trimmed. Unique among the branch’s cost centres, deleted ones included.

string
sageDepartmentId

The cost centre’s Sage department. The parent branch carries a sageDepartmentId of its own; which one a posting uses is decided by the Sage integration, not by this endpoint.

integer format: int32
nullable
nominalCode

The nominal (general-ledger) code this cost centre posts against.

integer format: int64
nullable
Example
{
  "costCentreId": 31,
  "branchId": 4,
  "costCentreName": "Warehouse Operatives",
  "sageDepartmentId": 21,
  "nominalCode": 4001
}

400

Section titled “400”

Bad Request

Media typeapplication/problem+json
object
type
string
nullable
title
string
nullable
status
integer format: int32
nullable
detail
string
nullable
instance
string
nullable
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

401

Section titled “401”

Unauthorized

Media typeapplication/problem+json
object
type
string
nullable
title
string
nullable
status
integer format: int32
nullable
detail
string
nullable
instance
string
nullable
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

403

Section titled “403”

Forbidden

Media typeapplication/problem+json
object
type
string
nullable
title
string
nullable
status
integer format: int32
nullable
detail
string
nullable
instance
string
nullable
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

404

Section titled “404”

Not Found

Media typeapplication/problem+json
object
type
string
nullable
title
string
nullable
status
integer format: int32
nullable
detail
string
nullable
instance
string
nullable
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

409

Section titled “409”

Conflict

Media typeapplication/json

Returned with 409 when a cost centre name is already held by a deleted cost centre in the same branch. Restore that record or choose a different name.

object
costCentreId

The identifier of the deleted cost centre holding the name. Pass it to RestoreCostCentre to bring that record back instead of creating a new one.

integer format: int16
message

A human-readable explanation of the conflict. Diagnostic text, not a stable machine-readable code — branch on the 409 status and costCentreId instead.

string
Example
{
  "costCentreId": 31,
  "message": "A cost centre with this name was previously deleted for this branch."
}