Skip to content
API reference
/
/
Create a functional area

Create a functional area

Request

Sets up a new group to organise the workforce into, with a target headcount and, optionally, a set of conditions that keep its membership up to date on its own.

code has to be unique within the account and is stored in upper case whatever case it is sent in. Switching auto_update_mode on makes rules mandatory - a create that turns it on without well-formed conditions is rejected.

The created group comes back with only the fields that were set on it, not the full record that reading it returns: anything left to its stored default is absent rather than present and defaulted. Read the group back if you need its complete state.

Security
default
Headers
Rosterfy-Platformstring
Bodyapplication/jsonrequired
namestringrequired

The name administrators see. Required.

frontend_namestringrequired

The name volunteers see in the portal. Required, and shown in place of name to anyone without administrator access, so it is worth setting even when the two match.

codestringrequired

A short reference for the group, unique within the account. Letters, numbers, dashes and underscores only - spaces and punctuation are rejected. Stored and returned in upper case whatever case it is sent in.

headcount_functional_area_type_idinteger

The ID of the group type to file this group under. Optional; omit or send null to leave the group untyped.

targetinteger

How many people this group is aiming to have. 0 means no limit. Cannot be negative.

auto_update_modeinteger

Whether membership is maintained automatically from rules, and in which direction: 0 off, 1 add and remove, 2 add only, 3 remove only. When this is anything other than 0, rules must be present and well formed or the request is rejected.

rulesArray of objects

The membership conditions used when auto_update_mode is on, as a list of condition objects built from the account's own user fields. Each condition names a field, a comparison and a value. Build these in the admin console and send back what it produces rather than composing them by hand - the set of addressable fields is specific to the account. This field is cleared whenever it is omitted, so resend it on every update to a group that has automatic updating switched on; omitting it there clears the conditions and the request is rejected.

training_idsArray of integers

The IDs of the training modules assigned to anyone who joins this group. Replaces the whole list rather than adding to it, so send every module you want kept. Omitting the field leaves the stored list untouched.

curl -i -X POST \
  https://developer.rosterfy.com/_mock/api-docs/openapi/api/v2/headcount/functionalarea \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Rosterfy-Platform: admin' \
  -d '{
    "name": "Guest Services",
    "frontend_name": "Guest Services",
    "code": "GUESTSERVICES",
    "headcount_functional_area_type_id": 1,
    "target": 50,
    "auto_update_mode": 0,
    "rules": [],
    "training_ids": [
      1
    ]
  }'

Responses

Bodyapplication/json
objectobject
niceobject
relationsobject
permissionsobject
Response
{
  "object": {
    "rules": [],
    "auto_update_mode": 0,
    "name": "Guest Services",
    "frontend_name": "Guest Services",
    "code": "GUESTSERVICES",
    "headcount_functional_area_type_id": 1,
    "target": 50,
    "training_ids": [ … ],
    "account_id": 20101,
    "updated_by": 1234,
    "uuid": "428585a9-f02d-4ca8-8383-35b1f8433f1c",
    "updated_at": "2026-06-09T05:36:16.000000Z",
    "created_at": "2026-06-09T05:36:16.000000Z",
    "id": 1
  },
  "nice": {
    "rrn": "rrn:local:20101:functional_area:1"
  },
  "relations": {},
  "permissions": {
    "read": true,
    "update": true,
    "delete": true
  }
}