Your API key

Create one in the portal under API keys.

Browse the API

API reference

Departments

The department tree, used to scope rules and campaigns.

4 endpoints

GET/api/v1/departments

List departments

Every department, with its parent and current head count.

departments:read

This endpoint takes no parameters beyond the URL itself.

Example response

json

{
  "departments": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Operations",
      "parent_id": null,
      "parent_name": null,
      "user_count": 12
    }
  ],
  "total": 4
}

Copy and paste

curl -X GET "https://api.usesigned.co.uk/api/v1/departments" \
  -H "X-API-Key: $SIGNED_API_KEY"

POST/api/v1/departments

Create a department

Adds a department. Pass a parent_id to nest it.

departments:write

Parameters

JSON body

nameRequired
stringDepartment name.
up to 255 characters
example: "Operations"
parent_idOptional
stringDepartment to nest this one under.
uuid

Example request body

json

{
  "name": "Operations",
  "parent_id": null
}

Example response

json

{
  "department": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Operations",
    "parent_id": null
  }
}

Copy and paste

curl -X POST "https://api.usesigned.co.uk/api/v1/departments" \
  -H "X-API-Key: $SIGNED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Operations","parent_id": null}'

PATCH/api/v1/departments/{id}

Update a department

Renames a department or moves it in the tree. A department cannot be its own parent.

departments:write

Parameters

In the path

idRequired
stringDepartment ID.
uuid

JSON body

nameOptional
stringDepartment name.
up to 255 characters
parent_idOptional
stringDepartment to nest this one under, or null to move it to the top level.
uuid

Example request body

json

{
  "name": "Operations and Delivery"
}

Example response

json

{
  "department": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Operations and Delivery"
  }
}

Copy and paste

curl -X PATCH "https://api.usesigned.co.uk/api/v1/departments/{id}" \
  -H "X-API-Key: $SIGNED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Operations and Delivery"}'

DELETE/api/v1/departments/{id}

Delete a department

Deletes a department. People in it are moved to no department, child departments move up a level, and campaigns targeting it are switched off.

departments:write

Parameters

In the path

idRequired
stringDepartment ID.
uuid

Example response

json

{
  "deleted": true
}

Copy and paste

curl -X DELETE "https://api.usesigned.co.uk/api/v1/departments/{id}" \
  -H "X-API-Key: $SIGNED_API_KEY"

Worth knowing

Refused while a rule targets the department, so you can see what would break first.