Skip to content
API reference
/
/
Create a job title

Create a job title

Request

Adds a role under the functional area named in the URL. The parent is taken from the URL, so it is not a body field and cannot be set by sending one.

code has to be unique across the whole account, not just within this functional area, and is stored in upper case whatever case it is sent in.

The created role comes back without deleted_at, which reading it includes. Everything else matches the read shape.

Security
default
Path
functionalarea_idintegerrequired

The ID of the functional area.

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 role, unique across the account rather than just within the group. Letters, numbers, dashes and underscores only - spaces and punctuation are rejected. Stored and returned in upper case whatever case it is sent in.

descriptionstring

What the role involves, as HTML. Shown to volunteers alongside the role. Sanitised on the way out, so unsupported markup will not be returned as sent.

training_idsArray of integers

The IDs of the training modules assigned to anyone who takes on this role. 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/{functionalarea_id}/jobtitle' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Rosterfy-Platform: admin' \
  -d '{
    "name": "Information Desk Attendant",
    "frontend_name": "Information Desk Attendant",
    "code": "INFODESK",
    "description": "<p>Answers visitor questions at the information desk.</p>",
    "training_ids": [
      1
    ]
  }'

Responses

Bodyapplication/json
objectobject
niceobject
relationsobject
permissionsobject
Response
{
  "object": {
    "id": 1,
    "headcount_functional_area_id": 1,
    "name": "Information Desk Attendant",
    "frontend_name": "Information Desk Attendant",
    "code": "INFODESK",
    "description": "<p>Answers visitor questions at the information desk.</p>",
    "training_ids": [ … ],
    "deleted_at": null,
    "created_at": "2026-06-09T05:36:16.000000Z",
    "updated_at": "2026-06-09T05:36:16.000000Z",
    "uuid": "e17404de-d3db-4e85-81ee-4552d19da8c4"
  },
  "nice": {
    "rrn": "rrn:local:20101:job_title:1",
    "functional_area_name": "Guest Services"
  },
  "relations": {
    "functional_area": { … }
  },
  "permissions": {
    "read": true,
    "update": true,
    "delete": true
  }
}