{ "openapi": "3.1.0", "info": { "title": "Rosterfy API Documentation", "description": "A guide to using the Rosterfy REST API.", "version": "2.0.0" }, "servers": [ { "url": "https://{account}.{domain}", "description": "Your Rosterfy account", "variables": { "account": { "default": "example", "description": "Your account's subdomain - the first part of the address you sign in to Rosterfy on." }, "domain": { "default": "rosterfy.com", "description": "The rest of that address. rosterfy.com unless your account is on a regional deployment, in which case use the domain you sign in on." } } } ], "tags": [ { "name": "Authentication", "description": "" }, { "name": "Me Module", "description": "" }, { "name": "User Module", "description": "" }, { "name": "Account Module", "description": "" }, { "name": "Blog Module", "description": "" }, { "name": "Certificate Module", "description": "" }, { "name": "Training Module", "description": "" }, { "name": "Headcount Module", "description": "" }, { "name": "Inventory Module", "description": "" }, { "name": "Report Module", "description": "" }, { "name": "Role Offer Module", "description": "" }, { "name": "Event Module", "description": "" }, { "name": "Shift Module", "description": "" }, { "name": "Reward Point", "description": "" }, { "name": "Automatic Rostering", "description": "" }, { "name": "Utilities", "description": "" }, { "name": "Form Module", "description": "" } ], "components": { "securitySchemes": { "default": { "type": "http", "scheme": "bearer", "description": "See the Authentication section for retrieving a Bearer token." } } }, "security": [ { "default": [] } ], "paths": { "/api/v2/oauth/token": { "post": { "summary": "Request an access token", "operationId": "requestAnAccessToken", "tags": [ "Authentication" ], "security": [], "description": "Exchanges a set of client credentials and a user's sign-in details for an access token.\nEvery other endpoint in this API expects the result in an\n`Authorization: Bearer ` header, so this is the first call an integration\nmakes.\n\nYou need a `client_id` and `client_secret` before you can call it. The client id is the\n`id` of one of your personal access clients - see the listing endpoint below. Rosterfy\nissues the matching secret; no endpoint returns it.\n\nThe token is issued for the user whose `username` and `password` you send, and it carries\nexactly that user's access. Use a dedicated integration user rather than a person's own\nlogin, so the integration keeps working when people come and go and so its activity is\ndistinguishable in the audit trail.\n\n`expires_in` is the lifetime in seconds - 2592000, or 30 days. The `refresh_token` returned\nalongside it lasts longer than the access token and can be exchanged for a new one by\ncalling this endpoint again with `grant_type` set to `refresh_token`, sending\n`refresh_token` in place of `username` and `password`. Refresh before the access token\nexpires rather than after; once it has lapsed there is nothing to refresh and you are back\nto a full credential exchange.\n\nThe body may be sent as JSON or as `application/x-www-form-urlencoded`. Both are accepted\nand both return JSON.\n\nTreat the access token as a credential in its own right. It is a bearer token: anything\nholding it has the user's access for as long as it lives, so store it the way you would\nstore the password you exchanged for it, and never put it in a URL or a log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "grant_type", "client_id", "client_secret" ], "properties": { "grant_type": { "type": "string", "enum": [ "password", "refresh_token" ], "description": "The exchange being performed. Send `password` for the initial exchange, or `refresh_token` to renew an existing token.", "examples": [ "password" ] }, "client_id": { "type": "integer", "description": "The id of the personal access client the credentials belong to.", "examples": [ 1234 ] }, "client_secret": { "type": "string", "description": "The secret issued with that client.", "examples": [ "{YOUR_CLIENT_SECRET}" ] }, "username": { "type": "string", "description": "The email address of the user the token is issued for. Required when `grant_type` is `password`.", "examples": [ "integration@example.com" ] }, "password": { "type": "string", "description": "That user's password. Required when `grant_type` is `password`.", "examples": [ "{YOUR_PASSWORD}" ] }, "refresh_token": { "type": "string", "description": "The refresh token from an earlier exchange. Required when `grant_type` is `refresh_token`, and ignored otherwise.", "examples": [ "{YOUR_REFRESH_TOKEN}" ] }, "scope": { "type": "string", "description": "Optional. Omit it, or send `*`, to receive a token carrying the whole of the user's access.", "examples": [ "*" ] } } }, "examples": { "password": { "summary": "Initial exchange", "value": { "grant_type": "password", "client_id": 1234, "client_secret": "{YOUR_CLIENT_SECRET}", "username": "integration@example.com", "password": "{YOUR_PASSWORD}", "scope": "*" } }, "refresh": { "summary": "Renewing a token", "value": { "grant_type": "refresh_token", "client_id": 1234, "client_secret": "{YOUR_CLIENT_SECRET}", "refresh_token": "{YOUR_REFRESH_TOKEN}", "scope": "*" } } } } } }, "responses": { "200": { "description": "A new access token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token_type": { "type": "string", "description": "Always `Bearer`. This is the scheme to use in the Authorization header.", "examples": [ "Bearer" ] }, "expires_in": { "type": "integer", "description": "Seconds until the access token expires.", "examples": [ 2592000 ] }, "access_token": { "type": "string", "description": "The token to send as `Authorization: Bearer `.", "examples": [ "{ACCESS_TOKEN}" ] }, "refresh_token": { "type": "string", "description": "Exchange this for a new access token before the current one expires.", "examples": [ "{REFRESH_TOKEN}" ] } } }, "examples": { "issued": { "summary": "Token issued", "value": { "token_type": "Bearer", "expires_in": 2592000, "access_token": "{ACCESS_TOKEN}", "refresh_token": "{REFRESH_TOKEN}" } } } } } }, "400": { "description": "The request is not a grant this endpoint can process - an unknown `grant_type`, or one whose required fields are missing.", "content": { "application/json": { "examples": { "unsupported_grant_type": { "summary": "Unknown grant type", "value": { "error": "unsupported_grant_type", "error_description": "The authorization grant type is not supported by the authorization server.", "hint": "Check that all required parameters have been provided", "message": "The authorization grant type is not supported by the authorization server." } } } } } }, "401": { "description": "The credentials were rejected. This covers both halves of the exchange - the client id and secret, and the user details - and does not say which was wrong.", "content": { "application/json": { "examples": { "invalid_credentials": { "summary": "Credentials rejected", "value": { "message": "Invalid credentials" } } } } } } } } }, "/api/v2/oauth/clients": { "get": { "summary": "List your personal access clients", "operationId": "listYourPersonalAccessClients", "description": "Returns the personal access clients registered against the authenticated user. A\npersonal access client is the `client_id` half of the credentials the token endpoint\nexchanges for an access token, and `id` here is that `client_id`.\n\nThe listing is scoped to the caller and to nobody else: it returns the clients that\ncaller registered, not every client in the account, and there is no parameter that\nwidens it. Clients that have been withdrawn are left out, so an entry disappearing from\nthis list means its credentials no longer work.\n\nThe response is a flat array. It carries no pagination envelope and takes no filter,\nsort or page parameters, so the whole set comes back in one call however many there are.\n\nNo client secret is returned, here or anywhere else in the API. Ask Rosterfy for the\nsecret that goes with a `client_id` you hold.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1234 ] }, "user_id": { "type": "integer", "examples": [ 1234 ] }, "name": { "type": "string", "examples": [ "Nightly roster export" ] }, "provider": { "type": [ "string", "null" ], "examples": [ null ] }, "redirect": { "type": "string", "examples": [ "https://example.com/oauth/callback" ] }, "personal_access_client": { "type": "boolean", "examples": [ true ] }, "password_client": { "type": "boolean", "examples": [ false ] }, "revoked": { "type": "boolean", "examples": [ false ] }, "created_at": { "type": "string", "examples": [ "2026-01-14T02:08:00.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-01-14T02:08:00.000000Z" ] } } }, "examples": [ [ { "id": 1234, "user_id": 1234, "name": "Nightly roster export", "provider": null, "redirect": "https://example.com/oauth/callback", "personal_access_client": true, "password_client": false, "revoked": false, "created_at": "2026-01-14T02:08:00.000000Z", "updated_at": "2026-01-14T02:08:00.000000Z" }, { "id": 1235, "user_id": 1234, "name": "Volunteer portal sync", "provider": null, "redirect": "https://example.com/oauth/callback", "personal_access_client": true, "password_client": false, "revoked": false, "created_at": "2026-02-03T09:41:17.000000Z", "updated_at": "2026-02-03T09:41:17.000000Z" } ] ] } } } } }, "tags": [ "Authentication" ] }, "post": { "summary": "Register a personal access client", "operationId": "registerAPersonalAccessClient", "description": "Registers a new personal access client against the authenticated user and returns it.\nThe `id` on the response is the `client_id` the token endpoint expects.\n\nThe client belongs to the caller. It is not shared with the rest of the account, and it\ncarries the caller's own access - a token issued through it can reach whatever that user\ncan reach, so register the client as the user whose access the integration should have.\n\n**The response does not include the client secret**, and no endpoint returns it\nafterwards. Ask Rosterfy for the secret that goes with the `client_id` this call\nreturns; until you have it, the client cannot complete a token exchange.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer", "examples": [ 1234 ] }, "name": { "type": "string", "examples": [ "Nightly roster export" ] }, "provider": { "type": [ "string", "null" ], "examples": [ null ] }, "redirect": { "type": "string", "examples": [ "https://example.com/oauth/callback" ] }, "personal_access_client": { "type": "boolean", "examples": [ true ] }, "password_client": { "type": "boolean", "examples": [ false ] }, "revoked": { "type": "boolean", "examples": [ false ] }, "updated_at": { "type": "string", "examples": [ "2026-01-14T02:08:00.000000Z" ] }, "created_at": { "type": "string", "examples": [ "2026-01-14T02:08:00.000000Z" ] }, "id": { "type": "integer", "examples": [ 1234 ] } }, "examples": [ { "user_id": 1234, "name": "Nightly roster export", "provider": null, "redirect": "https://example.com/oauth/callback", "personal_access_client": true, "password_client": false, "revoked": false, "updated_at": "2026-01-14T02:08:00.000000Z", "created_at": "2026-01-14T02:08:00.000000Z", "id": 1234 } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "A label for the client, shown wherever the client is listed. Use something that identifies the system that will hold the credentials, so a client can be recognised and withdrawn later without guesswork.", "examples": [ null ] }, "redirect": { "type": "string", "description": "The absolute URL an authorisation response is returned to. Required in practice: a request that omits it fails, so send a URL you control even when the integration never redirects a browser anywhere.", "examples": [ null ] } }, "required": [ "name", "redirect" ] } } } } } }, "/api/v2/user/me": { "get": { "summary": "Get current user", "operationId": "getCurrentUser", "description": "Returns everything a client needs about the signed-in user in a single call: who they are,\nwhat they are allowed to do, and how their experience should be configured. This is the\ncall to make immediately after authenticating.\n\n`user` is the profile itself, including any custom attributes the account has defined,\nwhich appear as `custom_*` keys alongside the standard ones. `nice` is the same data\nformatted for display - dates written out, phone numbers and addresses composed, coded\nvalues resolved to their labels - so a client can render fields without reimplementing the\naccount's formatting rules. `type` is the user type they belong to, which carries the\nshift limits and rules applied to them.\n\n`permissions` states what the user may do, as a flat map of permission keys to booleans. It\nis large for an administrator and short for an ordinary portal user, and the example below\nshows a representative selection rather than the full set. Test for the specific keys you\ncare about rather than iterating the map, and treat an absent key as not granted.\n`checkpoint` and `checkpoint_permissions` describe the onboarding stage the user has\nreached and what that stage unlocks. `settings` holds their personal preferences, such as\nlocale and timezone, which should be preferred over any account default.\n\nThe remaining keys are small signals: `socials` lists the social accounts linked to the\nprofile, `is_primary_account` says whether they are signed in to the account that owns\ntheir record rather than a related one, `has_account_roles` says whether they hold any\nadministrative role, and `messaging_user_id` is present only where messaging is enabled.\n\nBecause the response contains the caller's own personal data, treat it accordingly - do not\nlog it wholesale or cache it anywhere shared.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1234 ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "email": { "type": "string", "examples": [ "alex.example@example.com" ] }, "force_reset_password": { "type": "integer", "examples": [ 0 ] }, "password_expires_at": { "type": [ "string", "null" ], "examples": [ null ] }, "first_name": { "type": "string", "examples": [ "Alex" ] }, "middle_name": { "type": [ "string", "null" ], "examples": [ null ] }, "last_name": { "type": "string", "examples": [ "Example" ] }, "preferred_name": { "type": [ "string", "null" ], "examples": [ null ] }, "phone": { "type": "string", "examples": [ "au-200000000" ] }, "dob": { "type": "string", "examples": [ "1990-01-15" ] }, "picture": { "type": [ "string", "null" ], "examples": [ null ] }, "picture_status": { "type": "integer", "examples": [ 0 ] }, "is_subscribed": { "type": "integer", "examples": [ 0 ] }, "is_subscribed_transactional": { "type": "integer", "examples": [ 1 ] }, "is_unreachable": { "type": "integer", "examples": [ 0 ] }, "is_unreachable_sms": { "type": "integer", "examples": [ 0 ] }, "terms": { "type": "integer", "examples": [ 1 ] }, "rating": { "type": "string", "examples": [ "0.00" ] }, "shift_privacy": { "type": "integer", "examples": [ 1 ] }, "is_team_leader": { "type": "integer", "examples": [ 0 ] }, "email_verified": { "type": "integer", "examples": [ 0 ] }, "login_lockout_attempts": { "type": "integer", "examples": [ 0 ] }, "login_lockout_at": { "type": [ "string", "null" ], "examples": [ null ] }, "login_lockout_email_sent_at": { "type": [ "string", "null" ], "examples": [ null ] }, "last_login_at": { "type": "string", "examples": [ "2026-01-20T02:14:52.000000Z" ] }, "last_app_login_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "last_activated": { "type": [ "string", "null" ], "examples": [ null ] }, "from_source": { "type": [ "string", "null" ], "examples": [ null ] }, "delete_requested_at": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-01-05T01:32:57.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-01-20T01:42:50.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "interests": { "type": [ "string", "null" ], "examples": [ null ] }, "address": { "type": "object", "properties": { "iso": { "type": "string", "examples": [ "AUS" ] }, "region_code": { "type": "string", "examples": [ "VIC" ] }, "coordinates": { "type": "object", "properties": { "latitude": { "type": [ "string", "null" ], "examples": [ null ] }, "longitude": { "type": [ "string", "null" ], "examples": [ null ] } } }, "street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "city": { "type": "string", "examples": [ "Example City" ] }, "postcode": { "type": "string", "examples": [ "1000" ] }, "region": { "type": "string", "examples": [ "VIC" ] }, "country": { "type": "string", "examples": [ "AU" ] }, "latitude": { "type": [ "string", "null" ], "examples": [ null ] }, "longitude": { "type": [ "string", "null" ], "examples": [ null ] } } }, "rrn": { "type": "string", "examples": [ "rrn:local:20101:user:AAAABBBBCCCCDDDDEEEEFFFF" ] }, "age": { "type": "integer", "examples": [ 36 ] }, "checkpoint_id": { "type": "integer", "examples": [ 3 ] }, "type_id": { "type": "integer", "examples": [ 2 ] }, "eula_agreed": { "type": "boolean", "examples": [ false ] }, "qr_code": { "type": "string", "examples": [ "https://example.rosterfy.com/qr/qr-example.png" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:user:AAAABBBBCCCCDDDDEEEEFFFF" ] }, "family_id": { "type": [ "string", "null" ], "examples": [ null ] }, "has_family_members": { "type": "string", "examples": [ "No" ] }, "manages_family": { "type": "boolean", "examples": [ false ] }, "family_manager": { "type": "string", "examples": [ "No" ] }, "family_member": { "type": "string", "examples": [ "No" ] }, "is_family_member": { "type": "boolean", "examples": [ false ] }, "is_engaged": { "type": "string", "examples": [ "No" ] }, "is_engaged:raw": { "type": "boolean", "examples": [ false ] }, "last_engaged_at": { "type": [ "string", "null" ], "examples": [ null ] }, "last_engaged_at:raw": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:33 AM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "5:33 AM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "email_verified": { "type": "string", "examples": [ "No" ] }, "from_source": { "type": "string", "examples": [ "" ] }, "interests": { "type": [ "string", "null" ], "examples": [ null ] }, "interests:value": { "type": [ "string", "null" ], "examples": [ null ] }, "interests:array": { "type": [ "string", "null" ], "examples": [ null ] }, "is_subscribed_transactional": { "type": "string", "examples": [ "Yes" ] }, "is_team_leader": { "type": "string", "examples": [ "No" ] }, "last_login_at": { "type": "string", "examples": [ "Aug 10, 2026, 5:16 AM" ] }, "last_login_at__date": { "type": "string", "examples": [ "Aug 10, 2026" ] }, "last_login_at__time": { "type": "string", "examples": [ "5:16 AM" ] }, "last_login_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "last_login_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "last_login_at__dayofweek": { "type": "string", "examples": [ "Monday" ] }, "middle_name": { "type": "string", "examples": [ "" ] }, "picture_status": { "type": "string", "examples": [ "N/A" ] }, "picture_status:value": { "type": "integer", "examples": [ 0 ] }, "picture_status:array": { "type": "string", "examples": [ "N/A" ] }, "shift_privacy": { "type": "string", "examples": [ "Yes" ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:33 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:33 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "first_name": { "type": "string", "examples": [ "Alex" ] }, "last_name": { "type": "string", "examples": [ "Example" ] }, "preferred_name": { "type": "string", "examples": [ "" ] }, "dob": { "type": "string", "examples": [ "Jan 15, 1990" ] }, "dob__dayofweek": { "type": "string", "examples": [ "Monday" ] }, "is_subscribed": { "type": "string", "examples": [ "No" ] }, "terms": { "type": "string", "examples": [ "Yes" ] }, "name": { "type": "string", "examples": [ "Alex Example" ] }, "age": { "type": "integer", "examples": [ 36 ] }, "age_months": { "type": "string", "examples": [ "36 years, 0 months" ] }, "info": { "type": "string", "examples": [ "Alex Example (alex.example@example.com)" ] }, "preferred_first_name": { "type": "string", "examples": [ "Alex" ] }, "delete_requested": { "type": "boolean", "examples": [ false ] }, "updated_hours": { "type": "number", "examples": [ 1487.7417004144 ] }, "is_community_user": { "type": "boolean", "examples": [ false ] }, "timezone": { "type": "string", "examples": [ "UTC" ] }, "address": { "type": "string", "examples": [ "1 Example Street\nExample City\nVictoria\nAustralia\n1000" ] }, "address_oneline": { "type": "string", "examples": [ "1 Example Street, Example City, Victoria, Australia, 1000" ] }, "address.country": { "type": "string", "examples": [ "Australia" ] }, "address.country:raw": { "type": "string", "examples": [ "AUS" ] }, "phone": { "type": "string", "examples": [ "(+61) 200000000" ] }, "phone:raw": { "type": "string", "examples": [ "+61200000000" ] } } }, "type": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 2 ] }, "account_branding_id": { "type": [ "string", "null" ], "examples": [ null ] }, "name": { "type": "string", "examples": [ "Default" ] }, "code": { "type": "string", "examples": [ "default" ] }, "profile_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "training_ids": { "type": [ "string", "null" ], "examples": [ null ] }, "registration_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_limit": { "type": "integer", "examples": [ 0 ] }, "shift_max_time": { "type": [ "string", "null" ], "examples": [ null ] }, "max_shift_length": { "type": "integer", "examples": [ 0 ] }, "min_shift_length": { "type": "integer", "examples": [ 0 ] }, "min_consecutive_rest_time_per_week": { "type": "integer", "examples": [ 0 ] }, "max_work_days_per_week": { "type": "integer", "examples": [ 0 ] }, "gap_between_shifts": { "type": "integer", "examples": [ 0 ] }, "group_leader_attributes": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:33:39.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:33:39.000000Z" ] }, "uuid": { "type": "string", "examples": [ "0cdefc27-b599-4a15-a82f-18c11bb44803" ] } } }, "permissions": { "type": "object", "properties": { "admin": { "type": "boolean", "examples": [ true ] }, "event": { "type": "boolean", "examples": [ true ] }, "event:create": { "type": "boolean", "examples": [ true ] }, "event:read": { "type": "boolean", "examples": [ true ] }, "event:update": { "type": "boolean", "examples": [ true ] }, "event:delete": { "type": "boolean", "examples": [ true ] }, "user": { "type": "boolean", "examples": [ true ] }, "user:create": { "type": "boolean", "examples": [ true ] }, "user:read": { "type": "boolean", "examples": [ true ] }, "user:update": { "type": "boolean", "examples": [ true ] }, "user:delete": { "type": "boolean", "examples": [ true ] }, "training": { "type": "boolean", "examples": [ true ] }, "training:read": { "type": "boolean", "examples": [ true ] }, "report": { "type": "boolean", "examples": [ true ] }, "report:read": { "type": "boolean", "examples": [ true ] } } }, "checkpoint": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "user_checkpoint_type_id": { "type": [ "string", "null" ], "examples": [ null ] }, "name": { "type": "string", "examples": [ "Default" ] }, "label": { "type": "string", "examples": [ "default" ] }, "permissions": { "type": "object", "properties": { "all": { "type": "string", "examples": [ "1" ] } } }, "actions": { "type": "array", "examples": [ [] ] }, "is_inheritable": { "type": "integer", "examples": [ 0 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:33:39.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:34:24.000000Z" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:checkpoint:1" ] }, "content_id": { "type": "integer", "examples": [ 3 ] }, "account_name_path": { "type": "string", "examples": [ "Example Organisation" ] }, "is_foreign_account": { "type": "boolean", "examples": [ false ] } } }, "relations": { "type": "object", "properties": { "user_checkpoint_type": { "type": [ "string", "null" ], "examples": [ null ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ false ] } } } } }, "checkpoint_permissions": { "type": "object", "properties": { "training": { "type": "boolean", "examples": [ true ] }, "contact": { "type": "boolean", "examples": [ true ] }, "event": { "type": "object", "properties": { "type": { "type": "boolean", "examples": [ true ] }, "apply_to_shifts": { "type": "boolean", "examples": [ true ] }, "calendar": { "type": "boolean", "examples": [ true ] }, "history": { "type": "boolean", "examples": [ true ] }, "has_enabled_shift_type": { "type": "boolean", "examples": [ true ] }, "shift_type": { "type": "boolean", "examples": [ true ] }, "activites": { "type": "boolean", "examples": [ true ] }, "use_leader_mode_when_not_checked_in": { "type": "boolean", "examples": [ true ] }, "shift_calendar": { "type": "boolean", "examples": [ true ] } } }, "blog": { "type": "object", "properties": { "article": { "type": "boolean", "examples": [ true ] } } }, "rewardpoint": { "type": "boolean", "examples": [ true ] }, "inventory": { "type": "boolean", "examples": [ true ] }, "role_offer": { "type": "object", "properties": { "apply": { "type": "boolean", "examples": [ true ] }, "has_enabled_functional_area": { "type": "boolean", "examples": [ true ] }, "functional_area": { "type": "boolean", "examples": [ true ] } } }, "integration": { "type": "object", "properties": { "fundraising": { "type": "boolean", "examples": [ true ] } } }, "subaccount": { "type": "boolean", "examples": [ true ] }, "view_subaccount_selection_menu": { "type": "boolean", "examples": [ true ] }, "availability": { "type": "boolean", "examples": [ true ] }, "certificate": { "type": "boolean", "examples": [ true ] }, "eav": { "type": "object", "properties": { "has_disabled_attributes": { "type": "boolean", "examples": [ true ] }, "disabled_attributes": { "type": "boolean", "examples": [ true ] } } }, "user_group": { "type": "boolean", "examples": [ true ] }, "messaging": { "type": "object", "properties": { "access": { "type": "boolean", "examples": [ true ] } } } } }, "settings": { "type": "object", "properties": { "general:locale": { "type": "string", "examples": [ "en-AU" ] }, "general:timezone": { "type": "string", "examples": [ "Australia/Melbourne" ] }, "general:advanced_pagination": { "type": "boolean", "examples": [ false ] }, "general:high_accessibility": { "type": "boolean", "examples": [ false ] }, "availability:advanced": { "type": "boolean", "examples": [ false ] }, "availability:available_by_default": { "type": "boolean", "examples": [ true ] }, "security:2fa": { "type": "string", "examples": [ "" ] } } }, "socials": { "type": "array", "examples": [ [] ] }, "is_primary_account": { "type": "boolean", "examples": [ true ] }, "has_account_roles": { "type": "boolean", "examples": [ true ] }, "messaging_user_id": { "type": [ "string", "null" ], "examples": [ null ] } }, "examples": [ { "user": { "id": 1234, "account_id": 20101, "email": "alex.example@example.com", "force_reset_password": 0, "password_expires_at": null, "first_name": "Alex", "middle_name": null, "last_name": "Example", "preferred_name": null, "phone": "au-200000000", "dob": "1990-01-15", "picture": null, "picture_status": 0, "is_subscribed": 0, "is_subscribed_transactional": 1, "is_unreachable": 0, "is_unreachable_sms": 0, "terms": 1, "rating": "0.00", "shift_privacy": 1, "is_team_leader": 0, "email_verified": 0, "login_lockout_attempts": 0, "login_lockout_at": null, "login_lockout_email_sent_at": null, "last_login_at": "2026-01-20T02:14:52.000000Z", "last_app_login_at": null, "is_archived": 0, "last_activated": null, "from_source": null, "delete_requested_at": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-01-05T01:32:57.000000Z", "updated_at": "2026-01-20T01:42:50.000000Z", "deleted_by": null, "interests": null, "address": { "iso": "AUS", "region_code": "VIC", "coordinates": { "latitude": null, "longitude": null }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "Example City", "postcode": "1000", "region": "VIC", "country": "AU", "latitude": null, "longitude": null }, "rrn": "rrn:local:20101:user:AAAABBBBCCCCDDDDEEEEFFFF", "age": 36, "checkpoint_id": 3, "type_id": 2, "eula_agreed": false, "qr_code": "https://example.rosterfy.com/qr/qr-example.png" }, "nice": { "rrn": "rrn:local:20101:user:AAAABBBBCCCCDDDDEEEEFFFF", "family_id": null, "has_family_members": "No", "manages_family": false, "family_manager": "No", "family_member": "No", "is_family_member": false, "is_engaged": "No", "is_engaged:raw": false, "last_engaged_at": null, "last_engaged_at:raw": null, "created_at": "Jun 9, 2026, 5:33 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:33 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "email_verified": "No", "from_source": "", "interests": null, "interests:value": null, "interests:array": null, "is_subscribed_transactional": "Yes", "is_team_leader": "No", "last_login_at": "Aug 10, 2026, 5:16 AM", "last_login_at__date": "Aug 10, 2026", "last_login_at__time": "5:16 AM", "last_login_at__offset": " (+00:00 UTC)", "last_login_at__offset_minutes": 0, "last_login_at__dayofweek": "Monday", "middle_name": "", "picture_status": "N/A", "picture_status:value": 0, "picture_status:array": "N/A", "shift_privacy": "Yes", "updated_at": "Jun 9, 2026, 5:33 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:33 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "first_name": "Alex", "last_name": "Example", "preferred_name": "", "dob": "Jan 15, 1990", "dob__dayofweek": "Monday", "is_subscribed": "No", "terms": "Yes", "name": "Alex Example", "age": 36, "age_months": "36 years, 0 months", "info": "Alex Example (alex.example@example.com)", "preferred_first_name": "Alex", "delete_requested": false, "updated_hours": 1487.7417004144, "is_community_user": false, "timezone": "UTC", "address": "1 Example Street\nExample City\nVictoria\nAustralia\n1000", "address_oneline": "1 Example Street, Example City, Victoria, Australia, 1000", "address.country": "Australia", "address.country:raw": "AUS", "phone": "(+61) 200000000", "phone:raw": "+61200000000" }, "type": { "id": 2, "account_branding_id": null, "name": "Default", "code": "default", "profile_form_id": null, "training_ids": null, "registration_form_id": null, "shift_limit": 0, "shift_max_time": null, "max_shift_length": 0, "min_shift_length": 0, "min_consecutive_rest_time_per_week": 0, "max_work_days_per_week": 0, "gap_between_shifts": 0, "group_leader_attributes": null, "deleted_at": null, "created_at": "2026-06-09T05:33:39.000000Z", "updated_at": "2026-06-09T05:33:39.000000Z", "uuid": "0cdefc27-b599-4a15-a82f-18c11bb44803" }, "permissions": { "admin": true, "event": true, "event:create": true, "event:read": true, "event:update": true, "event:delete": true, "user": true, "user:create": true, "user:read": true, "user:update": true, "user:delete": true, "training": true, "training:read": true, "report": true, "report:read": true }, "checkpoint": { "object": { "id": 1, "user_checkpoint_type_id": null, "name": "Default", "label": "default", "permissions": { "all": "1" }, "actions": [], "is_inheritable": 0, "sort_order": 0, "deleted_at": null, "created_at": "2026-06-09T05:33:39.000000Z", "updated_at": "2026-06-09T05:34:24.000000Z" }, "nice": { "rrn": "rrn:local:20101:checkpoint:1", "content_id": 3, "account_name_path": "Example Organisation", "is_foreign_account": false }, "relations": { "user_checkpoint_type": null }, "permissions": { "read": true, "update": true, "delete": false } }, "checkpoint_permissions": { "training": true, "contact": true, "event": { "type": true, "apply_to_shifts": true, "calendar": true, "history": true, "has_enabled_shift_type": true, "shift_type": true, "activites": true, "use_leader_mode_when_not_checked_in": true, "shift_calendar": true }, "blog": { "article": true }, "rewardpoint": true, "inventory": true, "role_offer": { "apply": true, "has_enabled_functional_area": true, "functional_area": true }, "integration": { "fundraising": true }, "subaccount": true, "view_subaccount_selection_menu": true, "availability": true, "certificate": true, "eav": { "has_disabled_attributes": true, "disabled_attributes": true }, "user_group": true, "messaging": { "access": true } }, "settings": { "general:locale": "en-AU", "general:timezone": "Australia/Melbourne", "general:advanced_pagination": false, "general:high_accessibility": false, "availability:advanced": false, "availability:available_by_default": true, "security:2fa": "" }, "socials": [], "is_primary_account": true, "has_account_roles": true, "messaging_user_id": null } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Me Module" ] } }, "/api/v2/account/data": { "get": { "summary": "Get current account configuration", "operationId": "getCurrentAccountConfiguration", "description": "Returns the configuration a client needs in order to present the organisation correctly:\nhow the account identifies itself, the settings that shape the experience, the wording it\nuses for everyday concepts, and the locales it offers. Which account answers is determined\nby the subdomain the request is made against, so no identifier is passed.\n\nThe response has five parts. `account` is the organisation itself - its identifier, its\nparent if it sits under one, its status and a set of capability flags a client uses to\ndecide what to show. `settings` is the account's configuration as key/value pairs, keyed by\na `section:name` string. `terms` is the account's own vocabulary, so an organisation that\ncalls its people \"Members\" rather than \"Volunteers\" is reflected here and a client should\ntake its labels from this block rather than hard-coding them. `locales` lists the languages\noffered. `extras` carries client-side integration configuration.\n\nThe `settings` block is large and account-specific - a configured organisation returns\nseveral hundred entries - so the example shows a representative selection rather than the\nfull set. Read the keys you need by name and ignore the rest; entries are added over time\nand a key being absent means the account has not set it.\n\nDespite being grouped with the current-user endpoints, this describes the organisation and\nnot the caller. Nothing in the response varies by user.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 20101 ] }, "rrn": { "type": "string", "examples": [ "rrn:local:20101:account:20101" ] }, "parent_id": { "type": [ "string", "null" ], "examples": [ null ] }, "parent_url": { "type": [ "string", "null" ], "examples": [ null ] }, "parent_account_name": { "type": [ "string", "null" ], "examples": [ null ] }, "status": { "type": "string", "examples": [ "approved" ] }, "can_request_deletion": { "type": "boolean", "examples": [ true ] }, "has_support_email": { "type": "boolean", "examples": [ false ] }, "delete_requested_at": { "type": [ "string", "null" ], "examples": [ null ] }, "allow_family": { "type": "boolean", "examples": [ true ] }, "is_archived": { "type": "boolean", "examples": [ false ] }, "has_latest_eula": { "type": "boolean", "examples": [ false ] }, "has_payment_integration": { "type": "boolean", "examples": [ false ] }, "is_locked": { "type": "boolean", "examples": [ false ] }, "is_trial": { "type": "boolean", "examples": [ false ] }, "has_seek_volunteer_integration": { "type": "boolean", "examples": [ false ] } } }, "settings": { "type": "object", "properties": { "general:available_locales": { "type": "array", "items": { "type": "string" }, "examples": [ [ "en-US" ] ] }, "general:locale": { "type": "string", "examples": [ "en-AU" ] }, "general:timezone": { "type": "string", "examples": [ "Australia/Melbourne" ] }, "general:location": { "type": "array", "items": { "type": "number" }, "examples": [ [ -37.829632, 144.957956 ] ] }, "users:register": { "type": "integer", "examples": [ 1 ] }, "email:from_email": { "type": "string", "examples": [ "noreply@example.com" ] }, "email:from_name": { "type": "string", "examples": [ "Example Organisation" ] } } }, "terms": { "type": "object", "properties": { "rosterfy": { "type": "string", "examples": [ "Rosterfy" ] }, "admin": { "type": "string", "examples": [ "Admin" ] }, "portal": { "type": "string", "examples": [ "Portal" ] }, "user": { "type": "string", "examples": [ "User" ] }, "users": { "type": "string", "examples": [ "Users" ] }, "event": { "type": "string", "examples": [ "Event" ] }, "events": { "type": "string", "examples": [ "Events" ] }, "shift": { "type": "string", "examples": [ "Shift" ] }, "shifts": { "type": "string", "examples": [ "Shifts" ] }, "account": { "type": "string", "examples": [ "Account" ] }, "accounts": { "type": "string", "examples": [ "Accounts" ] }, "subaccount": { "type": "string", "examples": [ "Subaccount" ] }, "subaccounts": { "type": "string", "examples": [ "Subaccounts" ] } } }, "locales": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "examples": [ "en-AU" ] }, "text": { "type": "string", "examples": [ "English (Australia)" ] } } }, "examples": [ [ { "value": "en-AU", "text": "English (Australia)" }, { "value": "en-GB", "text": "English (United Kingdom)" }, { "value": "en-US", "text": "English (United States)" } ] ] }, "extras": { "type": "object", "properties": { "datadog": { "type": "object", "properties": { "client_token": { "type": "string", "examples": [ "pub00000000000000000000000000000000" ] }, "application_id": { "type": "string", "examples": [ "00000000-0000-0000-0000-000000000000" ] }, "service": { "type": "string", "examples": [ "rosterfy" ] }, "sample_rate": { "type": "string", "examples": [ "100" ] }, "premium_sample_rate": { "type": "string", "examples": [ "100" ] }, "track_interactions": { "type": "boolean", "examples": [ true ] }, "version": { "type": "string", "examples": [ "1.0.0" ] } } }, "thresholds": { "type": "array", "examples": [ [] ] }, "level_1_account_rrn": { "type": "string", "examples": [ "rrn:local:20101:account:20101" ] }, "intercom_app_id": { "type": "string", "examples": [ "example0" ] }, "messaging_api_key": { "type": "string", "examples": [ "example0key0" ] }, "messaging_channel_limit": { "type": "integer", "examples": [ 10000 ] }, "show_channel_count": { "type": "boolean", "examples": [ false ] } } } }, "examples": [ { "account": { "id": 20101, "rrn": "rrn:local:20101:account:20101", "parent_id": null, "parent_url": null, "parent_account_name": null, "status": "approved", "can_request_deletion": true, "has_support_email": false, "delete_requested_at": null, "allow_family": true, "is_archived": false, "has_latest_eula": false, "has_payment_integration": false, "is_locked": false, "is_trial": false, "has_seek_volunteer_integration": false }, "settings": { "general:available_locales": [ "en-US" ], "general:locale": "en-AU", "general:timezone": "Australia/Melbourne", "general:location": [ -37.829632, 144.957956 ], "users:register": 1, "email:from_email": "noreply@example.com", "email:from_name": "Example Organisation" }, "terms": { "rosterfy": "Rosterfy", "admin": "Admin", "portal": "Portal", "user": "User", "users": "Users", "event": "Event", "events": "Events", "shift": "Shift", "shifts": "Shifts", "account": "Account", "accounts": "Accounts", "subaccount": "Subaccount", "subaccounts": "Subaccounts" }, "locales": [ { "value": "en-AU", "text": "English (Australia)" }, { "value": "en-GB", "text": "English (United Kingdom)" }, { "value": "en-US", "text": "English (United States)" } ], "extras": { "datadog": { "client_token": "pub00000000000000000000000000000000", "application_id": "00000000-0000-0000-0000-000000000000", "service": "rosterfy", "sample_rate": "100", "premium_sample_rate": "100", "track_interactions": true, "version": "1.0.0" }, "thresholds": [], "level_1_account_rrn": "rrn:local:20101:account:20101", "intercom_app_id": "example0", "messaging_api_key": "example0key0", "messaging_channel_limit": 10000, "show_channel_count": false } } ] } } } } }, "tags": [ "Me Module" ] } }, "/api/v2/me/stats": { "get": { "summary": "Get my statistics", "operationId": "getMyStatistics", "description": "Returns the headline activity totals for the signed-in user - the sort of figures a\nvolunteer portal shows on a dashboard, such as events attended, shifts worked, hours\ncontributed and the current reward point balance. Each entry carries a stable `code` to\nkey off, a display `label` already rendered in the account's own terminology, the `value`\nitself, and an `icon` hint the portal uses.\n\nWhich totals come back is a per-account choice, so the set of codes is not fixed and an\naccount that has selected none receives an empty array. Treat `code` as the contract and\nignore any code you do not recognise rather than relying on position. Totals are computed\non read and briefly cached, so a figure can lag a change made moments earlier.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "examples": [ "reward_point_balance" ] }, "label": { "type": "string", "examples": [ "Reward point balance" ] }, "value": { "type": "integer", "examples": [ 0 ] }, "icon": { "type": "string", "examples": [ "fas fa-medal" ] } } }, "examples": [ [ { "code": "reward_point_balance", "label": "Reward point balance", "value": 0, "icon": "fas fa-medal" }, { "code": "total_number_of_events", "label": "Total Number Of Events", "value": 4, "icon": "fas fa-star" }, { "code": "total_number_of_shifts", "label": "Total Number Of Shifts", "value": 4, "icon": "fas fa-calendar-alt" }, { "code": "total_shift_hours", "label": "Total Shift Hours Attended (By Scheduled Time)", "value": 18, "icon": "fas fa-clock" } ] ] } } } } }, "tags": [ "Me Module" ] } }, "/api/v2/me/training": { "get": { "summary": "List my training", "operationId": "listMyTraining", "description": "Returns the published training modules that are relevant to the signed-in user: those they\nhave been assigned, plus any module the organisation has made elective so that anyone may\nstart it. Modules the user has been explicitly exempted from are left out, as are modules\nthat have not been published. Training shared down from a parent organisation is included\nalongside the account's own.\n\nEach row is the training module itself rather than the user's progress against it. To see\nwhere the user has got to, filter on `current_user.status`, whose values are `COMPLETE`\nand `INCOMPLETE` - for example `filter[0][attr]=current_user.status&filter[0][value]=INCOMPLETE`\nfor everything still outstanding.\n\nThe listing is only paginated when `page` is supplied. Without it every match is returned\nas a flat array rather than in the paged envelope.", "parameters": [ { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "query", "name": "extras", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "required": false, "schema": { "type": "array", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "items": { "type": "string", "enum": [ "certificate_stats" ] }, "examples": [ [ "certificate_stats" ] ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Site Safety Induction" ] }, "short_description": { "type": [ "string", "null" ], "examples": [ null ] }, "thumbnail_url": { "type": [ "string", "null" ], "examples": [ null ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-01-12T06:55:00.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-01-12T06:55:00.000000Z" ] }, "success_message": { "type": "string", "examples": [ "You have completed the induction." ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "is_elective": { "type": "integer", "examples": [ 0 ] }, "estimated_complete_time": { "type": "integer", "examples": [ 11 ] }, "ttl": { "type": "integer", "examples": [ 0 ] }, "pass_score": { "type": "integer", "examples": [ 0 ] }, "is_library": { "type": "integer", "examples": [ 0 ] }, "publish": { "type": "integer", "examples": [ 1 ] }, "service": { "type": "string", "examples": [ "online" ] }, "external_id": { "type": [ "string", "null" ], "examples": [ null ] }, "meta": { "type": "array", "examples": [ [] ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "certificate_id": { "type": [ "string", "null" ], "examples": [ null ] }, "form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "type_id": { "type": [ "string", "null" ], "examples": [ null ] }, "is_inheritable": { "type": "integer", "examples": [ 0 ] } } }, "nice": { "type": "object", "properties": { "publish": { "type": "string", "examples": [ "Yes" ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "account_url": { "type": "string", "examples": [ "https://example.rosterfy.com/" ] }, "external": { "type": "boolean", "examples": [ false ] }, "has_certificate": { "type": "boolean", "examples": [ false ] }, "account_name_path": { "type": "string", "examples": [ "Rosterfy Subaccount" ] }, "is_foreign_account": { "type": "boolean", "examples": [ false ] }, "acts_as_native": { "type": "boolean", "examples": [ false ] }, "number_of_steps": { "type": "string", "examples": [ "3" ] }, "number_of_questions": { "type": "integer", "examples": [ 0 ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } }, "examples": [ [ { "object": { "id": 1, "name": "Site Safety Induction", "short_description": null, "thumbnail_url": null, "account_id": 20101, "deleted_at": null, "created_at": "2026-01-12T06:55:00.000000Z", "updated_at": "2026-01-12T06:55:00.000000Z", "success_message": "You have completed the induction.", "is_archived": 0, "is_elective": 0, "estimated_complete_time": 11, "ttl": 0, "pass_score": 0, "is_library": 0, "publish": 1, "service": "online", "external_id": null, "meta": [], "sort_order": 0, "certificate_id": null, "form_id": null, "type_id": null, "is_inheritable": 0 }, "nice": { "publish": "Yes", "account_id": 20101, "account_url": "https://example.rosterfy.com/", "external": false, "has_certificate": false, "account_name_path": "Rosterfy Subaccount", "is_foreign_account": false, "acts_as_native": false, "number_of_steps": "3", "number_of_questions": 0 }, "relations": [], "permissions": { "read": true, "update": true, "delete": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/me/training?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/me/training?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/me/training" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 1, "name": "Site Safety Induction", "short_description": null, "thumbnail_url": null, "account_id": 20101, "deleted_at": null, "created_at": "2026-01-12T06:55:00.000000Z", "updated_at": "2026-01-12T06:55:00.000000Z", "success_message": "You have completed the induction.", "is_archived": 0, "is_elective": 0, "estimated_complete_time": 11, "ttl": 0, "pass_score": 0, "is_library": 0, "publish": 1, "service": "online", "external_id": null, "meta": [], "sort_order": 0, "certificate_id": null, "form_id": null, "type_id": null, "is_inheritable": 0 }, "nice": { "publish": "Yes", "account_id": 20101, "account_url": "https://example.rosterfy.com/", "external": false, "has_certificate": false, "account_name_path": "Rosterfy Subaccount", "is_foreign_account": false, "acts_as_native": false, "number_of_steps": "3", "number_of_questions": 0 }, "relations": [], "permissions": { "read": true, "update": true, "delete": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/me/training?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/me/training?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/me/training", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Me Module" ] } }, "/api/v2/me/event": { "get": { "summary": "List my events", "operationId": "listMyEvents", "description": "Returns the events the signed-in user has a record against - anything they have applied\nfor, been rostered onto, attended or registered interest in. An event the user has no\ninvolvement with is never returned, so this is the volunteer's own history and upcoming\nschedule rather than a catalogue of what the organisation is running.\n\nRows are events, not shifts. To work with the individual shifts inside an event, use the\nshift endpoints rather than reading them from here.\n\nEvents that have not been published are excluded unless the caller also administers events,\nso an ordinary portal user and an administrator can get different counts for the same\nquery.\n\nThe listing is only paginated when `page` is supplied. Without it every match is returned\nas a flat array rather than in the paged envelope.", "parameters": [ { "in": "query", "name": "status", "description": "Narrow the list by the user's involvement. `active` returns only\n events where they hold a live place, `demand` only events still looking for people. Any\n other value is ignored and the full list is returned.", "required": false, "schema": { "type": "string", "description": "Narrow the list by the user's involvement. `active` returns only\n events where they hold a live place, `demand` only events still looking for people. Any\n other value is ignored and the full list is returned.", "examples": [ "active" ] } }, { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "query", "name": "extras", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "required": false, "schema": { "type": "array", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "items": { "type": "string", "enum": [ "leader_state", "shift_count", "stats", "certificate_user_count" ] }, "examples": [ [ "leader_state" ] ] } }, { "in": "query", "name": "with", "description": "A list of relations to include in the response. May be single records or collections.\nIt is often more efficient to retrieve this way, to avoid follow-up API calls.", "required": false, "schema": { "type": "array", "description": "A list of relations to include in the response. May be single records or collections.\nIt is often more efficient to retrieve this way, to avoid follow-up API calls.", "items": { "type": "string", "enum": [ "hasManyDeepFromRelationsWithConstraints", "hasOneDeepFromRelationsWithConstraints", "hasManyDeepFromReverse", "hasOneDeepFromReverse" ] }, "examples": [ [ "hasManyDeepFromRelationsWithConstraints" ] ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "parent_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_template_id": { "type": [ "string", "null" ], "examples": [ null ] }, "path": { "type": "string", "examples": [ "21476346" ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "event_type_id": { "type": "integer", "examples": [ 11 ] }, "journey_id": { "type": [ "string", "null" ], "examples": [ null ] }, "timezone": { "type": "string", "examples": [ "UTC" ] }, "start_timestamp": { "type": "string", "examples": [ "2026-06-04T05:00:00.000000Z" ] }, "end_timestamp": { "type": "string", "examples": [ "2026-06-29T05:00:00.000000Z" ] }, "is_ongoing": { "type": "integer", "examples": [ 0 ] }, "apps_open_timestamp": { "type": "string", "examples": [ "2026-06-03T05:00:00.000000Z" ] }, "apps_close_timestamp": { "type": "string", "examples": [ "2026-06-07T05:00:00.000000Z" ] }, "headcount_location_venue_id": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_functional_area_job_title_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_status_default": { "type": "integer", "examples": [ 2 ] }, "max_shift_apps_per_user": { "type": "integer", "examples": [ 0 ] }, "min_shift_apps_per_user": { "type": "integer", "examples": [ 0 ] }, "min_shift_apps_per_shift_type": { "type": [ "string", "null" ], "examples": [ null ] }, "max_shift_apps_per_shift_type": { "type": [ "string", "null" ], "examples": [ null ] }, "gap_between_shifts": { "type": "integer", "examples": [ 0 ] }, "shift_confirmed_status_default": { "type": "integer", "examples": [ 3 ] }, "shift_rejected_status_default": { "type": "integer", "examples": [ 6 ] }, "shift_can_withdraw_default": { "type": "integer", "examples": [ 1 ] }, "shift_can_confirm_default": { "type": "integer", "examples": [ 1 ] }, "shift_can_confirm_limit": { "type": "integer", "examples": [ 0 ] }, "shift_can_withdraw_limit": { "type": "integer", "examples": [ 0 ] }, "shift_checked_in_status_default": { "type": "integer", "examples": [ 4 ] }, "shift_checked_out_status_default": { "type": "integer", "examples": [ 4 ] }, "certificate_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_leader_feedback_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_feedback_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_default_journey_complete_status": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_default_journey_id": { "type": [ "string", "null" ], "examples": [ null ] }, "allow_user_activities": { "type": "integer", "examples": [ 0 ] }, "user_activity_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "training_ids": { "type": [ "string", "null" ], "examples": [ null ] }, "banner_image": { "type": [ "string", "null" ], "examples": [ null ] }, "grid_image": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "visibility_show_groups": { "type": "array", "examples": [ [] ] }, "visibility_hide_groups": { "type": "array", "examples": [ [] ] }, "visibility_show_roleoffer": { "type": "array", "examples": [ [] ] }, "role_offer_address": { "type": "integer", "examples": [ 0 ] }, "checkin_visible_attributes": { "type": "array", "examples": [ [] ] }, "shift_filter_attributes": { "type": [ "string", "null" ], "examples": [ null ] }, "leader_shift_filter_attributes": { "type": [ "string", "null" ], "examples": [ null ] }, "self_checkin": { "type": "integer", "examples": [ 0 ] }, "self_checkin_open": { "type": "integer", "examples": [ 0 ] }, "self_checkin_close": { "type": "integer", "examples": [ 0 ] }, "self_checkout_close": { "type": "integer", "examples": [ 0 ] }, "checkin_close_default": { "type": "integer", "examples": [ 0 ] }, "shift_precheckin_open_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_enable_waitlist_default": { "type": "integer", "examples": [ 0 ] }, "geofence_checkin_limit_default": { "type": [ "string", "null" ], "examples": [ null ] }, "max_waitlist": { "type": "integer", "examples": [ 0 ] }, "group_booking_ttl_default": { "type": [ "string", "null" ], "examples": [ null ] }, "max_group_demand_default": { "type": [ "string", "null" ], "examples": [ null ] }, "max_group_size": { "type": [ "string", "null" ], "examples": [ null ] }, "reserved_expiry": { "type": [ "string", "null" ], "examples": [ null ] }, "post_feedback_form": { "type": [ "string", "null" ], "examples": [ null ] }, "post_feedback_publish_at": { "type": [ "string", "null" ], "examples": [ null ] }, "expression_of_interest": { "type": "integer", "examples": [ 0 ] }, "journey_complete_status": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_apply_status": { "type": [ "string", "null" ], "examples": [ null ] }, "expression_of_interest_form": { "type": [ "string", "null" ], "examples": [ null ] }, "cancel_expression_of_interest_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "eoi_demand": { "type": "integer", "examples": [ 0 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "is_virtual": { "type": "integer", "examples": [ 0 ] }, "status": { "type": "string", "examples": [ "published" ] }, "approval_status": { "type": "string", "examples": [ "approved" ] }, "approval_reason": { "type": [ "string", "null" ], "examples": [ null ] }, "promoted": { "type": "integer", "examples": [ 0 ] }, "public": { "type": "integer", "examples": [ 0 ] }, "is_cancelled": { "type": "integer", "examples": [ 0 ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "public_shift": { "type": "integer", "examples": [ 0 ] }, "public_shift_default": { "type": "integer", "examples": [ 0 ] }, "certificates_awarded": { "type": "integer", "examples": [ 0 ] }, "created_by": { "type": "integer", "examples": [ 1234 ] }, "updated_by": { "type": "integer", "examples": [ 1234 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:50.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:50.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "description": { "type": "string", "examples": [ "

Our flagship community event.

" ] }, "name": { "type": "string", "examples": [ "City Marathon 2026" ] }, "address": { "type": "object", "properties": { "iso": { "type": "string", "examples": [ "AUS" ] }, "street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "city": { "type": "string", "examples": [ "Example City" ] }, "postcode": { "type": "string", "examples": [ "1000" ] }, "region": { "type": "string", "examples": [ "VIC" ] }, "country": { "type": "string", "examples": [ "AU" ] }, "latitude": { "type": [ "string", "null" ], "examples": [ null ] }, "longitude": { "type": [ "string", "null" ], "examples": [ null ] } } } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:event:1" ] }, "allow_user_activities": { "type": "string", "examples": [ "No" ] }, "approval_status": { "type": "string", "examples": [ "Approved" ] }, "approval_status:value": { "type": "string", "examples": [ "approved" ] }, "approval_status:array": { "type": "string", "examples": [ "Approved" ] }, "apps_close_timestamp": { "type": "string", "examples": [ "Jun 7, 2026, 5:00 AM" ] }, "apps_close_timestamp__date": { "type": "string", "examples": [ "Jun 7, 2026" ] }, "apps_close_timestamp__time": { "type": "string", "examples": [ "5:00 AM" ] }, "apps_close_timestamp__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "apps_close_timestamp__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "apps_close_timestamp__dayofweek": { "type": "string", "examples": [ "Sunday" ] }, "apps_open_timestamp": { "type": "string", "examples": [ "Jun 3, 2026, 5:00 AM" ] }, "apps_open_timestamp__date": { "type": "string", "examples": [ "Jun 3, 2026" ] }, "apps_open_timestamp__time": { "type": "string", "examples": [ "5:00 AM" ] }, "apps_open_timestamp__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "apps_open_timestamp__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "apps_open_timestamp__dayofweek": { "type": "string", "examples": [ "Wednesday" ] }, "cancel_expression_of_interest_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "cancel_expression_of_interest_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "cancel_expression_of_interest_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "end_timestamp": { "type": "string", "examples": [ "Jun 29, 2026, 5:00 AM" ] }, "end_timestamp__date": { "type": "string", "examples": [ "Jun 29, 2026" ] }, "end_timestamp__time": { "type": "string", "examples": [ "5:00 AM" ] }, "end_timestamp__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "end_timestamp__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "end_timestamp__dayofweek": { "type": "string", "examples": [ "Monday" ] }, "event_template_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_template_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "event_template_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "event_type_id": { "type": "string", "examples": [ "ratione laborum dolor" ] }, "event_type_id:value": { "type": "integer", "examples": [ 11 ] }, "event_type_id:array": { "type": "string", "examples": [ "ratione laborum dolor" ] }, "expression_of_interest": { "type": "string", "examples": [ "No" ] }, "headcount_location_venue_id": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "is_ongoing": { "type": "string", "examples": [ "No" ] }, "is_virtual": { "type": "string", "examples": [ "No" ] }, "name": { "type": "string", "examples": [ "City Marathon 2026" ] }, "promoted": { "type": "string", "examples": [ "No" ] }, "role_offer_address": { "type": "string", "examples": [ "No" ] }, "self_checkin": { "type": "string", "examples": [ "No" ] }, "shift_application_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_feedback_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_feedback_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_feedback_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "start_timestamp": { "type": "string", "examples": [ "Jun 4, 2026, 5:00 AM" ] }, "start_timestamp__date": { "type": "string", "examples": [ "Jun 4, 2026" ] }, "start_timestamp__time": { "type": "string", "examples": [ "5:00 AM" ] }, "start_timestamp__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "start_timestamp__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "start_timestamp__dayofweek": { "type": "string", "examples": [ "Thursday" ] }, "status": { "type": "string", "examples": [ "Published" ] }, "status:value": { "type": "string", "examples": [ "published" ] }, "status:array": { "type": "string", "examples": [ "Published" ] }, "tags": { "type": [ "string", "null" ], "examples": [ null ] }, "tags:value": { "type": [ "string", "null" ], "examples": [ null ] }, "tags:array": { "type": [ "string", "null" ], "examples": [ null ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "visibility_hide_groups": { "type": "string", "examples": [ "" ] }, "visibility_show_groups": { "type": "string", "examples": [ "" ] }, "visibility_show_roleoffer": { "type": "string", "examples": [ "" ] }, "full_name": { "type": "string", "examples": [ "City Marathon 2026" ] }, "event_type_name": { "type": "string", "examples": [ "ratione laborum dolor" ] }, "grid_list_image": { "type": [ "string", "null" ], "examples": [ null ] }, "is_eoi_demand_met": { "type": "boolean", "examples": [ false ] }, "has_payrun": { "type": "boolean", "examples": [ false ] }, "min_shifts": { "type": "integer", "examples": [ 0 ] }, "post_event_feedback_form_completed_at": { "type": [ "string", "null" ], "examples": [ null ] }, "expression_of_interest_form_completed_at": { "type": [ "string", "null" ], "examples": [ null ] }, "expression_of_interest_form_cancelled_at": { "type": [ "string", "null" ], "examples": [ null ] }, "account_name": { "type": "string", "examples": [ "Example Organisation" ] }, "apply": { "type": "object", "properties": { "code": { "type": "integer", "examples": [ 1001 ] }, "message": { "type": "string", "examples": [ "Event is closed" ] } } }, "address": { "type": "string", "examples": [ "1 Example Street\nExample City\nVictoria\nAustralia\n1000" ] }, "address_oneline": { "type": "string", "examples": [ "1 Example Street, Example City, Victoria, Australia, 1000" ] }, "address.latitude": { "type": [ "string", "null" ], "examples": [ null ] }, "address.longitude": { "type": [ "string", "null" ], "examples": [ null ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "apply": { "type": "boolean", "examples": [ false ] }, "cancel": { "type": "boolean", "examples": [ false ] }, "can_publish": { "type": "boolean", "examples": [ true ] } } }, "attributes": { "type": "array", "examples": [ [] ] } } }, "examples": [ [ { "object": { "id": 1, "parent_id": null, "event_template_id": null, "path": "21476346", "account_id": 20101, "event_type_id": 11, "journey_id": null, "timezone": "UTC", "start_timestamp": "2026-06-04T05:00:00.000000Z", "end_timestamp": "2026-06-29T05:00:00.000000Z", "is_ongoing": 0, "apps_open_timestamp": "2026-06-03T05:00:00.000000Z", "apps_close_timestamp": "2026-06-07T05:00:00.000000Z", "headcount_location_venue_id": null, "headcount_functional_area_job_title_id": null, "shift_status_default": 2, "max_shift_apps_per_user": 0, "min_shift_apps_per_user": 0, "min_shift_apps_per_shift_type": null, "max_shift_apps_per_shift_type": null, "gap_between_shifts": 0, "shift_confirmed_status_default": 3, "shift_rejected_status_default": 6, "shift_can_withdraw_default": 1, "shift_can_confirm_default": 1, "shift_can_confirm_limit": 0, "shift_can_withdraw_limit": 0, "shift_checked_in_status_default": 4, "shift_checked_out_status_default": 4, "certificate_id": null, "shift_application_form_id_default": null, "shift_withdraw_form_id_default": null, "shift_checkin_form_id_default": null, "shift_attended_form_id_default": null, "shift_checkout_form_id_default": null, "shift_leader_feedback_form_id_default": null, "shift_feedback_form_id_default": null, "shift_precheckin_form_id_default": null, "shift_default_journey_complete_status": null, "shift_default_journey_id": null, "allow_user_activities": 0, "user_activity_form_id": null, "training_ids": null, "banner_image": null, "grid_image": null, "minimum_dob": null, "minimum_age": null, "maximum_dob": null, "maximum_age": null, "visibility_show_groups": [], "visibility_hide_groups": [], "visibility_show_roleoffer": [], "role_offer_address": 0, "checkin_visible_attributes": [], "shift_filter_attributes": null, "leader_shift_filter_attributes": null, "self_checkin": 0, "self_checkin_open": 0, "self_checkin_close": 0, "self_checkout_close": 0, "checkin_close_default": 0, "shift_precheckin_open_default": null, "shift_enable_waitlist_default": 0, "geofence_checkin_limit_default": null, "max_waitlist": 0, "group_booking_ttl_default": null, "max_group_demand_default": null, "max_group_size": null, "reserved_expiry": null, "post_feedback_form": null, "post_feedback_publish_at": null, "expression_of_interest": 0, "journey_complete_status": null, "journey_apply_status": null, "expression_of_interest_form": null, "cancel_expression_of_interest_form_id": null, "eoi_demand": 0, "sort_order": 0, "is_virtual": 0, "status": "published", "approval_status": "approved", "approval_reason": null, "promoted": 0, "public": 0, "is_cancelled": 0, "is_archived": 0, "public_shift": 0, "public_shift_default": 0, "certificates_awarded": 0, "created_by": 1234, "updated_by": 1234, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:36:50.000000Z", "updated_at": "2026-06-09T05:36:50.000000Z", "deleted_by": null, "description": "

Our flagship community event.

", "name": "City Marathon 2026", "address": { "iso": "AUS", "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "Example City", "postcode": "1000", "region": "VIC", "country": "AU", "latitude": null, "longitude": null } }, "nice": { "rrn": "rrn:local:20101:event:1", "allow_user_activities": "No", "approval_status": "Approved", "approval_status:value": "approved", "approval_status:array": "Approved", "apps_close_timestamp": "Jun 7, 2026, 5:00 AM", "apps_close_timestamp__date": "Jun 7, 2026", "apps_close_timestamp__time": "5:00 AM", "apps_close_timestamp__offset": " (+00:00 UTC)", "apps_close_timestamp__offset_minutes": 0, "apps_close_timestamp__dayofweek": "Sunday", "apps_open_timestamp": "Jun 3, 2026, 5:00 AM", "apps_open_timestamp__date": "Jun 3, 2026", "apps_open_timestamp__time": "5:00 AM", "apps_open_timestamp__offset": " (+00:00 UTC)", "apps_open_timestamp__offset_minutes": 0, "apps_open_timestamp__dayofweek": "Wednesday", "cancel_expression_of_interest_form_id": null, "cancel_expression_of_interest_form_id:value": null, "cancel_expression_of_interest_form_id:array": null, "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "end_timestamp": "Jun 29, 2026, 5:00 AM", "end_timestamp__date": "Jun 29, 2026", "end_timestamp__time": "5:00 AM", "end_timestamp__offset": " (+00:00 UTC)", "end_timestamp__offset_minutes": 0, "end_timestamp__dayofweek": "Monday", "event_template_id": null, "event_template_id:value": null, "event_template_id:array": null, "event_type_id": "ratione laborum dolor", "event_type_id:value": 11, "event_type_id:array": "ratione laborum dolor", "expression_of_interest": "No", "headcount_location_venue_id": null, "headcount_location_venue_id:value": null, "headcount_location_venue_id:array": null, "is_ongoing": "No", "is_virtual": "No", "name": "City Marathon 2026", "promoted": "No", "role_offer_address": "No", "self_checkin": "No", "shift_application_form_id_default": null, "shift_application_form_id_default:value": null, "shift_application_form_id_default:array": null, "shift_attended_form_id_default": null, "shift_attended_form_id_default:value": null, "shift_attended_form_id_default:array": null, "shift_checkin_form_id_default": null, "shift_checkin_form_id_default:value": null, "shift_checkin_form_id_default:array": null, "shift_checkout_form_id_default": null, "shift_checkout_form_id_default:value": null, "shift_checkout_form_id_default:array": null, "shift_feedback_form_id_default": null, "shift_feedback_form_id_default:value": null, "shift_feedback_form_id_default:array": null, "shift_precheckin_form_id_default": null, "shift_precheckin_form_id_default:value": null, "shift_precheckin_form_id_default:array": null, "shift_withdraw_form_id_default": null, "shift_withdraw_form_id_default:value": null, "shift_withdraw_form_id_default:array": null, "start_timestamp": "Jun 4, 2026, 5:00 AM", "start_timestamp__date": "Jun 4, 2026", "start_timestamp__time": "5:00 AM", "start_timestamp__offset": " (+00:00 UTC)", "start_timestamp__offset_minutes": 0, "start_timestamp__dayofweek": "Thursday", "status": "Published", "status:value": "published", "status:array": "Published", "tags": null, "tags:value": null, "tags:array": null, "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "visibility_hide_groups": "", "visibility_show_groups": "", "visibility_show_roleoffer": "", "full_name": "City Marathon 2026", "event_type_name": "ratione laborum dolor", "grid_list_image": null, "is_eoi_demand_met": false, "has_payrun": false, "min_shifts": 0, "post_event_feedback_form_completed_at": null, "expression_of_interest_form_completed_at": null, "expression_of_interest_form_cancelled_at": null, "account_name": "Example Organisation", "apply": { "code": 1001, "message": "Event is closed" }, "address": "1 Example Street\nExample City\nVictoria\nAustralia\n1000", "address_oneline": "1 Example Street, Example City, Victoria, Australia, 1000", "address.latitude": null, "address.longitude": null }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "apply": false, "cancel": false, "can_publish": true }, "attributes": [] }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/me/event?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/me/event?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/me/event" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 1, "parent_id": null, "event_template_id": null, "path": "21476346", "account_id": 20101, "event_type_id": 11, "journey_id": null, "timezone": "UTC", "start_timestamp": "2026-06-04T05:00:00.000000Z", "end_timestamp": "2026-06-29T05:00:00.000000Z", "is_ongoing": 0, "apps_open_timestamp": "2026-06-03T05:00:00.000000Z", "apps_close_timestamp": "2026-06-07T05:00:00.000000Z", "headcount_location_venue_id": null, "headcount_functional_area_job_title_id": null, "shift_status_default": 2, "max_shift_apps_per_user": 0, "min_shift_apps_per_user": 0, "min_shift_apps_per_shift_type": null, "max_shift_apps_per_shift_type": null, "gap_between_shifts": 0, "shift_confirmed_status_default": 3, "shift_rejected_status_default": 6, "shift_can_withdraw_default": 1, "shift_can_confirm_default": 1, "shift_can_confirm_limit": 0, "shift_can_withdraw_limit": 0, "shift_checked_in_status_default": 4, "shift_checked_out_status_default": 4, "certificate_id": null, "shift_application_form_id_default": null, "shift_withdraw_form_id_default": null, "shift_checkin_form_id_default": null, "shift_attended_form_id_default": null, "shift_checkout_form_id_default": null, "shift_leader_feedback_form_id_default": null, "shift_feedback_form_id_default": null, "shift_precheckin_form_id_default": null, "shift_default_journey_complete_status": null, "shift_default_journey_id": null, "allow_user_activities": 0, "user_activity_form_id": null, "training_ids": null, "banner_image": null, "grid_image": null, "minimum_dob": null, "minimum_age": null, "maximum_dob": null, "maximum_age": null, "visibility_show_groups": [], "visibility_hide_groups": [], "visibility_show_roleoffer": [], "role_offer_address": 0, "checkin_visible_attributes": [], "shift_filter_attributes": null, "leader_shift_filter_attributes": null, "self_checkin": 0, "self_checkin_open": 0, "self_checkin_close": 0, "self_checkout_close": 0, "checkin_close_default": 0, "shift_precheckin_open_default": null, "shift_enable_waitlist_default": 0, "geofence_checkin_limit_default": null, "max_waitlist": 0, "group_booking_ttl_default": null, "max_group_demand_default": null, "max_group_size": null, "reserved_expiry": null, "post_feedback_form": null, "post_feedback_publish_at": null, "expression_of_interest": 0, "journey_complete_status": null, "journey_apply_status": null, "expression_of_interest_form": null, "cancel_expression_of_interest_form_id": null, "eoi_demand": 0, "sort_order": 0, "is_virtual": 0, "status": "published", "approval_status": "approved", "approval_reason": null, "promoted": 0, "public": 0, "is_cancelled": 0, "is_archived": 0, "public_shift": 0, "public_shift_default": 0, "certificates_awarded": 0, "created_by": 1234, "updated_by": 1234, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:36:50.000000Z", "updated_at": "2026-06-09T05:36:50.000000Z", "deleted_by": null, "description": "

Our flagship community event.

", "name": "City Marathon 2026", "address": { "iso": "AUS", "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "Example City", "postcode": "1000", "region": "VIC", "country": "AU", "latitude": null, "longitude": null } }, "nice": { "rrn": "rrn:local:20101:event:1", "allow_user_activities": "No", "approval_status": "Approved", "approval_status:value": "approved", "approval_status:array": "Approved", "apps_close_timestamp": "Jun 7, 2026, 5:00 AM", "apps_close_timestamp__date": "Jun 7, 2026", "apps_close_timestamp__time": "5:00 AM", "apps_close_timestamp__offset": " (+00:00 UTC)", "apps_close_timestamp__offset_minutes": 0, "apps_close_timestamp__dayofweek": "Sunday", "apps_open_timestamp": "Jun 3, 2026, 5:00 AM", "apps_open_timestamp__date": "Jun 3, 2026", "apps_open_timestamp__time": "5:00 AM", "apps_open_timestamp__offset": " (+00:00 UTC)", "apps_open_timestamp__offset_minutes": 0, "apps_open_timestamp__dayofweek": "Wednesday", "cancel_expression_of_interest_form_id": null, "cancel_expression_of_interest_form_id:value": null, "cancel_expression_of_interest_form_id:array": null, "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "end_timestamp": "Jun 29, 2026, 5:00 AM", "end_timestamp__date": "Jun 29, 2026", "end_timestamp__time": "5:00 AM", "end_timestamp__offset": " (+00:00 UTC)", "end_timestamp__offset_minutes": 0, "end_timestamp__dayofweek": "Monday", "event_template_id": null, "event_template_id:value": null, "event_template_id:array": null, "event_type_id": "ratione laborum dolor", "event_type_id:value": 11, "event_type_id:array": "ratione laborum dolor", "expression_of_interest": "No", "headcount_location_venue_id": null, "headcount_location_venue_id:value": null, "headcount_location_venue_id:array": null, "is_ongoing": "No", "is_virtual": "No", "name": "City Marathon 2026", "promoted": "No", "role_offer_address": "No", "self_checkin": "No", "shift_application_form_id_default": null, "shift_application_form_id_default:value": null, "shift_application_form_id_default:array": null, "shift_attended_form_id_default": null, "shift_attended_form_id_default:value": null, "shift_attended_form_id_default:array": null, "shift_checkin_form_id_default": null, "shift_checkin_form_id_default:value": null, "shift_checkin_form_id_default:array": null, "shift_checkout_form_id_default": null, "shift_checkout_form_id_default:value": null, "shift_checkout_form_id_default:array": null, "shift_feedback_form_id_default": null, "shift_feedback_form_id_default:value": null, "shift_feedback_form_id_default:array": null, "shift_precheckin_form_id_default": null, "shift_precheckin_form_id_default:value": null, "shift_precheckin_form_id_default:array": null, "shift_withdraw_form_id_default": null, "shift_withdraw_form_id_default:value": null, "shift_withdraw_form_id_default:array": null, "start_timestamp": "Jun 4, 2026, 5:00 AM", "start_timestamp__date": "Jun 4, 2026", "start_timestamp__time": "5:00 AM", "start_timestamp__offset": " (+00:00 UTC)", "start_timestamp__offset_minutes": 0, "start_timestamp__dayofweek": "Thursday", "status": "Published", "status:value": "published", "status:array": "Published", "tags": null, "tags:value": null, "tags:array": null, "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "visibility_hide_groups": "", "visibility_show_groups": "", "visibility_show_roleoffer": "", "full_name": "City Marathon 2026", "event_type_name": "ratione laborum dolor", "grid_list_image": null, "is_eoi_demand_met": false, "has_payrun": false, "min_shifts": 0, "post_event_feedback_form_completed_at": null, "expression_of_interest_form_completed_at": null, "expression_of_interest_form_cancelled_at": null, "account_name": "Example Organisation", "apply": { "code": 1001, "message": "Event is closed" }, "address": "1 Example Street\nExample City\nVictoria\nAustralia\n1000", "address_oneline": "1 Example Street, Example City, Victoria, Australia, 1000", "address.latitude": null, "address.longitude": null }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "apply": false, "cancel": false, "can_publish": true }, "attributes": [] }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/me/event?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/me/event?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/me/event", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Me Module" ] } }, "/api/v2/me/inventory/item": { "get": { "summary": "List my inventory items", "operationId": "listMyInventoryItems", "description": "Returns the inventory the signed-in user holds - uniforms, equipment, passes, awards and\nanything else the organisation tracks against a person. Rows come back in the order the\nuser has arranged them.\n\nThis endpoint answers two different questions, and `assigned_only` chooses which. Left at\nits default it returns the user's **allocations**: one row per item actually issued to\nthem, carrying the allocation's own serial number, expiry and collection state. Set it to\n`0` and it returns the **catalogue** instead: the published items the user is eligible for,\nwhether or not they hold one yet.\n\nThe two modes return different shapes, so read `assigned_only` as a switch between two\nresources rather than as a filter. The example below is the default, allocation shape.\n\nAllocations that have already been collected, or whose expiry has passed, are left out of\nthe default listing.\n\nThe listing is only paginated when `page` is supplied. Without it every match is returned\nas a flat array rather than in the paged envelope.", "parameters": [ { "in": "query", "name": "assigned_only", "description": "Return the user's own allocations (`1`, the default) or\n the catalogue of items they are eligible for (`0`). The two return different shapes.", "required": false, "schema": { "type": "boolean", "description": "Return the user's own allocations (`1`, the default) or\n the catalogue of items they are eligible for (`0`). The two return different shapes.", "examples": [ true ] } }, { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "inventory_allocation_id": { "type": [ "string", "null" ], "examples": [ null ] }, "inventory_item_id": { "type": "integer", "examples": [ 1 ] }, "user_id": { "type": "integer", "examples": [ 1234 ] }, "entity": { "type": [ "string", "null" ], "examples": [ null ] }, "entity_id": { "type": [ "string", "null" ], "examples": [ null ] }, "inventory_allocation_type": { "type": "string", "examples": [ "rewards" ] }, "serial": { "type": [ "string", "null" ], "examples": [ null ] }, "inventory_item_serial_id": { "type": [ "string", "null" ], "examples": [ null ] }, "expires_at": { "type": [ "string", "null" ], "examples": [ null ] }, "collected_at": { "type": [ "string", "null" ], "examples": [ null ] }, "collected_entity": { "type": [ "string", "null" ], "examples": [ null ] }, "collected_by": { "type": [ "string", "null" ], "examples": [ null ] }, "data": { "type": [ "string", "null" ], "examples": [ null ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-01-15T04:12:07.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-01-15T04:12:07.000000Z" ] } } }, "nice": { "type": "object", "properties": { "inventory_allocation_type": { "type": "string", "examples": [ "Rewards" ] }, "user_name": { "type": "string", "examples": [ "Alex Example" ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "user_update": { "type": "boolean", "examples": [ true ] } } } } }, "examples": [ [ { "object": { "id": 1, "inventory_allocation_id": null, "inventory_item_id": 1, "user_id": 1234, "entity": null, "entity_id": null, "inventory_allocation_type": "rewards", "serial": null, "inventory_item_serial_id": null, "expires_at": null, "collected_at": null, "collected_entity": null, "collected_by": null, "data": null, "sort_order": 0, "deleted_at": null, "created_at": "2026-01-15T04:12:07.000000Z", "updated_at": "2026-01-15T04:12:07.000000Z" }, "nice": { "inventory_allocation_type": "Rewards", "user_name": "Alex Example" }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "user_update": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/me/inventory/item?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/me/inventory/item?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/me/inventory/item" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 1, "inventory_allocation_id": null, "inventory_item_id": 1, "user_id": 1234, "entity": null, "entity_id": null, "inventory_allocation_type": "rewards", "serial": null, "inventory_item_serial_id": null, "expires_at": null, "collected_at": null, "collected_entity": null, "collected_by": null, "data": null, "sort_order": 0, "deleted_at": null, "created_at": "2026-01-15T04:12:07.000000Z", "updated_at": "2026-01-15T04:12:07.000000Z" }, "nice": { "inventory_allocation_type": "Rewards", "user_name": "Alex Example" }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "user_update": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/me/inventory/item?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/me/inventory/item?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/me/inventory/item", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Me Module" ] } }, "/api/v2/me/reward-point/balance": { "get": { "summary": "Get my reward point balance", "operationId": "getMyRewardPointBalance", "description": "Returns the signed-in user's current reward point balance as a single number. The balance\nis the net of every points transaction on the account - points awarded for attending\nshifts, completing training or any other earning rule the organisation has configured,\nless anything already redeemed.\n\nThe balance is derived on read rather than stored, so it always reflects the transactions\nrecorded at the moment of the call. A user who has never earned or redeemed anything gets\n`0` rather than an error, and so does a user on an account that does not use reward points\nat all - a zero balance is not a signal that the feature is switched off.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "balance": { "type": "integer", "examples": [ 1000 ] } }, "examples": [ { "balance": 1000 } ] } } } } }, "tags": [ "Me Module" ] } }, "/api/v2/user": { "get": { "summary": "List users", "operationId": "listUsers", "description": "Returns the people on your account: their name, contact details, date of\nbirth, address, and a value for every custom attribute the account collects\nabout a person. The `nice` block repeats the same values rendered for\ndisplay - the phone number formatted for its country, the address as one\nstring, select ids resolved to their labels - so a table can be drawn\nwithout resolving anything yourself.\n\nThis is the largest response the API produces. An account with a few\nhundred people and a normal set of custom attributes runs to megabytes, so\npage it rather than reading it whole, and filter it if you are looking for\nsomeone in particular.", "parameters": [ { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "query", "name": "extras", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "required": false, "schema": { "type": "array", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "items": { "type": "string", "enum": [ "duplicate_status", "crm", "background_check_user", "login_locked", "availability", "google2fa", "high_accessibility", "locale", "timezone", "shift_hours_by_event_type", "shift_hours_by_event_type_as_string", "first_shift", "first_shift_date", "last_shift", "last_shift_date", "push_notifications" ] }, "examples": [ [ "duplicate_status" ] ] } }, { "in": "query", "name": "with", "description": "A list of relations to include in the response. May be single records or collections.\nIt is often more efficient to retrieve this way, to avoid follow-up API calls.", "required": false, "schema": { "type": "array", "description": "A list of relations to include in the response. May be single records or collections.\nIt is often more efficient to retrieve this way, to avoid follow-up API calls.", "items": { "type": "string", "enum": [ "address", "account", "user_checkpoints", "user_checkpoint", "checkpoint", "vendor_id", "entity_vendor_id", "user_type", "type", "account_roles", "training_completed", "training_incomplete", "event_feedback_completed", "role_offer_demand", "role_offer_with_demand_status", "role_offer_viable", "role_offer_pending", "role_offer_accepted", "role_offer_rejected", "background_check_user", "invitation_submitted", "form_submissions", "admin_submissions", "event_shift_applied", "event_shift_confirmed", "event_shift_rejected", "event_shift_attended", "event_attended", "event_activity_attended", "items", "certificates", "messaging_tandc_acceptance" ] }, "examples": [ [ "address" ] ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 23453479 ] }, "id_token": { "type": "string", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxx" ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "email": { "type": "string", "examples": [ "alex.taylor@example.com" ] }, "force_reset_password": { "type": "integer", "examples": [ 0 ] }, "password_expires_at": { "type": [ "string", "null" ], "examples": [ null ] }, "first_name": { "type": "string", "examples": [ "Alex" ] }, "middle_name": { "type": [ "string", "null" ], "examples": [ null ] }, "last_name": { "type": "string", "examples": [ "Taylor" ] }, "preferred_name": { "type": [ "string", "null" ], "examples": [ null ] }, "phone": { "type": "string", "examples": [ "au-390000000" ] }, "dob": { "type": "string", "examples": [ "1990-04-12" ] }, "picture": { "type": [ "string", "null" ], "examples": [ null ] }, "picture_status": { "type": "integer", "examples": [ 0 ] }, "is_subscribed": { "type": "integer", "examples": [ 0 ] }, "is_subscribed_transactional": { "type": "integer", "examples": [ 1 ] }, "is_unreachable": { "type": "integer", "examples": [ 0 ] }, "is_unreachable_sms": { "type": "integer", "examples": [ 0 ] }, "terms": { "type": "integer", "examples": [ 1 ] }, "rating": { "type": "string", "examples": [ "0.00" ] }, "shift_privacy": { "type": "integer", "examples": [ 1 ] }, "is_team_leader": { "type": "integer", "examples": [ 0 ] }, "email_verified": { "type": "integer", "examples": [ 0 ] }, "login_lockout_attempts": { "type": "integer", "examples": [ 0 ] }, "login_lockout_at": { "type": [ "string", "null" ], "examples": [ null ] }, "login_lockout_email_sent_at": { "type": [ "string", "null" ], "examples": [ null ] }, "last_login_at": { "type": [ "string", "null" ], "examples": [ null ] }, "last_app_login_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "last_activated": { "type": [ "string", "null" ], "examples": [ null ] }, "from_source": { "type": [ "string", "null" ], "examples": [ null ] }, "delete_requested_at": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-05-29T18:30:58.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:35:38.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "interests": { "type": [ "string", "null" ], "examples": [ null ] }, "address": { "type": "object", "properties": { "iso": { "type": "string", "examples": [ "AUS" ] }, "region_code": { "type": "string", "examples": [ "VIC" ] }, "coordinates": { "type": "object", "properties": { "latitude": { "type": "string", "examples": [ "-37.814000" ] }, "longitude": { "type": "string", "examples": [ "144.963200" ] } } }, "street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "city": { "type": "string", "examples": [ "Melbourne" ] }, "postcode": { "type": "string", "examples": [ "3000" ] }, "region": { "type": "string", "examples": [ "VIC" ] }, "country": { "type": "string", "examples": [ "AU" ] }, "latitude": { "type": "string", "examples": [ "-37.814000" ] }, "longitude": { "type": "string", "examples": [ "144.963200" ] } } } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:user:xxxxxxxxxxxxxxxxxxxxxxxx" ] }, "address": { "type": "string", "examples": [ "1 Example Street\nMelbourne\nVictoria\nAustralia\n3000" ] }, "address_oneline": { "type": "string", "examples": [ "1 Example Street, Melbourne, Victoria, Australia, 3000" ] }, "address.country": { "type": "string", "examples": [ "Australia" ] }, "address.country:raw": { "type": "string", "examples": [ "AUS" ] }, "address.city": { "type": "string", "examples": [ "Melbourne" ] }, "address.region": { "type": "string", "examples": [ "Victoria" ] }, "address.region:raw": { "type": "string", "examples": [ "VIC" ] }, "address.postcode": { "type": "string", "examples": [ "3000" ] }, "address.street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "address.street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "address.street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "address.latitude": { "type": "string", "examples": [ "-37.814000" ] }, "address.longitude": { "type": "string", "examples": [ "144.963200" ] }, "family_id": { "type": [ "string", "null" ], "examples": [ null ] }, "has_family_members": { "type": "string", "examples": [ "No" ] }, "manages_family": { "type": "boolean", "examples": [ false ] }, "family_manager": { "type": "string", "examples": [ "No" ] }, "family_member": { "type": "string", "examples": [ "No" ] }, "is_family_member": { "type": "boolean", "examples": [ false ] }, "is_engaged": { "type": "string", "examples": [ "No" ] }, "is_engaged:raw": { "type": "boolean", "examples": [ false ] }, "last_engaged_at": { "type": [ "string", "null" ], "examples": [ null ] }, "last_engaged_at:raw": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "May 29, 2026, 6:30 PM" ] }, "created_at__date": { "type": "string", "examples": [ "May 29, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "6:30 PM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Friday" ] }, "email_verified": { "type": "string", "examples": [ "No" ] }, "from_source": { "type": "string", "examples": [ "" ] }, "interests": { "type": [ "string", "null" ], "examples": [ null ] }, "interests:value": { "type": [ "string", "null" ], "examples": [ null ] }, "interests:array": { "type": [ "string", "null" ], "examples": [ null ] }, "is_subscribed_transactional": { "type": "string", "examples": [ "Yes" ] }, "is_team_leader": { "type": "string", "examples": [ "No" ] }, "middle_name": { "type": "string", "examples": [ "" ] }, "picture_status": { "type": "string", "examples": [ "N/A" ] }, "picture_status:value": { "type": "integer", "examples": [ 0 ] }, "picture_status:array": { "type": "string", "examples": [ "N/A" ] }, "shift_privacy": { "type": "string", "examples": [ "Yes" ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:35 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:35 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "first_name": { "type": "string", "examples": [ "Alex" ] }, "last_name": { "type": "string", "examples": [ "Taylor" ] }, "preferred_name": { "type": "string", "examples": [ "" ] }, "phone:qr_code_value": { "type": "string", "examples": [ "au-390000000" ] }, "phone": { "type": "string", "examples": [ "(+61) 390000000" ] }, "phone:raw": { "type": "string", "examples": [ "+61390000000" ] }, "phone:local_au": { "type": "string", "examples": [ "0390000000" ] }, "dob": { "type": "string", "examples": [ "Apr 12, 1990" ] }, "dob__dayofweek": { "type": "string", "examples": [ "Thursday" ] }, "is_subscribed": { "type": "string", "examples": [ "No" ] }, "terms": { "type": "string", "examples": [ "Yes" ] }, "name": { "type": "string", "examples": [ "Alex Taylor" ] }, "age": { "type": "integer", "examples": [ 36 ] }, "age_months": { "type": "string", "examples": [ "36 years, 4 months" ] }, "info": { "type": "string", "examples": [ "Alex Taylor (alex.taylor@example.com)" ] }, "preferred_first_name": { "type": "string", "examples": [ "Alex" ] }, "delete_requested": { "type": "boolean", "examples": [ false ] }, "updated_hours": { "type": "number", "examples": [ 1673.4862143775 ] }, "is_community_user": { "type": "boolean", "examples": [ false ] }, "timezone": { "type": "string", "examples": [ "UTC" ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } }, "attributes": { "type": "array", "examples": [ [] ] }, "id": { "type": "integer", "examples": [ 23453479 ] }, "name": { "type": "string", "examples": [ "Alex Taylor" ] } } }, "examples": [ [ { "object": { "id": 23453479, "id_token": "xxxxxxxxxxxxxxxxxxxxxxxx", "account_id": 20101, "email": "alex.taylor@example.com", "force_reset_password": 0, "password_expires_at": null, "first_name": "Alex", "middle_name": null, "last_name": "Taylor", "preferred_name": null, "phone": "au-390000000", "dob": "1990-04-12", "picture": null, "picture_status": 0, "is_subscribed": 0, "is_subscribed_transactional": 1, "is_unreachable": 0, "is_unreachable_sms": 0, "terms": 1, "rating": "0.00", "shift_privacy": 1, "is_team_leader": 0, "email_verified": 0, "login_lockout_attempts": 0, "login_lockout_at": null, "login_lockout_email_sent_at": null, "last_login_at": null, "last_app_login_at": null, "is_archived": 0, "last_activated": null, "from_source": null, "delete_requested_at": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-05-29T18:30:58.000000Z", "updated_at": "2026-06-09T05:35:38.000000Z", "deleted_by": null, "interests": null, "address": { "iso": "AUS", "region_code": "VIC", "coordinates": { "latitude": "-37.814000", "longitude": "144.963200" }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "Melbourne", "postcode": "3000", "region": "VIC", "country": "AU", "latitude": "-37.814000", "longitude": "144.963200" } }, "nice": { "rrn": "rrn:local:20101:user:xxxxxxxxxxxxxxxxxxxxxxxx", "address": "1 Example Street\nMelbourne\nVictoria\nAustralia\n3000", "address_oneline": "1 Example Street, Melbourne, Victoria, Australia, 3000", "address.country": "Australia", "address.country:raw": "AUS", "address.city": "Melbourne", "address.region": "Victoria", "address.region:raw": "VIC", "address.postcode": "3000", "address.street_address_1": "1 Example Street", "address.street_address_2": null, "address.street_address_3": null, "address.latitude": "-37.814000", "address.longitude": "144.963200", "family_id": null, "has_family_members": "No", "manages_family": false, "family_manager": "No", "family_member": "No", "is_family_member": false, "is_engaged": "No", "is_engaged:raw": false, "last_engaged_at": null, "last_engaged_at:raw": null, "created_at": "May 29, 2026, 6:30 PM", "created_at__date": "May 29, 2026", "created_at__time": "6:30 PM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Friday", "email_verified": "No", "from_source": "", "interests": null, "interests:value": null, "interests:array": null, "is_subscribed_transactional": "Yes", "is_team_leader": "No", "middle_name": "", "picture_status": "N/A", "picture_status:value": 0, "picture_status:array": "N/A", "shift_privacy": "Yes", "updated_at": "Jun 9, 2026, 5:35 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:35 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "first_name": "Alex", "last_name": "Taylor", "preferred_name": "", "phone:qr_code_value": "au-390000000", "phone": "(+61) 390000000", "phone:raw": "+61390000000", "phone:local_au": "0390000000", "dob": "Apr 12, 1990", "dob__dayofweek": "Thursday", "is_subscribed": "No", "terms": "Yes", "name": "Alex Taylor", "age": 36, "age_months": "36 years, 4 months", "info": "Alex Taylor (alex.taylor@example.com)", "preferred_first_name": "Alex", "delete_requested": false, "updated_hours": 1673.4862143775, "is_community_user": false, "timezone": "UTC" }, "relations": [], "permissions": { "read": true, "update": true, "delete": true }, "attributes": [], "id": 23453479, "name": "Alex Taylor" }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/user?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/user?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/user" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 23453479, "id_token": "xxxxxxxxxxxxxxxxxxxxxxxx", "account_id": 20101, "email": "alex.taylor@example.com", "force_reset_password": 0, "password_expires_at": null, "first_name": "Alex", "middle_name": null, "last_name": "Taylor", "preferred_name": null, "phone": "au-390000000", "dob": "1990-04-12", "picture": null, "picture_status": 0, "is_subscribed": 0, "is_subscribed_transactional": 1, "is_unreachable": 0, "is_unreachable_sms": 0, "terms": 1, "rating": "0.00", "shift_privacy": 1, "is_team_leader": 0, "email_verified": 0, "login_lockout_attempts": 0, "login_lockout_at": null, "login_lockout_email_sent_at": null, "last_login_at": null, "last_app_login_at": null, "is_archived": 0, "last_activated": null, "from_source": null, "delete_requested_at": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-05-29T18:30:58.000000Z", "updated_at": "2026-06-09T05:35:38.000000Z", "deleted_by": null, "interests": null, "address": { "iso": "AUS", "region_code": "VIC", "coordinates": { "latitude": "-37.814000", "longitude": "144.963200" }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "Melbourne", "postcode": "3000", "region": "VIC", "country": "AU", "latitude": "-37.814000", "longitude": "144.963200" } }, "nice": { "rrn": "rrn:local:20101:user:xxxxxxxxxxxxxxxxxxxxxxxx", "address": "1 Example Street\nMelbourne\nVictoria\nAustralia\n3000", "address_oneline": "1 Example Street, Melbourne, Victoria, Australia, 3000", "address.country": "Australia", "address.country:raw": "AUS", "address.city": "Melbourne", "address.region": "Victoria", "address.region:raw": "VIC", "address.postcode": "3000", "address.street_address_1": "1 Example Street", "address.street_address_2": null, "address.street_address_3": null, "address.latitude": "-37.814000", "address.longitude": "144.963200", "family_id": null, "has_family_members": "No", "manages_family": false, "family_manager": "No", "family_member": "No", "is_family_member": false, "is_engaged": "No", "is_engaged:raw": false, "last_engaged_at": null, "last_engaged_at:raw": null, "created_at": "May 29, 2026, 6:30 PM", "created_at__date": "May 29, 2026", "created_at__time": "6:30 PM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Friday", "email_verified": "No", "from_source": "", "interests": null, "interests:value": null, "interests:array": null, "is_subscribed_transactional": "Yes", "is_team_leader": "No", "middle_name": "", "picture_status": "N/A", "picture_status:value": 0, "picture_status:array": "N/A", "shift_privacy": "Yes", "updated_at": "Jun 9, 2026, 5:35 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:35 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "first_name": "Alex", "last_name": "Taylor", "preferred_name": "", "phone:qr_code_value": "au-390000000", "phone": "(+61) 390000000", "phone:raw": "+61390000000", "phone:local_au": "0390000000", "dob": "Apr 12, 1990", "dob__dayofweek": "Thursday", "is_subscribed": "No", "terms": "Yes", "name": "Alex Taylor", "age": 36, "age_months": "36 years, 4 months", "info": "Alex Taylor (alex.taylor@example.com)", "preferred_first_name": "Alex", "delete_requested": false, "updated_hours": 1673.4862143775, "is_community_user": false, "timezone": "UTC" }, "relations": [], "permissions": { "read": true, "update": true, "delete": true }, "attributes": [], "id": 23453479, "name": "Alex Taylor" }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/user?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/user?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/user", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "User Module" ] }, "post": { "summary": "Create a user", "operationId": "createAUser", "description": "Adds a person to your account and returns the created record. The response\ncarries only the fields the create actually set, so it is a smaller object\nthan reading the same person back afterwards - read them again if you need\nthe full record.\n\n**Which fields are required depends on the account.** `first_name` and\n`last_name` always are. Whether `email` and `dob` are required is an account\nsetting, so the same body can be accepted on one account and rejected on\nanother; if you integrate against several, send both.\n\nCustom attributes are sent alongside the fields below, under the codes the\naccount defines for them. Creating a person may send them a welcome email,\ndepending on how the account is configured.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "email": { "type": "string", "examples": [ "alex.taylor@example.com" ] }, "first_name": { "type": "string", "examples": [ "Alex" ] }, "last_name": { "type": "string", "examples": [ "Taylor" ] }, "dob": { "type": "string", "examples": [ "1990-04-12" ] }, "phone": { "type": "string", "examples": [ "au-390000000" ] }, "terms": { "type": "boolean", "examples": [ true ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "is_unreachable": { "type": "integer", "examples": [ 0 ] }, "email_verified": { "type": "integer", "examples": [ 0 ] }, "is_unreachable_sms": { "type": "integer", "examples": [ 0 ] }, "id_token": { "type": "string", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxx" ] }, "is_subscribed_transactional": { "type": "boolean", "examples": [ true ] }, "updated_at": { "type": "string", "examples": [ "2026-08-17T23:04:48.000000Z" ] }, "created_at": { "type": "string", "examples": [ "2026-08-17T23:04:48.000000Z" ] }, "id": { "type": "integer", "examples": [ 23453703 ] }, "interests": { "type": [ "string", "null" ], "examples": [ null ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:user:xxxxxxxxxxxxxxxxxxxxxxxx" ] }, "address": { "type": "string", "examples": [ "No Address" ] }, "address_oneline": { "type": "string", "examples": [ "No Address" ] }, "family_id": { "type": [ "string", "null" ], "examples": [ null ] }, "has_family_members": { "type": "string", "examples": [ "No" ] }, "manages_family": { "type": "boolean", "examples": [ false ] }, "family_manager": { "type": "string", "examples": [ "No" ] }, "family_member": { "type": "string", "examples": [ "No" ] }, "is_family_member": { "type": "boolean", "examples": [ false ] }, "is_engaged": { "type": "string", "examples": [ "No" ] }, "is_engaged:raw": { "type": "boolean", "examples": [ false ] }, "last_engaged_at": { "type": [ "string", "null" ], "examples": [ null ] }, "last_engaged_at:raw": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "Aug 17, 2026, 11:04 PM" ] }, "created_at__date": { "type": "string", "examples": [ "Aug 17, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "11:04 PM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Monday" ] }, "email_verified": { "type": "string", "examples": [ "No" ] }, "from_source": { "type": "string", "examples": [ "" ] }, "interests": { "type": [ "string", "null" ], "examples": [ null ] }, "interests:value": { "type": [ "string", "null" ], "examples": [ null ] }, "interests:array": { "type": [ "string", "null" ], "examples": [ null ] }, "is_subscribed_transactional": { "type": "string", "examples": [ "Yes" ] }, "is_team_leader": { "type": "string", "examples": [ "No" ] }, "middle_name": { "type": "string", "examples": [ "" ] }, "picture_status": { "type": "string", "examples": [ "N/A" ] }, "picture_status:value": { "type": [ "string", "null" ], "examples": [ null ] }, "picture_status:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_privacy": { "type": "string", "examples": [ "No" ] }, "updated_at": { "type": "string", "examples": [ "Aug 17, 2026, 11:04 PM" ] }, "updated_at__date": { "type": "string", "examples": [ "Aug 17, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "11:04 PM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Monday" ] }, "first_name": { "type": "string", "examples": [ "Alex" ] }, "last_name": { "type": "string", "examples": [ "Taylor" ] }, "preferred_name": { "type": "string", "examples": [ "" ] }, "phone:qr_code_value": { "type": "string", "examples": [ "au-390000000" ] }, "phone": { "type": "string", "examples": [ "(+61) 390000000" ] }, "phone:raw": { "type": "string", "examples": [ "+61390000000" ] }, "phone:local_au": { "type": "string", "examples": [ "0390000000" ] }, "dob": { "type": "string", "examples": [ "Apr 12, 1990" ] }, "dob__dayofweek": { "type": "string", "examples": [ "Thursday" ] }, "is_subscribed": { "type": "string", "examples": [ "No" ] }, "terms": { "type": "string", "examples": [ "Yes" ] }, "name": { "type": "string", "examples": [ "Alex Taylor" ] }, "age": { "type": "integer", "examples": [ 36 ] }, "age_months": { "type": "string", "examples": [ "36 years, 4 months" ] }, "info": { "type": "string", "examples": [ "Alex Taylor (alex.taylor@example.com)" ] }, "preferred_first_name": { "type": "string", "examples": [ "Alex" ] }, "delete_requested": { "type": "boolean", "examples": [ false ] }, "updated_hours": { "type": "number", "examples": [ 0.00041929472222222 ] }, "is_community_user": { "type": "boolean", "examples": [ false ] }, "timezone": { "type": "string", "examples": [ "UTC" ] } } }, "relations": { "type": "object", "properties": { "family_user": { "type": [ "string", "null" ], "examples": [ null ] }, "user_type": { "type": [ "string", "null" ], "examples": [ null ] }, "user_checkpoint": { "type": [ "string", "null" ], "examples": [ null ] }, "family": { "type": [ "string", "null" ], "examples": [ null ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "impersonate": { "type": "boolean", "examples": [ true ] } } }, "attributes": { "type": "object", "properties": {} }, "id": { "type": "integer", "examples": [ 23453703 ] }, "name": { "type": "string", "examples": [ "Alex Taylor" ] } }, "examples": [ { "object": { "email": "alex.taylor@example.com", "first_name": "Alex", "last_name": "Taylor", "dob": "1990-04-12", "phone": "au-390000000", "terms": true, "account_id": 20101, "is_unreachable": 0, "email_verified": 0, "is_unreachable_sms": 0, "id_token": "xxxxxxxxxxxxxxxxxxxxxxxx", "is_subscribed_transactional": true, "updated_at": "2026-08-17T23:04:48.000000Z", "created_at": "2026-08-17T23:04:48.000000Z", "id": 23453703, "interests": null }, "nice": { "rrn": "rrn:local:20101:user:xxxxxxxxxxxxxxxxxxxxxxxx", "address": "No Address", "address_oneline": "No Address", "family_id": null, "has_family_members": "No", "manages_family": false, "family_manager": "No", "family_member": "No", "is_family_member": false, "is_engaged": "No", "is_engaged:raw": false, "last_engaged_at": null, "last_engaged_at:raw": null, "created_at": "Aug 17, 2026, 11:04 PM", "created_at__date": "Aug 17, 2026", "created_at__time": "11:04 PM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Monday", "email_verified": "No", "from_source": "", "interests": null, "interests:value": null, "interests:array": null, "is_subscribed_transactional": "Yes", "is_team_leader": "No", "middle_name": "", "picture_status": "N/A", "picture_status:value": null, "picture_status:array": null, "shift_privacy": "No", "updated_at": "Aug 17, 2026, 11:04 PM", "updated_at__date": "Aug 17, 2026", "updated_at__time": "11:04 PM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Monday", "first_name": "Alex", "last_name": "Taylor", "preferred_name": "", "phone:qr_code_value": "au-390000000", "phone": "(+61) 390000000", "phone:raw": "+61390000000", "phone:local_au": "0390000000", "dob": "Apr 12, 1990", "dob__dayofweek": "Thursday", "is_subscribed": "No", "terms": "Yes", "name": "Alex Taylor", "age": 36, "age_months": "36 years, 4 months", "info": "Alex Taylor (alex.taylor@example.com)", "preferred_first_name": "Alex", "delete_requested": false, "updated_hours": 0.00041929472222222, "is_community_user": false, "timezone": "UTC" }, "relations": { "family_user": null, "user_type": null, "user_checkpoint": null, "family": null }, "permissions": { "read": true, "update": true, "delete": true, "impersonate": true }, "attributes": {}, "id": 23453703, "name": "Alex Taylor" } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Sorry, we found issues with some of the submitted data - please review and try again." ] }, "errors": { "type": "object", "properties": { "first_name": { "type": "array", "items": { "type": "string" }, "examples": [ [ "Field is required." ] ] }, "last_name": { "type": "array", "items": { "type": "string" }, "examples": [ [ "Field is required." ] ] } } } }, "examples": [ { "message": "Sorry, we found issues with some of the submitted data - please review and try again.", "errors": { "first_name": [ "Field is required." ], "last_name": [ "Field is required." ] } } ] } } } } }, "tags": [ "User Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address of the User. Must be unique.", "examples": [ "alex.taylor@example.com" ] }, "first_name": { "type": "string", "description": "The first name of the User", "examples": [ "Alex" ] }, "last_name": { "type": "string", "description": "The last name of the User", "examples": [ "Taylor" ] }, "dob": { "type": "string", "description": "Date of birth in Y-m-d format", "examples": [ "1990-04-12" ] }, "phone": { "type": "string", "description": "Phone number", "examples": [ "au-390000000" ] }, "terms": { "type": "boolean", "description": "Whether the User has accepted the terms and conditions.", "examples": [ true ] }, "address": { "type": "object", "description": "The address of the User.", "properties": {}, "examples": [ { "street": "123 Example St", "city": "Example City", "state": "EX", "postcode": "12345", "country": "Example Country" } ] }, "picture": { "type": "string", "description": "", "examples": [ null ] }, "account_role": { "type": "array", "description": "An ID of an account role (Admin Permission) to place User into.", "items": { "type": "string" }, "examples": [ [] ] }, "user_checkpoint_id": { "type": "integer", "description": "The ID of the checkpoint the user should be placed into.", "examples": [ 1 ] }, "user_type_id": { "type": "integer", "description": "Set the User Type of the User.", "examples": [ 1 ] }, "invitation_token": { "type": "string", "description": "", "examples": [ null ] }, "custom_*": { "type": "string", "description": "A custom attribute, named by its code - custom_shirt_size, for example. The value follows the attribute's own type, so it may be a string, a number, a boolean or a list. See the custom attributes documentation.", "examples": [ null ] } }, "required": [ "email", "first_name", "last_name", "dob", "terms" ] } } } } }, "put": { "summary": "Update many users at once", "operationId": "updateManyUsersAtOnce", "description": "Applies one set of changes to many people and returns a token identifying\nthe queued job. The work happens in the background, so a `200` means the\nrequest was accepted, not that every record has been updated.\n\nChoose the people either explicitly or by filter. `applyTo` of `selected`\ntakes the ids in `selected`; `applyTo` of `all` takes everyone your token\nmay read, narrowed by `filter` if you send one and to a single group if you\nsend `group_id`.\n\n**The fields you may change are the ones `PUT /user/{id}` accepts**,\nincluding the account's custom attributes, sent the same way. Two rules\ndiffer from the single update. Every field you send is applied to every\nperson selected, so a field left out of the body is the only way to leave it\nalone - and if you are building a form that offers \"keep existing value\" per\nfield, send that field with a companion `:use_default` of `true` and\nit will be skipped.\n\nRecords that fail validation individually are reported against the job\nrather than rejecting the whole request, so a token can come back for a\nrequest that ends up changing nothing.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "queue": { "type": "string", "examples": [ "mTsVQ1NCLS3vg7WwP5kG1Vbt" ] } }, "examples": [ { "queue": "mTsVQ1NCLS3vg7WwP5kG1Vbt" } ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Sorry, we found issues with some of the submitted data - please review and try again." ] }, "errors": { "type": "object", "properties": { "selected": { "type": "array", "items": { "type": "string" }, "examples": [ [ "Please select at least one User" ] ] } } } }, "examples": [ { "message": "Sorry, we found issues with some of the submitted data - please review and try again.", "errors": { "selected": [ "Please select at least one User" ] } } ] } } } } }, "tags": [ "User Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "filter": { "type": "array", "description": "The filter structure the listing accepts. Used when `applyTo` is `all`.", "items": { "type": "object" }, "examples": [ [ [] ] ] }, "group_id": { "type": "integer", "description": "Narrows an `applyTo` of `all` to the members of one group. Not validated.", "examples": [ 16 ] }, "applyTo": { "type": "string", "description": "Whether to update the ids in `selected`, or everyone the request matches. One of `selected` or `all`.", "examples": [ null ] }, "selected": { "type": "array", "description": "IDs of the users to update. Required unless `applyTo` is `all`.", "items": { "type": "integer" }, "examples": [ [] ] }, "custom_*": { "type": "string", "description": "A custom attribute, named by its code - custom_shirt_size, for example. The value follows the attribute's own type, so it may be a string, a number, a boolean or a list. See the custom attributes documentation.", "examples": [ null ] } } } } } } } }, "/api/v2/user/{id}": { "get": { "summary": "Read a user", "operationId": "readAUser", "description": "Returns one person's record: contact details, date of birth, address,\nsubscription and verification state, and a value for every custom attribute\nthe account collects. The `nice` block repeats those values rendered for\ndisplay, and `permissions` says what your token may go on to do with this\nperson.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 23453479 ] }, "id_token": { "type": "string", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxx" ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "email": { "type": "string", "examples": [ "alex.taylor@example.com" ] }, "force_reset_password": { "type": "integer", "examples": [ 0 ] }, "password_expires_at": { "type": [ "string", "null" ], "examples": [ null ] }, "first_name": { "type": "string", "examples": [ "Alex" ] }, "middle_name": { "type": [ "string", "null" ], "examples": [ null ] }, "last_name": { "type": "string", "examples": [ "Taylor" ] }, "preferred_name": { "type": [ "string", "null" ], "examples": [ null ] }, "phone": { "type": "string", "examples": [ "au-390000000" ] }, "dob": { "type": "string", "examples": [ "1990-04-12" ] }, "picture": { "type": [ "string", "null" ], "examples": [ null ] }, "picture_status": { "type": "integer", "examples": [ 0 ] }, "is_subscribed": { "type": "integer", "examples": [ 0 ] }, "is_subscribed_transactional": { "type": "integer", "examples": [ 1 ] }, "is_unreachable": { "type": "integer", "examples": [ 0 ] }, "is_unreachable_sms": { "type": "integer", "examples": [ 0 ] }, "terms": { "type": "integer", "examples": [ 1 ] }, "rating": { "type": "string", "examples": [ "0.00" ] }, "shift_privacy": { "type": "integer", "examples": [ 1 ] }, "is_team_leader": { "type": "integer", "examples": [ 0 ] }, "email_verified": { "type": "integer", "examples": [ 0 ] }, "login_lockout_attempts": { "type": "integer", "examples": [ 0 ] }, "login_lockout_at": { "type": [ "string", "null" ], "examples": [ null ] }, "login_lockout_email_sent_at": { "type": [ "string", "null" ], "examples": [ null ] }, "last_login_at": { "type": [ "string", "null" ], "examples": [ null ] }, "last_app_login_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "last_activated": { "type": [ "string", "null" ], "examples": [ null ] }, "from_source": { "type": [ "string", "null" ], "examples": [ null ] }, "delete_requested_at": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-05-29T18:30:58.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:35:38.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "interests": { "type": [ "string", "null" ], "examples": [ null ] }, "address": { "type": "object", "properties": { "iso": { "type": "string", "examples": [ "AUS" ] }, "region_code": { "type": "string", "examples": [ "VIC" ] }, "coordinates": { "type": "object", "properties": { "latitude": { "type": "string", "examples": [ "-37.814000" ] }, "longitude": { "type": "string", "examples": [ "144.963200" ] } } }, "street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "city": { "type": "string", "examples": [ "Melbourne" ] }, "postcode": { "type": "string", "examples": [ "3000" ] }, "region": { "type": "string", "examples": [ "VIC" ] }, "country": { "type": "string", "examples": [ "AU" ] }, "latitude": { "type": "string", "examples": [ "-37.814000" ] }, "longitude": { "type": "string", "examples": [ "144.963200" ] } } } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:user:xxxxxxxxxxxxxxxxxxxxxxxx" ] }, "address": { "type": "string", "examples": [ "1 Example Street\nMelbourne\nVictoria\nAustralia\n3000" ] }, "address_oneline": { "type": "string", "examples": [ "1 Example Street, Melbourne, Victoria, Australia, 3000" ] }, "address.country": { "type": "string", "examples": [ "Australia" ] }, "address.country:raw": { "type": "string", "examples": [ "AUS" ] }, "address.city": { "type": "string", "examples": [ "Melbourne" ] }, "address.region": { "type": "string", "examples": [ "Victoria" ] }, "address.region:raw": { "type": "string", "examples": [ "VIC" ] }, "address.postcode": { "type": "string", "examples": [ "3000" ] }, "address.street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "address.street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "address.street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "address.latitude": { "type": "string", "examples": [ "-37.814000" ] }, "address.longitude": { "type": "string", "examples": [ "144.963200" ] }, "family_id": { "type": [ "string", "null" ], "examples": [ null ] }, "has_family_members": { "type": "string", "examples": [ "No" ] }, "manages_family": { "type": "boolean", "examples": [ false ] }, "family_manager": { "type": "string", "examples": [ "No" ] }, "family_member": { "type": "string", "examples": [ "No" ] }, "is_family_member": { "type": "boolean", "examples": [ false ] }, "is_engaged": { "type": "string", "examples": [ "No" ] }, "is_engaged:raw": { "type": "boolean", "examples": [ false ] }, "last_engaged_at": { "type": [ "string", "null" ], "examples": [ null ] }, "last_engaged_at:raw": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "May 29, 2026, 6:30 PM" ] }, "created_at__date": { "type": "string", "examples": [ "May 29, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "6:30 PM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Friday" ] }, "email_verified": { "type": "string", "examples": [ "No" ] }, "from_source": { "type": "string", "examples": [ "" ] }, "interests": { "type": [ "string", "null" ], "examples": [ null ] }, "interests:value": { "type": [ "string", "null" ], "examples": [ null ] }, "interests:array": { "type": [ "string", "null" ], "examples": [ null ] }, "is_subscribed_transactional": { "type": "string", "examples": [ "Yes" ] }, "is_team_leader": { "type": "string", "examples": [ "No" ] }, "middle_name": { "type": "string", "examples": [ "" ] }, "picture_status": { "type": "string", "examples": [ "N/A" ] }, "picture_status:value": { "type": "integer", "examples": [ 0 ] }, "picture_status:array": { "type": "string", "examples": [ "N/A" ] }, "shift_privacy": { "type": "string", "examples": [ "Yes" ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:35 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:35 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "first_name": { "type": "string", "examples": [ "Alex" ] }, "last_name": { "type": "string", "examples": [ "Taylor" ] }, "preferred_name": { "type": "string", "examples": [ "" ] }, "phone:qr_code_value": { "type": "string", "examples": [ "au-390000000" ] }, "phone": { "type": "string", "examples": [ "(+61) 390000000" ] }, "phone:raw": { "type": "string", "examples": [ "+61390000000" ] }, "phone:local_au": { "type": "string", "examples": [ "0390000000" ] }, "dob": { "type": "string", "examples": [ "Apr 12, 1990" ] }, "dob__dayofweek": { "type": "string", "examples": [ "Thursday" ] }, "is_subscribed": { "type": "string", "examples": [ "No" ] }, "terms": { "type": "string", "examples": [ "Yes" ] }, "name": { "type": "string", "examples": [ "Alex Taylor" ] }, "age": { "type": "integer", "examples": [ 36 ] }, "age_months": { "type": "string", "examples": [ "36 years, 4 months" ] }, "info": { "type": "string", "examples": [ "Alex Taylor (alex.taylor@example.com)" ] }, "preferred_first_name": { "type": "string", "examples": [ "Alex" ] }, "delete_requested": { "type": "boolean", "examples": [ false ] }, "updated_hours": { "type": "number", "examples": [ 1673.4862143775 ] }, "is_community_user": { "type": "boolean", "examples": [ false ] }, "timezone": { "type": "string", "examples": [ "UTC" ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } }, "attributes": { "type": "object", "properties": {} }, "id": { "type": "integer", "examples": [ 23453479 ] }, "name": { "type": "string", "examples": [ "Alex Taylor" ] } }, "examples": [ { "object": { "id": 23453479, "id_token": "xxxxxxxxxxxxxxxxxxxxxxxx", "account_id": 20101, "email": "alex.taylor@example.com", "force_reset_password": 0, "password_expires_at": null, "first_name": "Alex", "middle_name": null, "last_name": "Taylor", "preferred_name": null, "phone": "au-390000000", "dob": "1990-04-12", "picture": null, "picture_status": 0, "is_subscribed": 0, "is_subscribed_transactional": 1, "is_unreachable": 0, "is_unreachable_sms": 0, "terms": 1, "rating": "0.00", "shift_privacy": 1, "is_team_leader": 0, "email_verified": 0, "login_lockout_attempts": 0, "login_lockout_at": null, "login_lockout_email_sent_at": null, "last_login_at": null, "last_app_login_at": null, "is_archived": 0, "last_activated": null, "from_source": null, "delete_requested_at": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-05-29T18:30:58.000000Z", "updated_at": "2026-06-09T05:35:38.000000Z", "deleted_by": null, "interests": null, "address": { "iso": "AUS", "region_code": "VIC", "coordinates": { "latitude": "-37.814000", "longitude": "144.963200" }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "Melbourne", "postcode": "3000", "region": "VIC", "country": "AU", "latitude": "-37.814000", "longitude": "144.963200" } }, "nice": { "rrn": "rrn:local:20101:user:xxxxxxxxxxxxxxxxxxxxxxxx", "address": "1 Example Street\nMelbourne\nVictoria\nAustralia\n3000", "address_oneline": "1 Example Street, Melbourne, Victoria, Australia, 3000", "address.country": "Australia", "address.country:raw": "AUS", "address.city": "Melbourne", "address.region": "Victoria", "address.region:raw": "VIC", "address.postcode": "3000", "address.street_address_1": "1 Example Street", "address.street_address_2": null, "address.street_address_3": null, "address.latitude": "-37.814000", "address.longitude": "144.963200", "family_id": null, "has_family_members": "No", "manages_family": false, "family_manager": "No", "family_member": "No", "is_family_member": false, "is_engaged": "No", "is_engaged:raw": false, "last_engaged_at": null, "last_engaged_at:raw": null, "created_at": "May 29, 2026, 6:30 PM", "created_at__date": "May 29, 2026", "created_at__time": "6:30 PM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Friday", "email_verified": "No", "from_source": "", "interests": null, "interests:value": null, "interests:array": null, "is_subscribed_transactional": "Yes", "is_team_leader": "No", "middle_name": "", "picture_status": "N/A", "picture_status:value": 0, "picture_status:array": "N/A", "shift_privacy": "Yes", "updated_at": "Jun 9, 2026, 5:35 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:35 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "first_name": "Alex", "last_name": "Taylor", "preferred_name": "", "phone:qr_code_value": "au-390000000", "phone": "(+61) 390000000", "phone:raw": "+61390000000", "phone:local_au": "0390000000", "dob": "Apr 12, 1990", "dob__dayofweek": "Thursday", "is_subscribed": "No", "terms": "Yes", "name": "Alex Taylor", "age": 36, "age_months": "36 years, 4 months", "info": "Alex Taylor (alex.taylor@example.com)", "preferred_first_name": "Alex", "delete_requested": false, "updated_hours": 1673.4862143775, "is_community_user": false, "timezone": "UTC" }, "relations": [], "permissions": { "read": true, "update": true, "delete": true }, "attributes": {}, "id": 23453479, "name": "Alex Taylor" } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "User Module" ] }, "put": { "summary": "Update a user", "operationId": "updateAUser", "description": "Updates one person's record and returns it, the same shape as reading it\nback. Every field is optional, so a body carrying only what changed is safe\n- fields you leave out keep their current values.\n\nCustom attributes are sent alongside the fields below, under the codes the\naccount defines for them. Send `account_role` to change the administrative\nrole this person holds on the account; a role your own token may not grant\nis rejected as a validation error against that field.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 23453479 ] }, "id_token": { "type": "string", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxx" ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "email": { "type": "string", "examples": [ "alex.taylor@example.com" ] }, "force_reset_password": { "type": "integer", "examples": [ 0 ] }, "password_expires_at": { "type": [ "string", "null" ], "examples": [ null ] }, "first_name": { "type": "string", "examples": [ "Alex" ] }, "middle_name": { "type": [ "string", "null" ], "examples": [ null ] }, "last_name": { "type": "string", "examples": [ "Taylor" ] }, "preferred_name": { "type": [ "string", "null" ], "examples": [ null ] }, "phone": { "type": "string", "examples": [ "au-390000000" ] }, "dob": { "type": "string", "examples": [ "1990-04-12" ] }, "picture": { "type": [ "string", "null" ], "examples": [ null ] }, "picture_status": { "type": "integer", "examples": [ 0 ] }, "is_subscribed": { "type": "integer", "examples": [ 0 ] }, "is_subscribed_transactional": { "type": "integer", "examples": [ 1 ] }, "is_unreachable": { "type": "integer", "examples": [ 0 ] }, "is_unreachable_sms": { "type": "integer", "examples": [ 0 ] }, "terms": { "type": "integer", "examples": [ 1 ] }, "rating": { "type": "string", "examples": [ "0.00" ] }, "shift_privacy": { "type": "integer", "examples": [ 1 ] }, "is_team_leader": { "type": "integer", "examples": [ 0 ] }, "email_verified": { "type": "integer", "examples": [ 0 ] }, "login_lockout_attempts": { "type": "integer", "examples": [ 0 ] }, "login_lockout_at": { "type": [ "string", "null" ], "examples": [ null ] }, "login_lockout_email_sent_at": { "type": [ "string", "null" ], "examples": [ null ] }, "last_login_at": { "type": [ "string", "null" ], "examples": [ null ] }, "last_app_login_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "last_activated": { "type": [ "string", "null" ], "examples": [ null ] }, "from_source": { "type": [ "string", "null" ], "examples": [ null ] }, "delete_requested_at": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-05-29T18:30:58.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:35:38.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "interests": { "type": [ "string", "null" ], "examples": [ null ] }, "address": { "type": "object", "properties": { "iso": { "type": "string", "examples": [ "AUS" ] }, "region_code": { "type": "string", "examples": [ "VIC" ] }, "coordinates": { "type": "object", "properties": { "latitude": { "type": "string", "examples": [ "-37.814000" ] }, "longitude": { "type": "string", "examples": [ "144.963200" ] } } }, "street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "city": { "type": "string", "examples": [ "Melbourne" ] }, "postcode": { "type": "string", "examples": [ "3000" ] }, "region": { "type": "string", "examples": [ "VIC" ] }, "country": { "type": "string", "examples": [ "AU" ] }, "latitude": { "type": "string", "examples": [ "-37.814000" ] }, "longitude": { "type": "string", "examples": [ "144.963200" ] } } } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:user:xxxxxxxxxxxxxxxxxxxxxxxx" ] }, "address": { "type": "string", "examples": [ "1 Example Street\nMelbourne\nVictoria\nAustralia\n3000" ] }, "address_oneline": { "type": "string", "examples": [ "1 Example Street, Melbourne, Victoria, Australia, 3000" ] }, "address.country": { "type": "string", "examples": [ "Australia" ] }, "address.country:raw": { "type": "string", "examples": [ "AUS" ] }, "address.city": { "type": "string", "examples": [ "Melbourne" ] }, "address.region": { "type": "string", "examples": [ "Victoria" ] }, "address.region:raw": { "type": "string", "examples": [ "VIC" ] }, "address.postcode": { "type": "string", "examples": [ "3000" ] }, "address.street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "address.street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "address.street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "address.latitude": { "type": "string", "examples": [ "-37.814000" ] }, "address.longitude": { "type": "string", "examples": [ "144.963200" ] }, "family_id": { "type": [ "string", "null" ], "examples": [ null ] }, "has_family_members": { "type": "string", "examples": [ "No" ] }, "manages_family": { "type": "boolean", "examples": [ false ] }, "family_manager": { "type": "string", "examples": [ "No" ] }, "family_member": { "type": "string", "examples": [ "No" ] }, "is_family_member": { "type": "boolean", "examples": [ false ] }, "is_engaged": { "type": "string", "examples": [ "No" ] }, "is_engaged:raw": { "type": "boolean", "examples": [ false ] }, "last_engaged_at": { "type": [ "string", "null" ], "examples": [ null ] }, "last_engaged_at:raw": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "May 29, 2026, 6:30 PM" ] }, "created_at__date": { "type": "string", "examples": [ "May 29, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "6:30 PM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Friday" ] }, "email_verified": { "type": "string", "examples": [ "No" ] }, "from_source": { "type": "string", "examples": [ "" ] }, "interests": { "type": [ "string", "null" ], "examples": [ null ] }, "interests:value": { "type": [ "string", "null" ], "examples": [ null ] }, "interests:array": { "type": [ "string", "null" ], "examples": [ null ] }, "is_subscribed_transactional": { "type": "string", "examples": [ "Yes" ] }, "is_team_leader": { "type": "string", "examples": [ "No" ] }, "middle_name": { "type": "string", "examples": [ "" ] }, "picture_status": { "type": "string", "examples": [ "N/A" ] }, "picture_status:value": { "type": "integer", "examples": [ 0 ] }, "picture_status:array": { "type": "string", "examples": [ "N/A" ] }, "shift_privacy": { "type": "string", "examples": [ "Yes" ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:35 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:35 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "first_name": { "type": "string", "examples": [ "Alex" ] }, "last_name": { "type": "string", "examples": [ "Taylor" ] }, "preferred_name": { "type": "string", "examples": [ "" ] }, "phone:qr_code_value": { "type": "string", "examples": [ "au-390000000" ] }, "phone": { "type": "string", "examples": [ "(+61) 390000000" ] }, "phone:raw": { "type": "string", "examples": [ "+61390000000" ] }, "phone:local_au": { "type": "string", "examples": [ "0390000000" ] }, "dob": { "type": "string", "examples": [ "Apr 12, 1990" ] }, "dob__dayofweek": { "type": "string", "examples": [ "Thursday" ] }, "is_subscribed": { "type": "string", "examples": [ "No" ] }, "terms": { "type": "string", "examples": [ "Yes" ] }, "name": { "type": "string", "examples": [ "Alex Taylor" ] }, "age": { "type": "integer", "examples": [ 36 ] }, "age_months": { "type": "string", "examples": [ "36 years, 4 months" ] }, "info": { "type": "string", "examples": [ "Alex Taylor (alex.taylor@example.com)" ] }, "preferred_first_name": { "type": "string", "examples": [ "Alex" ] }, "delete_requested": { "type": "boolean", "examples": [ false ] }, "updated_hours": { "type": "number", "examples": [ 1673.4862143775 ] }, "is_community_user": { "type": "boolean", "examples": [ false ] }, "timezone": { "type": "string", "examples": [ "UTC" ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } }, "attributes": { "type": "object", "properties": {} }, "id": { "type": "integer", "examples": [ 23453479 ] }, "name": { "type": "string", "examples": [ "Alex Taylor" ] } }, "examples": [ { "object": { "id": 23453479, "id_token": "xxxxxxxxxxxxxxxxxxxxxxxx", "account_id": 20101, "email": "alex.taylor@example.com", "force_reset_password": 0, "password_expires_at": null, "first_name": "Alex", "middle_name": null, "last_name": "Taylor", "preferred_name": null, "phone": "au-390000000", "dob": "1990-04-12", "picture": null, "picture_status": 0, "is_subscribed": 0, "is_subscribed_transactional": 1, "is_unreachable": 0, "is_unreachable_sms": 0, "terms": 1, "rating": "0.00", "shift_privacy": 1, "is_team_leader": 0, "email_verified": 0, "login_lockout_attempts": 0, "login_lockout_at": null, "login_lockout_email_sent_at": null, "last_login_at": null, "last_app_login_at": null, "is_archived": 0, "last_activated": null, "from_source": null, "delete_requested_at": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-05-29T18:30:58.000000Z", "updated_at": "2026-06-09T05:35:38.000000Z", "deleted_by": null, "interests": null, "address": { "iso": "AUS", "region_code": "VIC", "coordinates": { "latitude": "-37.814000", "longitude": "144.963200" }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "Melbourne", "postcode": "3000", "region": "VIC", "country": "AU", "latitude": "-37.814000", "longitude": "144.963200" } }, "nice": { "rrn": "rrn:local:20101:user:xxxxxxxxxxxxxxxxxxxxxxxx", "address": "1 Example Street\nMelbourne\nVictoria\nAustralia\n3000", "address_oneline": "1 Example Street, Melbourne, Victoria, Australia, 3000", "address.country": "Australia", "address.country:raw": "AUS", "address.city": "Melbourne", "address.region": "Victoria", "address.region:raw": "VIC", "address.postcode": "3000", "address.street_address_1": "1 Example Street", "address.street_address_2": null, "address.street_address_3": null, "address.latitude": "-37.814000", "address.longitude": "144.963200", "family_id": null, "has_family_members": "No", "manages_family": false, "family_manager": "No", "family_member": "No", "is_family_member": false, "is_engaged": "No", "is_engaged:raw": false, "last_engaged_at": null, "last_engaged_at:raw": null, "created_at": "May 29, 2026, 6:30 PM", "created_at__date": "May 29, 2026", "created_at__time": "6:30 PM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Friday", "email_verified": "No", "from_source": "", "interests": null, "interests:value": null, "interests:array": null, "is_subscribed_transactional": "Yes", "is_team_leader": "No", "middle_name": "", "picture_status": "N/A", "picture_status:value": 0, "picture_status:array": "N/A", "shift_privacy": "Yes", "updated_at": "Jun 9, 2026, 5:35 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:35 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "first_name": "Alex", "last_name": "Taylor", "preferred_name": "", "phone:qr_code_value": "au-390000000", "phone": "(+61) 390000000", "phone:raw": "+61390000000", "phone:local_au": "0390000000", "dob": "Apr 12, 1990", "dob__dayofweek": "Thursday", "is_subscribed": "No", "terms": "Yes", "name": "Alex Taylor", "age": 36, "age_months": "36 years, 4 months", "info": "Alex Taylor (alex.taylor@example.com)", "preferred_first_name": "Alex", "delete_requested": false, "updated_hours": 1673.4862143775, "is_community_user": false, "timezone": "UTC" }, "relations": [], "permissions": { "read": true, "update": true, "delete": true }, "attributes": {}, "id": 23453479, "name": "Alex Taylor" } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Sorry, we found issues with some of the submitted data - please review and try again." ] }, "errors": { "type": "object", "properties": { "email": { "type": "array", "items": { "type": "string" }, "examples": [ [ "Must be a valid email address." ] ] } } } }, "examples": [ { "message": "Sorry, we found issues with some of the submitted data - please review and try again.", "errors": { "email": [ "Must be a valid email address." ] } } ] } } } } }, "tags": [ "User Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address of the User. Must be unique.", "examples": [ "alex.taylor@example.com" ] }, "preferred_name": { "type": "string", "description": "", "examples": [ null ] }, "first_name": { "type": "string", "description": "The first name of the User", "examples": [ "Alex" ] }, "middle_name": { "type": "string", "description": "", "examples": [ null ] }, "last_name": { "type": "string", "description": "The last name of the User", "examples": [ "Taylor" ] }, "phone": { "type": "string", "description": "Phone number", "examples": [ "au-390000000" ] }, "dob": { "type": "string", "description": "Date of birth in Y-m-d format", "examples": [ "1990-04-12" ] }, "address": { "type": "object", "description": "The address of the User.", "properties": {}, "examples": [ { "iso": "AUS", "region_code": "VIC", "coordinates": { "latitude": "-37.814000", "longitude": "144.963200" }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "Melbourne", "postcode": "3000", "region": "VIC", "country": "AU", "latitude": "-37.814000", "longitude": "144.963200" } ] }, "is_subscribed": { "type": "boolean", "description": "", "examples": [ 0 ] }, "picture": { "type": "string", "description": "", "examples": [ null ] }, "account_role": { "type": "string", "description": "An ID of an account role (Admin Permission) to place User into.", "examples": [ null ] }, "user_checkpoint_id": { "type": "integer", "description": "The ID of the checkpoint the user should be placed into.", "examples": [ 1 ] }, "user_type_id": { "type": "integer", "description": "Set the User Type of the User.", "examples": [ 1 ] }, "is_archived": { "type": "boolean", "description": "Whether the User is archived.", "examples": [ 0 ] }, "general:timezone": { "type": "string", "description": "", "examples": [ null ] }, "custom_*": { "type": "string", "description": "A custom attribute, named by its code - custom_shirt_size, for example. The value follows the attribute's own type, so it may be a string, a number, a boolean or a list. See the custom attributes documentation.", "examples": [ null ] } } } } } } }, "delete": { "summary": "Delete a user", "operationId": "deleteAUser", "description": "Removes a person from the account. The record is soft-deleted rather than\nerased, so their history on shifts, training and forms is preserved and the\ndeletion can be undone in-platform.\n\nDeleting someone whose permissions other account configuration relies on -\na report or a group they created - is refused with a `405` naming what\nstands in the way. That refusal can be overridden by repeating the request\nwith the `reference` from the response in `override[]`, which accepts the\nconsequence the message describes.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "204": { "description": "No content, successful deletion", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } }, "405": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Reports and groups created by this user rely on their permissions. If you remove all their roles, these reports and groups will be updated to use your permissions" ] }, "reference": { "type": "string", "examples": [ "account.role.delete" ] } }, "examples": [ { "message": "Reports and groups created by this user rely on their permissions. If you remove all their roles, these reports and groups will be updated to use your permissions", "reference": "account.role.delete" } ] } } } } }, "tags": [ "User Module" ] }, "parameters": [ { "in": "path", "name": "id", "description": "The ID of the user.", "required": true, "schema": { "type": "integer", "examples": [ 23453479 ] } } ] }, "/api/v2/user/group/user": { "put": { "summary": "Add users to groups in bulk", "operationId": "addUsersToGroupsInBulk", "description": "Adds many people to one or more user groups and returns a token identifying\nthe queued job. The work happens in the background, so a `200` means the\nrequest was accepted, not that every membership exists yet. People already\nin a group are skipped rather than duplicated.\n\n`entity` says what the ids you send refer to, and it is the field that makes\nthis endpoint worth using: with `user` you send user ids directly, and with\nthe other values you send shift, shift-assignment, event-registration or\nrole-offer-application ids instead and the people attached to those records\nare the ones added. That is how \"add everyone rostered on this shift to a\ngroup\" is expressed.\n\n`applyTo` of `selected` takes the ids in `selected`. `applyTo` of `all` takes\nevery record of that `entity` type on the account, narrowed by `filter` if\nyou send one - so an `all` with no filter is a very wide request, and worth\nrunning against the corresponding listing first to see what it selects.\n\nThree of the `entity` types are scoped to a parent record through\n`identifiers`, and two of them insist on it: `event_user` requires\n`identifiers.event_id` and `role_offer_user` requires\n`identifiers.role_offer_id`, while `event_shift` and `event_shift_user` accept\n`identifiers.event_id` and `identifiers.shift_id` respectively to narrow the\nselection but do not require them. `entity` of `user` ignores `identifiers`\nentirely.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "queue": { "type": "string", "examples": [ "mTsVQ1NCLS3vg7WwP5kG1Vbt" ] } }, "examples": [ { "queue": "mTsVQ1NCLS3vg7WwP5kG1Vbt" } ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Sorry, we found issues with some of the submitted data - please review and try again." ] }, "errors": { "type": "object", "properties": { "group_id": { "type": "array", "items": { "type": "string" }, "examples": [ [ "Field is required." ] ] } } } }, "examples": [ { "message": "Sorry, we found issues with some of the submitted data - please review and try again.", "errors": { "group_id": [ "Field is required." ] } } ] } } } } }, "tags": [ "User Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "applyTo": { "type": "string", "description": "Which records to act on: `selected` or `all`.", "examples": [ "selected" ] }, "selected": { "type": "array", "description": "IDs of the records named by `entity`. Needed when `applyTo` is `selected`.", "items": { "type": "integer" }, "examples": [ [ 16 ] ] }, "identifiers": { "type": "object", "description": "Narrows the chosen `entity` to one parent record. See the description.", "properties": { "event_id": { "type": "integer", "description": "Required when `entity` is `event_user`; optional for `event_shift`.", "examples": [ 16 ] }, "shift_id": { "type": "integer", "description": "Optional when `entity` is `event_shift_user`.", "examples": [ 16 ] }, "role_offer_id": { "type": "integer", "description": "Required when `entity` is `role_offer_user`.", "examples": [ 16 ] } }, "examples": [ [] ] }, "filter": { "type": "array", "description": "The filter structure the matching listing accepts. Used when `applyTo` is `all`.", "items": { "type": "object" }, "examples": [ [ [] ] ] }, "group_id": { "type": "array", "description": "IDs of the groups to add the users to. Every group named here receives every user the request selects.", "items": { "type": "integer" }, "examples": [ [] ] }, "entity": { "type": "string", "description": "What the ids in `selected` refer to. `user` for user ids; the other values take the users attached to the named records instead - `event_shift` for shifts, `event_shift_user` for shift assignments, `event_user` for event registrations, `role_offer_user` for role offer applications.", "examples": [ null ] } }, "required": [ "applyTo", "group_id", "entity" ] } } } } } }, "/api/v2/account": { "get": { "summary": "List sub-accounts", "operationId": "listSubAccounts", "description": "Returns the sub-accounts sitting directly beneath the one you are signed in to.\nNeither the account you are calling as nor anything above it is included, and\naccounts in a different part of the hierarchy are never returned.\n\nEach row carries `object.parent_id` and `object.path` - a slash-separated chain of\naccount ids from the top of the tree down - so the hierarchy can be rebuilt from\nthe listing without further calls.\n\nResults are limited to the sub-accounts you are allowed to see, so two callers in\nthe same account can get different rows.", "parameters": [ { "in": "query", "name": "show_descendant", "description": "Return the whole subtree rather than only the\naccounts one level down. Available when the account allows it.", "required": false, "schema": { "type": "boolean", "description": "Return the whole subtree rather than only the\naccounts one level down. Available when the account allows it.", "examples": [ true ] } }, { "in": "query", "name": "subaccount_selection", "description": "Narrow the results to the sub-accounts\noffered in the account-switching menu. Available when the account allows it.", "required": false, "schema": { "type": "boolean", "description": "Narrow the results to the sub-accounts\noffered in the account-switching menu. Available when the account allows it.", "examples": [ true ] } }, { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "query", "name": "extras", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "required": false, "schema": { "type": "array", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "items": { "type": "string", "enum": [ "stats", "domains", "limits", "certificate" ] }, "examples": [ [ "stats" ] ] } }, { "in": "query", "name": "with", "description": "A list of relations to include in the response. May be single records or collections.\nIt is often more efficient to retrieve this way, to avoid follow-up API calls.", "required": false, "schema": { "type": "array", "description": "A list of relations to include in the response. May be single records or collections.\nIt is often more efficient to retrieve this way, to avoid follow-up API calls.", "items": { "type": "string", "enum": [ "users", "brandings", "account_terms_and_conditions_acceptance" ] }, "examples": [ [ "users" ] ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 20101 ] }, "parent_id": { "type": "integer", "examples": [ 1 ] }, "account_type_id": { "type": "integer", "examples": [ 3 ] }, "path": { "type": "string", "examples": [ "1/20101" ] }, "name": { "type": "string", "examples": [ "Example Organisation" ] }, "config": { "type": "object", "properties": { "active_settings": { "type": "array", "items": { "type": "string" }, "examples": [ [ "general:locale", "general:timezone", "general:country", "users:login", "users:register", "users:require_dob", "event:shift_status_default", "event:self_checkin", "branding:name", "branding:primary_color" ] ] } } }, "meta": { "type": "array", "examples": [ [] ] }, "visibility_rules": { "type": "array", "examples": [ [] ] }, "status": { "type": "string", "examples": [ "approved" ] }, "status_reason": { "type": [ "string", "null" ], "examples": [ null ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "start_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "end_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "notes": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_firstname": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_lastname": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_email": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_phone": { "type": [ "string", "null" ], "examples": [ null ] }, "support_manager_email": { "type": "string", "examples": [ "support.manager@example.com" ] }, "allow_deletion_request": { "type": "integer", "examples": [ 1 ] }, "organization_type": { "type": [ "string", "null" ], "examples": [ null ] }, "contract_start_date": { "type": "string", "examples": [ "2026-06-09" ] }, "contract_end_date": { "type": "string", "examples": [ "2027-06-09" ] }, "billing_contact_email": { "type": "string", "examples": [ "billing@example.com" ] }, "billing_support_email": { "type": "string", "examples": [ "billing.support@example.com" ] }, "is_enabled": { "type": "integer", "examples": [ 1 ] }, "additional_billing_support_email": { "type": "string", "examples": [ "billing.additional@example.com" ] }, "delete_requested_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "trial_ends_at": { "type": [ "string", "null" ], "examples": [ null ] }, "can_erase": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:33:32.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T07:08:01.000000Z" ] }, "domain": { "type": "array", "items": { "type": "string" }, "examples": [ [ "example.rosterfy.com" ] ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:1:account:20101" ] }, "address": { "type": "string", "examples": [ "No Address" ] }, "address_oneline": { "type": "string", "examples": [ "No Address" ] }, "account_type_id": { "type": "integer", "examples": [ 3 ] }, "account_type_id:value": { "type": "integer", "examples": [ 3 ] }, "account_type_id:array": { "type": "integer", "examples": [ 3 ] }, "allow_deletion_request": { "type": "string", "examples": [ "Yes" ] }, "contact_firstname": { "type": "string", "examples": [ "" ] }, "contact_lastname": { "type": "string", "examples": [ "" ] }, "contact_phone:qr_code_value": { "type": "string", "examples": [ "" ] }, "contact_phone": { "type": "string", "examples": [ "" ] }, "contact_phone:raw": { "type": "string", "examples": [ "" ] }, "contract_end_date": { "type": "string", "examples": [ "Jun 9, 2027" ] }, "contract_end_date__dayofweek": { "type": "string", "examples": [ "Wednesday" ] }, "contract_start_date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "contract_start_date__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "name": { "type": "string", "examples": [ "Example Organisation" ] }, "notes": { "type": "string", "examples": [ "" ] }, "organization_type": { "type": [ "string", "null" ], "examples": [ null ] }, "organization_type:value": { "type": [ "string", "null" ], "examples": [ null ] }, "organization_type:array": { "type": [ "string", "null" ], "examples": [ null ] }, "status": { "type": "string", "examples": [ "Approved" ] }, "status:value": { "type": "string", "examples": [ "approved" ] }, "status:array": { "type": "string", "examples": [ "approved" ] }, "status_reason": { "type": "string", "examples": [ "" ] }, "created_at": { "type": "string", "examples": [ "2026-06-09 05:33:32" ] }, "url": { "type": "string", "examples": [ "https://example.rosterfy.com/" ] }, "branding_name": { "type": "string", "examples": [ "Example Organisation" ] }, "branding_subtitle": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo_mono": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo_stacked": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_banner": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_favicon": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_description": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_primary_color": { "type": "string", "examples": [ "#3131c7" ] }, "branding_complimentary_color": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_secondary_color": { "type": "string", "examples": [ "#38b6ff" ] }, "register": { "type": "boolean", "examples": [ false ] }, "organisation_contact": { "type": "string", "examples": [ " " ] }, "has_subaccount_approved_email_template": { "type": "boolean", "examples": [ false ] }, "has_subaccount_rejected_email_template": { "type": "boolean", "examples": [ false ] }, "parent_account_name": { "type": "string", "examples": [ "Example Parent Organisation" ] } } }, "relations": { "type": "object", "properties": { "current_user_checkpoint": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 3 ] }, "user_checkpoint_type_id": { "type": [ "string", "null" ], "examples": [ null ] }, "name": { "type": "string", "examples": [ "Default" ] }, "label": { "type": "string", "examples": [ "default" ] }, "permissions": { "type": "object", "properties": { "all": { "type": "string", "examples": [ "1" ] } } }, "actions": { "type": "array", "examples": [ [] ] }, "is_inheritable": { "type": "integer", "examples": [ 0 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:33:39.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:34:24.000000Z" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:checkpoint:3" ] }, "content_id": { "type": "integer", "examples": [ 3 ] }, "account_name_path": { "type": "string", "examples": [ "Example Organisation" ] }, "is_foreign_account": { "type": "boolean", "examples": [ false ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ false ] } } } } }, "parent": { "type": "array", "examples": [ [] ] }, "account": { "type": "array", "examples": [ [] ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ false ] }, "delete": { "type": "boolean", "examples": [ false ] }, "apply": { "type": "boolean", "examples": [ false ] }, "apply_error": { "type": "string", "examples": [ "Subaccount does not allow User to join" ] }, "view_subaccount_selection_menu": { "type": "boolean", "examples": [ false ] } } }, "attributes": { "type": "array", "examples": [ [] ] } } }, "examples": [ [ { "object": { "id": 20101, "parent_id": 1, "account_type_id": 3, "path": "1/20101", "name": "Example Organisation", "config": { "active_settings": [ "general:locale", "general:timezone", "general:country", "users:login", "users:register", "users:require_dob", "event:shift_status_default", "event:self_checkin", "branding:name", "branding:primary_color" ] }, "meta": [], "visibility_rules": [], "status": "approved", "status_reason": null, "sort_order": 0, "start_timestamp": null, "end_timestamp": null, "notes": null, "contact_firstname": null, "contact_lastname": null, "contact_email": null, "contact_phone": null, "support_manager_email": "support.manager@example.com", "allow_deletion_request": 1, "organization_type": null, "contract_start_date": "2026-06-09", "contract_end_date": "2027-06-09", "billing_contact_email": "billing@example.com", "billing_support_email": "billing.support@example.com", "is_enabled": 1, "additional_billing_support_email": "billing.additional@example.com", "delete_requested_at": null, "is_archived": 0, "trial_ends_at": null, "can_erase": 0, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:33:32.000000Z", "updated_at": "2026-06-09T07:08:01.000000Z", "domain": [ "example.rosterfy.com" ] }, "nice": { "rrn": "rrn:local:1:account:20101", "address": "No Address", "address_oneline": "No Address", "account_type_id": 3, "account_type_id:value": 3, "account_type_id:array": 3, "allow_deletion_request": "Yes", "contact_firstname": "", "contact_lastname": "", "contact_phone:qr_code_value": "", "contact_phone": "", "contact_phone:raw": "", "contract_end_date": "Jun 9, 2027", "contract_end_date__dayofweek": "Wednesday", "contract_start_date": "Jun 9, 2026", "contract_start_date__dayofweek": "Tuesday", "name": "Example Organisation", "notes": "", "organization_type": null, "organization_type:value": null, "organization_type:array": null, "status": "Approved", "status:value": "approved", "status:array": "approved", "status_reason": "", "created_at": "2026-06-09 05:33:32", "url": "https://example.rosterfy.com/", "branding_name": "Example Organisation", "branding_subtitle": null, "branding_logo": null, "branding_logo_mono": null, "branding_logo_stacked": null, "branding_banner": null, "branding_favicon": null, "branding_description": null, "branding_primary_color": "#3131c7", "branding_complimentary_color": null, "branding_secondary_color": "#38b6ff", "register": false, "organisation_contact": " ", "has_subaccount_approved_email_template": false, "has_subaccount_rejected_email_template": false, "parent_account_name": "Example Parent Organisation" }, "relations": { "current_user_checkpoint": { "object": { "id": 3, "user_checkpoint_type_id": null, "name": "Default", "label": "default", "permissions": { "all": "1" }, "actions": [], "is_inheritable": 0, "sort_order": 0, "deleted_at": null, "created_at": "2026-06-09T05:33:39.000000Z", "updated_at": "2026-06-09T05:34:24.000000Z" }, "nice": { "rrn": "rrn:local:20101:checkpoint:3", "content_id": 3, "account_name_path": "Example Organisation", "is_foreign_account": false }, "permissions": { "read": true, "update": true, "delete": false } }, "parent": [], "account": [] }, "permissions": { "read": true, "update": false, "delete": false, "apply": false, "apply_error": "Subaccount does not allow User to join", "view_subaccount_selection_menu": false }, "attributes": [] }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/account?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/account?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/account" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 20101, "parent_id": 1, "account_type_id": 3, "path": "1/20101", "name": "Example Organisation", "config": { "active_settings": [ "general:locale", "general:timezone", "general:country", "users:login", "users:register", "users:require_dob", "event:shift_status_default", "event:self_checkin", "branding:name", "branding:primary_color" ] }, "meta": [], "visibility_rules": [], "status": "approved", "status_reason": null, "sort_order": 0, "start_timestamp": null, "end_timestamp": null, "notes": null, "contact_firstname": null, "contact_lastname": null, "contact_email": null, "contact_phone": null, "support_manager_email": "support.manager@example.com", "allow_deletion_request": 1, "organization_type": null, "contract_start_date": "2026-06-09", "contract_end_date": "2027-06-09", "billing_contact_email": "billing@example.com", "billing_support_email": "billing.support@example.com", "is_enabled": 1, "additional_billing_support_email": "billing.additional@example.com", "delete_requested_at": null, "is_archived": 0, "trial_ends_at": null, "can_erase": 0, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:33:32.000000Z", "updated_at": "2026-06-09T07:08:01.000000Z", "domain": [ "example.rosterfy.com" ] }, "nice": { "rrn": "rrn:local:1:account:20101", "address": "No Address", "address_oneline": "No Address", "account_type_id": 3, "account_type_id:value": 3, "account_type_id:array": 3, "allow_deletion_request": "Yes", "contact_firstname": "", "contact_lastname": "", "contact_phone:qr_code_value": "", "contact_phone": "", "contact_phone:raw": "", "contract_end_date": "Jun 9, 2027", "contract_end_date__dayofweek": "Wednesday", "contract_start_date": "Jun 9, 2026", "contract_start_date__dayofweek": "Tuesday", "name": "Example Organisation", "notes": "", "organization_type": null, "organization_type:value": null, "organization_type:array": null, "status": "Approved", "status:value": "approved", "status:array": "approved", "status_reason": "", "created_at": "2026-06-09 05:33:32", "url": "https://example.rosterfy.com/", "branding_name": "Example Organisation", "branding_subtitle": null, "branding_logo": null, "branding_logo_mono": null, "branding_logo_stacked": null, "branding_banner": null, "branding_favicon": null, "branding_description": null, "branding_primary_color": "#3131c7", "branding_complimentary_color": null, "branding_secondary_color": "#38b6ff", "register": false, "organisation_contact": " ", "has_subaccount_approved_email_template": false, "has_subaccount_rejected_email_template": false, "parent_account_name": "Example Parent Organisation" }, "relations": { "current_user_checkpoint": { "object": { "id": 3, "user_checkpoint_type_id": null, "name": "Default", "label": "default", "permissions": { "all": "1" }, "actions": [], "is_inheritable": 0, "sort_order": 0, "deleted_at": null, "created_at": "2026-06-09T05:33:39.000000Z", "updated_at": "2026-06-09T05:34:24.000000Z" }, "nice": { "rrn": "rrn:local:20101:checkpoint:3", "content_id": 3, "account_name_path": "Example Organisation", "is_foreign_account": false }, "permissions": { "read": true, "update": true, "delete": false } }, "parent": [], "account": [] }, "permissions": { "read": true, "update": false, "delete": false, "apply": false, "apply_error": "Subaccount does not allow User to join", "view_subaccount_selection_menu": false }, "attributes": [] }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/account?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/account?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/account", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Account Module" ] }, "post": { "summary": "Create a sub-account", "operationId": "createASubAccount", "description": "Creates a sub-account directly beneath the one you are signed in to. The parent is\nalways taken from the caller and cannot be set from the request. The response is\nthe same shape as reading the account, so a follow-up read is not needed.\n\nOnly `name` is required. Send `_options.create_admin` together with the four\n`contact_*` fields to create the account's first administrator at the same time,\nand add `_options.send_welcome` to email them an invitation - without an\nadministrator, nobody can sign in to the new account yet.\n\nLeave `create_defaults` on unless you intend to configure the account from\nscratch; a sub-account without the default statuses, forms and templates is not\nusable on its own.\n\n**`meta` is stored whole.** The object you send replaces the stored one rather\nthan merging into it, so send every key you want to keep.\n\n**Creating a sub-account is refused once the account has reached its configured\nlimit on sub-accounts**, and the limit of any account above it applies too, so a\nparent at its own limit blocks the whole branch.\n\nFields beyond the ones below are accepted from callers with elevated access.\nThe account's own configured attributes are accepted as `custom_*` fields.\n\nThe endpoint also accepts a `recipe` file - a blueprint to build the new account\nfrom, sent as `multipart/form-data` instead of JSON. It is left out of the\nparameters below because a blueprint comes from exporting an existing account,\nwhich is not part of the published API.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 20101 ] }, "parent_id": { "type": "integer", "examples": [ 1 ] }, "account_type_id": { "type": "integer", "examples": [ 3 ] }, "path": { "type": "string", "examples": [ "1/20101" ] }, "name": { "type": "string", "examples": [ "Example Organisation" ] }, "config": { "type": "object", "properties": { "active_settings": { "type": "array", "items": { "type": "string" }, "examples": [ [ "general:locale", "general:timezone", "general:country", "users:login", "users:register", "users:require_dob", "event:shift_status_default", "event:self_checkin", "branding:name", "branding:primary_color" ] ] } } }, "meta": { "type": "array", "examples": [ [] ] }, "visibility_rules": { "type": "array", "examples": [ [] ] }, "status": { "type": "string", "examples": [ "approved" ] }, "status_reason": { "type": [ "string", "null" ], "examples": [ null ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "start_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "end_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "notes": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_firstname": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_lastname": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_email": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_phone": { "type": [ "string", "null" ], "examples": [ null ] }, "support_manager_email": { "type": "string", "examples": [ "support.manager@example.com" ] }, "allow_deletion_request": { "type": "integer", "examples": [ 1 ] }, "organization_type": { "type": [ "string", "null" ], "examples": [ null ] }, "contract_start_date": { "type": "string", "examples": [ "2026-06-09" ] }, "contract_end_date": { "type": "string", "examples": [ "2027-06-09" ] }, "billing_contact_email": { "type": "string", "examples": [ "billing@example.com" ] }, "billing_support_email": { "type": "string", "examples": [ "billing.support@example.com" ] }, "is_enabled": { "type": "integer", "examples": [ 1 ] }, "additional_billing_support_email": { "type": "string", "examples": [ "billing.additional@example.com" ] }, "delete_requested_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "trial_ends_at": { "type": [ "string", "null" ], "examples": [ null ] }, "can_erase": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:33:32.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T07:08:01.000000Z" ] }, "domain": { "type": "array", "items": { "type": "string" }, "examples": [ [ "example.rosterfy.com" ] ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:1:account:20101" ] }, "address": { "type": "string", "examples": [ "No Address" ] }, "address_oneline": { "type": "string", "examples": [ "No Address" ] }, "account_type_id": { "type": "integer", "examples": [ 3 ] }, "account_type_id:value": { "type": "integer", "examples": [ 3 ] }, "account_type_id:array": { "type": "integer", "examples": [ 3 ] }, "allow_deletion_request": { "type": "string", "examples": [ "Yes" ] }, "contact_firstname": { "type": "string", "examples": [ "" ] }, "contact_lastname": { "type": "string", "examples": [ "" ] }, "contact_phone:qr_code_value": { "type": "string", "examples": [ "" ] }, "contact_phone": { "type": "string", "examples": [ "" ] }, "contact_phone:raw": { "type": "string", "examples": [ "" ] }, "contract_end_date": { "type": "string", "examples": [ "Jun 9, 2027" ] }, "contract_end_date__dayofweek": { "type": "string", "examples": [ "Wednesday" ] }, "contract_start_date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "contract_start_date__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "name": { "type": "string", "examples": [ "Example Organisation" ] }, "notes": { "type": "string", "examples": [ "" ] }, "organization_type": { "type": [ "string", "null" ], "examples": [ null ] }, "organization_type:value": { "type": [ "string", "null" ], "examples": [ null ] }, "organization_type:array": { "type": [ "string", "null" ], "examples": [ null ] }, "status": { "type": "string", "examples": [ "Approved" ] }, "status:value": { "type": "string", "examples": [ "approved" ] }, "status:array": { "type": "string", "examples": [ "approved" ] }, "status_reason": { "type": "string", "examples": [ "" ] }, "created_at": { "type": "string", "examples": [ "2026-06-09 05:33:32" ] }, "url": { "type": "string", "examples": [ "https://example.rosterfy.com/" ] }, "branding_name": { "type": "string", "examples": [ "Example Organisation" ] }, "branding_subtitle": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo_mono": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo_stacked": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_banner": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_favicon": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_description": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_primary_color": { "type": "string", "examples": [ "#3131c7" ] }, "branding_complimentary_color": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_secondary_color": { "type": "string", "examples": [ "#38b6ff" ] }, "register": { "type": "boolean", "examples": [ false ] }, "organisation_contact": { "type": "string", "examples": [ " " ] }, "has_subaccount_approved_email_template": { "type": "boolean", "examples": [ false ] }, "has_subaccount_rejected_email_template": { "type": "boolean", "examples": [ false ] }, "parent_account_name": { "type": "string", "examples": [ "Example Parent Organisation" ] } } }, "relations": { "type": "object", "properties": { "current_user_checkpoint": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 3 ] }, "user_checkpoint_type_id": { "type": [ "string", "null" ], "examples": [ null ] }, "name": { "type": "string", "examples": [ "Default" ] }, "label": { "type": "string", "examples": [ "default" ] }, "permissions": { "type": "object", "properties": { "all": { "type": "string", "examples": [ "1" ] } } }, "actions": { "type": "array", "examples": [ [] ] }, "is_inheritable": { "type": "integer", "examples": [ 0 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:33:39.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:34:24.000000Z" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:checkpoint:3" ] }, "content_id": { "type": "integer", "examples": [ 3 ] }, "account_name_path": { "type": "string", "examples": [ "Example Organisation" ] }, "is_foreign_account": { "type": "boolean", "examples": [ false ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ false ] } } } } }, "parent": { "type": "array", "examples": [ [] ] }, "account": { "type": "array", "examples": [ [] ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ false ] }, "delete": { "type": "boolean", "examples": [ false ] }, "apply": { "type": "boolean", "examples": [ false ] }, "apply_error": { "type": "string", "examples": [ "Subaccount does not allow User to join" ] }, "view_subaccount_selection_menu": { "type": "boolean", "examples": [ false ] } } }, "attributes": { "type": "object", "properties": {} } }, "examples": [ { "object": { "id": 20101, "parent_id": 1, "account_type_id": 3, "path": "1/20101", "name": "Example Organisation", "config": { "active_settings": [ "general:locale", "general:timezone", "general:country", "users:login", "users:register", "users:require_dob", "event:shift_status_default", "event:self_checkin", "branding:name", "branding:primary_color" ] }, "meta": [], "visibility_rules": [], "status": "approved", "status_reason": null, "sort_order": 0, "start_timestamp": null, "end_timestamp": null, "notes": null, "contact_firstname": null, "contact_lastname": null, "contact_email": null, "contact_phone": null, "support_manager_email": "support.manager@example.com", "allow_deletion_request": 1, "organization_type": null, "contract_start_date": "2026-06-09", "contract_end_date": "2027-06-09", "billing_contact_email": "billing@example.com", "billing_support_email": "billing.support@example.com", "is_enabled": 1, "additional_billing_support_email": "billing.additional@example.com", "delete_requested_at": null, "is_archived": 0, "trial_ends_at": null, "can_erase": 0, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:33:32.000000Z", "updated_at": "2026-06-09T07:08:01.000000Z", "domain": [ "example.rosterfy.com" ] }, "nice": { "rrn": "rrn:local:1:account:20101", "address": "No Address", "address_oneline": "No Address", "account_type_id": 3, "account_type_id:value": 3, "account_type_id:array": 3, "allow_deletion_request": "Yes", "contact_firstname": "", "contact_lastname": "", "contact_phone:qr_code_value": "", "contact_phone": "", "contact_phone:raw": "", "contract_end_date": "Jun 9, 2027", "contract_end_date__dayofweek": "Wednesday", "contract_start_date": "Jun 9, 2026", "contract_start_date__dayofweek": "Tuesday", "name": "Example Organisation", "notes": "", "organization_type": null, "organization_type:value": null, "organization_type:array": null, "status": "Approved", "status:value": "approved", "status:array": "approved", "status_reason": "", "created_at": "2026-06-09 05:33:32", "url": "https://example.rosterfy.com/", "branding_name": "Example Organisation", "branding_subtitle": null, "branding_logo": null, "branding_logo_mono": null, "branding_logo_stacked": null, "branding_banner": null, "branding_favicon": null, "branding_description": null, "branding_primary_color": "#3131c7", "branding_complimentary_color": null, "branding_secondary_color": "#38b6ff", "register": false, "organisation_contact": " ", "has_subaccount_approved_email_template": false, "has_subaccount_rejected_email_template": false, "parent_account_name": "Example Parent Organisation" }, "relations": { "current_user_checkpoint": { "object": { "id": 3, "user_checkpoint_type_id": null, "name": "Default", "label": "default", "permissions": { "all": "1" }, "actions": [], "is_inheritable": 0, "sort_order": 0, "deleted_at": null, "created_at": "2026-06-09T05:33:39.000000Z", "updated_at": "2026-06-09T05:34:24.000000Z" }, "nice": { "rrn": "rrn:local:20101:checkpoint:3", "content_id": 3, "account_name_path": "Example Organisation", "is_foreign_account": false }, "permissions": { "read": true, "update": true, "delete": false } }, "parent": [], "account": [] }, "permissions": { "read": true, "update": false, "delete": false, "apply": false, "apply_error": "Subaccount does not allow User to join", "view_subaccount_selection_menu": false }, "attributes": {} } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Account Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the sub-account, up to 255 characters. This is what people see in the account switcher and in anything branded with the account name.", "examples": [ "Example Organisation" ] }, "contact_firstname": { "type": "string", "description": "First name of the person to set up as the sub-account's first administrator. Required when _options.create_admin is set, and otherwise recorded as the account contact.", "examples": [ null ] }, "contact_lastname": { "type": "string", "description": "Last name of that person. Required when _options.create_admin is set.", "examples": [ null ] }, "contact_email": { "type": "string", "description": "Email address of that person, which becomes the administrator's sign-in address. Required when _options.create_admin is set.", "examples": [ null ] }, "contact_phone": { "type": "string", "description": "Phone number of that person, in international format such as au-297809703. Required when _options.create_admin is set.", "examples": [ null ] }, "_options": { "type": "object", "description": "", "properties": { "create_admin": { "type": "boolean", "description": "Whether to create an administrator in the new sub-account from the contact_* fields. Without it the contact details are stored but no one can sign in to the account yet. Create only.", "examples": [ true ] }, "send_welcome": { "type": "boolean", "description": "Whether to email that new administrator an invitation with a link to set their password. Only has an effect alongside _options.create_admin, and only when the account has a welcome email template configured. Create only.", "examples": [ true ] } }, "examples": [ { "create_admin": true } ] }, "meta": { "type": "object", "description": "", "properties": { "publish": { "type": "boolean", "description": "Whether the sub-account is listed to people browsing the sub-accounts they could join. Unpublished accounts stay reachable by direct link.", "examples": [ true ] }, "hide_from_new_applicants": { "type": "boolean", "description": "Whether to keep the sub-account out of the list someone sees while registering. It stays visible to people who already have an account.", "examples": [ true ] }, "promote": { "type": "boolean", "description": "Whether to feature the sub-account ahead of the others. The number of promoted accounts an account may have at once is capped, and exceeding it is rejected.", "examples": [ true ] }, "join": { "type": "boolean", "description": "Whether people may join this sub-account themselves rather than being added to it.", "examples": [ true ] } }, "examples": [ { "publish": true } ] }, "visibility_rules": { "type": "array", "description": "Optional conditions narrowing which people may see or join this sub-account. Structure is not part of the contract and is not validated - build the rules in the admin console and send back what a read returns. Send an empty array to clear them.", "items": { "type": "object" }, "examples": [ [] ] }, "sort_order": { "type": "integer", "description": "Position of the sub-account in lists that show a group of them together. Lower sorts first; accounts sharing a value fall back to name order.", "examples": [ 0 ] }, "start_timestamp": { "type": "string", "description": "When the sub-account becomes active, as YYYY-MM-DD HH:MM:SS. Must be within 25 years either side of now. Leave null for an account that is active immediately.", "examples": [ null ] }, "end_timestamp": { "type": "string", "description": "When the sub-account stops being active, as YYYY-MM-DD HH:MM:SS. Must be later than start_timestamp and within 25 years of now. Leave null for no end.", "examples": [ null ] }, "create_defaults": { "type": "boolean", "description": "Whether to populate the new sub-account with the default statuses, forms and templates a usable account needs. Leave it off only when the account is going to be filled from elsewhere. Create only.", "examples": [ true ] }, "locale": { "type": "string", "description": "Language the new sub-account starts in, as a locale code such as en or fr. Also becomes the only language available in it until more are added. Create only.", "examples": [ null ] }, "custom_*": { "type": "string", "description": "A custom attribute, named by its code - custom_shirt_size, for example. The value follows the attribute's own type, so it may be a string, a number, a boolean or a list. See the custom attributes documentation.", "examples": [ null ] } }, "required": [ "name" ] } } } } } }, "/api/v2/account/{id}": { "get": { "summary": "Read a sub-account", "operationId": "readASubAccount", "description": "Returns one account from your own part of the hierarchy: its name, where it sits,\nits contact and billing details, the domains it answers on, and the feature\nsettings it has turned on.\n\n`object.config.active_settings` names the settings configured on the account; the\nexample below shows a representative handful rather than the whole list. The\nvalues themselves are read through the account settings endpoints.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 20101 ] }, "parent_id": { "type": "integer", "examples": [ 1 ] }, "account_type_id": { "type": "integer", "examples": [ 3 ] }, "path": { "type": "string", "examples": [ "1/20101" ] }, "name": { "type": "string", "examples": [ "Example Organisation" ] }, "config": { "type": "object", "properties": { "active_settings": { "type": "array", "items": { "type": "string" }, "examples": [ [ "general:locale", "general:timezone", "general:country", "users:login", "users:register", "users:require_dob", "event:shift_status_default", "event:self_checkin", "branding:name", "branding:primary_color" ] ] } } }, "meta": { "type": "array", "examples": [ [] ] }, "visibility_rules": { "type": "array", "examples": [ [] ] }, "status": { "type": "string", "examples": [ "approved" ] }, "status_reason": { "type": [ "string", "null" ], "examples": [ null ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "start_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "end_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "notes": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_firstname": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_lastname": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_email": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_phone": { "type": [ "string", "null" ], "examples": [ null ] }, "support_manager_email": { "type": "string", "examples": [ "support.manager@example.com" ] }, "allow_deletion_request": { "type": "integer", "examples": [ 1 ] }, "organization_type": { "type": [ "string", "null" ], "examples": [ null ] }, "contract_start_date": { "type": "string", "examples": [ "2026-06-09" ] }, "contract_end_date": { "type": "string", "examples": [ "2027-06-09" ] }, "billing_contact_email": { "type": "string", "examples": [ "billing@example.com" ] }, "billing_support_email": { "type": "string", "examples": [ "billing.support@example.com" ] }, "is_enabled": { "type": "integer", "examples": [ 1 ] }, "additional_billing_support_email": { "type": "string", "examples": [ "billing.additional@example.com" ] }, "delete_requested_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "trial_ends_at": { "type": [ "string", "null" ], "examples": [ null ] }, "can_erase": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:33:32.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T07:08:01.000000Z" ] }, "domain": { "type": "array", "items": { "type": "string" }, "examples": [ [ "example.rosterfy.com" ] ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:1:account:20101" ] }, "address": { "type": "string", "examples": [ "No Address" ] }, "address_oneline": { "type": "string", "examples": [ "No Address" ] }, "account_type_id": { "type": "integer", "examples": [ 3 ] }, "account_type_id:value": { "type": "integer", "examples": [ 3 ] }, "account_type_id:array": { "type": "integer", "examples": [ 3 ] }, "allow_deletion_request": { "type": "string", "examples": [ "Yes" ] }, "contact_firstname": { "type": "string", "examples": [ "" ] }, "contact_lastname": { "type": "string", "examples": [ "" ] }, "contact_phone:qr_code_value": { "type": "string", "examples": [ "" ] }, "contact_phone": { "type": "string", "examples": [ "" ] }, "contact_phone:raw": { "type": "string", "examples": [ "" ] }, "contract_end_date": { "type": "string", "examples": [ "Jun 9, 2027" ] }, "contract_end_date__dayofweek": { "type": "string", "examples": [ "Wednesday" ] }, "contract_start_date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "contract_start_date__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "name": { "type": "string", "examples": [ "Example Organisation" ] }, "notes": { "type": "string", "examples": [ "" ] }, "organization_type": { "type": [ "string", "null" ], "examples": [ null ] }, "organization_type:value": { "type": [ "string", "null" ], "examples": [ null ] }, "organization_type:array": { "type": [ "string", "null" ], "examples": [ null ] }, "status": { "type": "string", "examples": [ "Approved" ] }, "status:value": { "type": "string", "examples": [ "approved" ] }, "status:array": { "type": "string", "examples": [ "approved" ] }, "status_reason": { "type": "string", "examples": [ "" ] }, "created_at": { "type": "string", "examples": [ "2026-06-09 05:33:32" ] }, "url": { "type": "string", "examples": [ "https://example.rosterfy.com/" ] }, "branding_name": { "type": "string", "examples": [ "Example Organisation" ] }, "branding_subtitle": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo_mono": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo_stacked": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_banner": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_favicon": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_description": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_primary_color": { "type": "string", "examples": [ "#3131c7" ] }, "branding_complimentary_color": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_secondary_color": { "type": "string", "examples": [ "#38b6ff" ] }, "register": { "type": "boolean", "examples": [ false ] }, "organisation_contact": { "type": "string", "examples": [ " " ] }, "has_subaccount_approved_email_template": { "type": "boolean", "examples": [ false ] }, "has_subaccount_rejected_email_template": { "type": "boolean", "examples": [ false ] }, "parent_account_name": { "type": "string", "examples": [ "Example Parent Organisation" ] } } }, "relations": { "type": "object", "properties": { "current_user_checkpoint": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 3 ] }, "user_checkpoint_type_id": { "type": [ "string", "null" ], "examples": [ null ] }, "name": { "type": "string", "examples": [ "Default" ] }, "label": { "type": "string", "examples": [ "default" ] }, "permissions": { "type": "object", "properties": { "all": { "type": "string", "examples": [ "1" ] } } }, "actions": { "type": "array", "examples": [ [] ] }, "is_inheritable": { "type": "integer", "examples": [ 0 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:33:39.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:34:24.000000Z" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:checkpoint:3" ] }, "content_id": { "type": "integer", "examples": [ 3 ] }, "account_name_path": { "type": "string", "examples": [ "Example Organisation" ] }, "is_foreign_account": { "type": "boolean", "examples": [ false ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ false ] } } } } }, "parent": { "type": "array", "examples": [ [] ] }, "account": { "type": "array", "examples": [ [] ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ false ] }, "delete": { "type": "boolean", "examples": [ false ] }, "apply": { "type": "boolean", "examples": [ false ] }, "apply_error": { "type": "string", "examples": [ "Subaccount does not allow User to join" ] }, "view_subaccount_selection_menu": { "type": "boolean", "examples": [ false ] } } }, "attributes": { "type": "object", "properties": {} } }, "examples": [ { "object": { "id": 20101, "parent_id": 1, "account_type_id": 3, "path": "1/20101", "name": "Example Organisation", "config": { "active_settings": [ "general:locale", "general:timezone", "general:country", "users:login", "users:register", "users:require_dob", "event:shift_status_default", "event:self_checkin", "branding:name", "branding:primary_color" ] }, "meta": [], "visibility_rules": [], "status": "approved", "status_reason": null, "sort_order": 0, "start_timestamp": null, "end_timestamp": null, "notes": null, "contact_firstname": null, "contact_lastname": null, "contact_email": null, "contact_phone": null, "support_manager_email": "support.manager@example.com", "allow_deletion_request": 1, "organization_type": null, "contract_start_date": "2026-06-09", "contract_end_date": "2027-06-09", "billing_contact_email": "billing@example.com", "billing_support_email": "billing.support@example.com", "is_enabled": 1, "additional_billing_support_email": "billing.additional@example.com", "delete_requested_at": null, "is_archived": 0, "trial_ends_at": null, "can_erase": 0, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:33:32.000000Z", "updated_at": "2026-06-09T07:08:01.000000Z", "domain": [ "example.rosterfy.com" ] }, "nice": { "rrn": "rrn:local:1:account:20101", "address": "No Address", "address_oneline": "No Address", "account_type_id": 3, "account_type_id:value": 3, "account_type_id:array": 3, "allow_deletion_request": "Yes", "contact_firstname": "", "contact_lastname": "", "contact_phone:qr_code_value": "", "contact_phone": "", "contact_phone:raw": "", "contract_end_date": "Jun 9, 2027", "contract_end_date__dayofweek": "Wednesday", "contract_start_date": "Jun 9, 2026", "contract_start_date__dayofweek": "Tuesday", "name": "Example Organisation", "notes": "", "organization_type": null, "organization_type:value": null, "organization_type:array": null, "status": "Approved", "status:value": "approved", "status:array": "approved", "status_reason": "", "created_at": "2026-06-09 05:33:32", "url": "https://example.rosterfy.com/", "branding_name": "Example Organisation", "branding_subtitle": null, "branding_logo": null, "branding_logo_mono": null, "branding_logo_stacked": null, "branding_banner": null, "branding_favicon": null, "branding_description": null, "branding_primary_color": "#3131c7", "branding_complimentary_color": null, "branding_secondary_color": "#38b6ff", "register": false, "organisation_contact": " ", "has_subaccount_approved_email_template": false, "has_subaccount_rejected_email_template": false, "parent_account_name": "Example Parent Organisation" }, "relations": { "current_user_checkpoint": { "object": { "id": 3, "user_checkpoint_type_id": null, "name": "Default", "label": "default", "permissions": { "all": "1" }, "actions": [], "is_inheritable": 0, "sort_order": 0, "deleted_at": null, "created_at": "2026-06-09T05:33:39.000000Z", "updated_at": "2026-06-09T05:34:24.000000Z" }, "nice": { "rrn": "rrn:local:20101:checkpoint:3", "content_id": 3, "account_name_path": "Example Organisation", "is_foreign_account": false }, "permissions": { "read": true, "update": true, "delete": false } }, "parent": [], "account": [] }, "permissions": { "read": true, "update": false, "delete": false, "apply": false, "apply_error": "Subaccount does not allow User to join", "view_subaccount_selection_menu": false }, "attributes": {} } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Account Module" ] }, "put": { "summary": "Update a sub-account", "operationId": "updateASubAccount", "description": "Updates an account in your own part of the hierarchy. Every field is optional; a\nrequest with an empty body succeeds and changes nothing.\n\n**`meta` is stored whole.** The object you send replaces the stored one rather\nthan merging into it, so an update carrying only `meta.publish` clears\n`meta.join`, `meta.promote` and `meta.hide_from_new_applicants`. Send every key\nyou want to keep.\n\n**This endpoint answers in one of two shapes, both with a `200`.** Normally it\nreturns the updated account, the same shape as reading it. But a request that\ncarries a `permissions` object differing from the one already stored is handed to a\nbackground job instead, and the response is `{\"queue\": \"\"}` - nothing has\nbeen saved by the time it returns, the rest of the fields in that request are\napplied in the background too, and the token is not something you can poll. Read\nthe account back to confirm the outcome. `permissions` describes what features the\naccount itself may use and is not something an ordinary caller can change; sending\nit still switches the response shape, and it is then ignored.\n\nFields beyond the ones below are accepted from callers with elevated access.\nThe account's own configured attributes are accepted as `custom_*` fields.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "oneOf": [ { "description": "the update was queued", "type": "object", "properties": { "queue": { "type": "string", "examples": [ "mTsVQ1NCLS3vg7WwP5kG1Vbt" ] } }, "examples": [ { "queue": "mTsVQ1NCLS3vg7WwP5kG1Vbt" } ] }, { "description": "", "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 20101 ] }, "parent_id": { "type": "integer", "examples": [ 1 ] }, "account_type_id": { "type": "integer", "examples": [ 3 ] }, "path": { "type": "string", "examples": [ "1/20101" ] }, "name": { "type": "string", "examples": [ "Example Organisation" ] }, "config": { "type": "object", "properties": { "active_settings": { "type": "array", "items": { "type": "string" }, "examples": [ [ "general:locale", "general:timezone", "general:country", "users:login", "users:register", "users:require_dob", "event:shift_status_default", "event:self_checkin", "branding:name", "branding:primary_color" ] ] } } }, "meta": { "type": "array", "examples": [ [] ] }, "visibility_rules": { "type": "array", "examples": [ [] ] }, "status": { "type": "string", "examples": [ "approved" ] }, "status_reason": { "type": [ "string", "null" ], "examples": [ null ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "start_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "end_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "notes": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_firstname": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_lastname": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_email": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_phone": { "type": [ "string", "null" ], "examples": [ null ] }, "support_manager_email": { "type": "string", "examples": [ "support.manager@example.com" ] }, "allow_deletion_request": { "type": "integer", "examples": [ 1 ] }, "organization_type": { "type": [ "string", "null" ], "examples": [ null ] }, "contract_start_date": { "type": "string", "examples": [ "2026-06-09" ] }, "contract_end_date": { "type": "string", "examples": [ "2027-06-09" ] }, "billing_contact_email": { "type": "string", "examples": [ "billing@example.com" ] }, "billing_support_email": { "type": "string", "examples": [ "billing.support@example.com" ] }, "is_enabled": { "type": "integer", "examples": [ 1 ] }, "additional_billing_support_email": { "type": "string", "examples": [ "billing.additional@example.com" ] }, "delete_requested_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "trial_ends_at": { "type": [ "string", "null" ], "examples": [ null ] }, "can_erase": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:33:32.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T07:08:01.000000Z" ] }, "domain": { "type": "array", "items": { "type": "string" }, "examples": [ [ "example.rosterfy.com" ] ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:1:account:20101" ] }, "address": { "type": "string", "examples": [ "No Address" ] }, "address_oneline": { "type": "string", "examples": [ "No Address" ] }, "account_type_id": { "type": "integer", "examples": [ 3 ] }, "account_type_id:value": { "type": "integer", "examples": [ 3 ] }, "account_type_id:array": { "type": "integer", "examples": [ 3 ] }, "allow_deletion_request": { "type": "string", "examples": [ "Yes" ] }, "contact_firstname": { "type": "string", "examples": [ "" ] }, "contact_lastname": { "type": "string", "examples": [ "" ] }, "contact_phone:qr_code_value": { "type": "string", "examples": [ "" ] }, "contact_phone": { "type": "string", "examples": [ "" ] }, "contact_phone:raw": { "type": "string", "examples": [ "" ] }, "contract_end_date": { "type": "string", "examples": [ "Jun 9, 2027" ] }, "contract_end_date__dayofweek": { "type": "string", "examples": [ "Wednesday" ] }, "contract_start_date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "contract_start_date__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "name": { "type": "string", "examples": [ "Example Organisation" ] }, "notes": { "type": "string", "examples": [ "" ] }, "organization_type": { "type": [ "string", "null" ], "examples": [ null ] }, "organization_type:value": { "type": [ "string", "null" ], "examples": [ null ] }, "organization_type:array": { "type": [ "string", "null" ], "examples": [ null ] }, "status": { "type": "string", "examples": [ "Approved" ] }, "status:value": { "type": "string", "examples": [ "approved" ] }, "status:array": { "type": "string", "examples": [ "approved" ] }, "status_reason": { "type": "string", "examples": [ "" ] }, "created_at": { "type": "string", "examples": [ "2026-06-09 05:33:32" ] }, "url": { "type": "string", "examples": [ "https://example.rosterfy.com/" ] }, "branding_name": { "type": "string", "examples": [ "Example Organisation" ] }, "branding_subtitle": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo_mono": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo_stacked": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_banner": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_favicon": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_description": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_primary_color": { "type": "string", "examples": [ "#3131c7" ] }, "branding_complimentary_color": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_secondary_color": { "type": "string", "examples": [ "#38b6ff" ] }, "register": { "type": "boolean", "examples": [ false ] }, "organisation_contact": { "type": "string", "examples": [ " " ] }, "has_subaccount_approved_email_template": { "type": "boolean", "examples": [ false ] }, "has_subaccount_rejected_email_template": { "type": "boolean", "examples": [ false ] }, "parent_account_name": { "type": "string", "examples": [ "Example Parent Organisation" ] } } }, "relations": { "type": "object", "properties": { "current_user_checkpoint": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 3 ] }, "user_checkpoint_type_id": { "type": [ "string", "null" ], "examples": [ null ] }, "name": { "type": "string", "examples": [ "Default" ] }, "label": { "type": "string", "examples": [ "default" ] }, "permissions": { "type": "object", "properties": { "all": { "type": "string", "examples": [ "1" ] } } }, "actions": { "type": "array", "examples": [ [] ] }, "is_inheritable": { "type": "integer", "examples": [ 0 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:33:39.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:34:24.000000Z" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:checkpoint:3" ] }, "content_id": { "type": "integer", "examples": [ 3 ] }, "account_name_path": { "type": "string", "examples": [ "Example Organisation" ] }, "is_foreign_account": { "type": "boolean", "examples": [ false ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ false ] } } } } }, "parent": { "type": "array", "examples": [ [] ] }, "account": { "type": "array", "examples": [ [] ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ false ] }, "delete": { "type": "boolean", "examples": [ false ] }, "apply": { "type": "boolean", "examples": [ false ] }, "apply_error": { "type": "string", "examples": [ "Subaccount does not allow User to join" ] }, "view_subaccount_selection_menu": { "type": "boolean", "examples": [ false ] } } }, "attributes": { "type": "object", "properties": {} } }, "examples": [ { "object": { "id": 20101, "parent_id": 1, "account_type_id": 3, "path": "1/20101", "name": "Example Organisation", "config": { "active_settings": [ "general:locale", "general:timezone", "general:country", "users:login", "users:register", "users:require_dob", "event:shift_status_default", "event:self_checkin", "branding:name", "branding:primary_color" ] }, "meta": [], "visibility_rules": [], "status": "approved", "status_reason": null, "sort_order": 0, "start_timestamp": null, "end_timestamp": null, "notes": null, "contact_firstname": null, "contact_lastname": null, "contact_email": null, "contact_phone": null, "support_manager_email": "support.manager@example.com", "allow_deletion_request": 1, "organization_type": null, "contract_start_date": "2026-06-09", "contract_end_date": "2027-06-09", "billing_contact_email": "billing@example.com", "billing_support_email": "billing.support@example.com", "is_enabled": 1, "additional_billing_support_email": "billing.additional@example.com", "delete_requested_at": null, "is_archived": 0, "trial_ends_at": null, "can_erase": 0, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:33:32.000000Z", "updated_at": "2026-06-09T07:08:01.000000Z", "domain": [ "example.rosterfy.com" ] }, "nice": { "rrn": "rrn:local:1:account:20101", "address": "No Address", "address_oneline": "No Address", "account_type_id": 3, "account_type_id:value": 3, "account_type_id:array": 3, "allow_deletion_request": "Yes", "contact_firstname": "", "contact_lastname": "", "contact_phone:qr_code_value": "", "contact_phone": "", "contact_phone:raw": "", "contract_end_date": "Jun 9, 2027", "contract_end_date__dayofweek": "Wednesday", "contract_start_date": "Jun 9, 2026", "contract_start_date__dayofweek": "Tuesday", "name": "Example Organisation", "notes": "", "organization_type": null, "organization_type:value": null, "organization_type:array": null, "status": "Approved", "status:value": "approved", "status:array": "approved", "status_reason": "", "created_at": "2026-06-09 05:33:32", "url": "https://example.rosterfy.com/", "branding_name": "Example Organisation", "branding_subtitle": null, "branding_logo": null, "branding_logo_mono": null, "branding_logo_stacked": null, "branding_banner": null, "branding_favicon": null, "branding_description": null, "branding_primary_color": "#3131c7", "branding_complimentary_color": null, "branding_secondary_color": "#38b6ff", "register": false, "organisation_contact": " ", "has_subaccount_approved_email_template": false, "has_subaccount_rejected_email_template": false, "parent_account_name": "Example Parent Organisation" }, "relations": { "current_user_checkpoint": { "object": { "id": 3, "user_checkpoint_type_id": null, "name": "Default", "label": "default", "permissions": { "all": "1" }, "actions": [], "is_inheritable": 0, "sort_order": 0, "deleted_at": null, "created_at": "2026-06-09T05:33:39.000000Z", "updated_at": "2026-06-09T05:34:24.000000Z" }, "nice": { "rrn": "rrn:local:20101:checkpoint:3", "content_id": 3, "account_name_path": "Example Organisation", "is_foreign_account": false }, "permissions": { "read": true, "update": true, "delete": false } }, "parent": [], "account": [] }, "permissions": { "read": true, "update": false, "delete": false, "apply": false, "apply_error": "Subaccount does not allow User to join", "view_subaccount_selection_menu": false }, "attributes": {} } ] } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Account Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the sub-account, up to 255 characters. This is what people see in the account switcher and in anything branded with the account name.", "examples": [ "Example Organisation" ] }, "meta": { "type": "object", "description": "", "properties": { "publish": { "type": "boolean", "description": "Whether the sub-account is listed to people browsing the sub-accounts they could join. Unpublished accounts stay reachable by direct link.", "examples": [ true ] }, "hide_from_new_applicants": { "type": "boolean", "description": "Whether to keep the sub-account out of the list someone sees while registering. It stays visible to people who already have an account.", "examples": [ true ] }, "promote": { "type": "boolean", "description": "Whether to feature the sub-account ahead of the others. The number of promoted accounts an account may have at once is capped, and exceeding it is rejected.", "examples": [ true ] }, "join": { "type": "boolean", "description": "Whether people may join this sub-account themselves rather than being added to it.", "examples": [ true ] } }, "examples": [ { "publish": true } ] }, "visibility_rules": { "type": "array", "description": "Optional conditions narrowing which people may see or join this sub-account. Structure is not part of the contract and is not validated - build the rules in the admin console and send back what a read returns. Send an empty array to clear them.", "items": { "type": "object" }, "examples": [ [] ] }, "sort_order": { "type": "integer", "description": "Position of the sub-account in lists that show a group of them together. Lower sorts first; accounts sharing a value fall back to name order.", "examples": [ 0 ] }, "start_timestamp": { "type": "string", "description": "When the sub-account becomes active, as YYYY-MM-DD HH:MM:SS. Must be within 25 years either side of now. Leave null for an account that is active immediately.", "examples": [ null ] }, "end_timestamp": { "type": "string", "description": "When the sub-account stops being active, as YYYY-MM-DD HH:MM:SS. Must be later than start_timestamp and within 25 years of now. Leave null for no end.", "examples": [ null ] }, "is_archived": { "type": "boolean", "description": "Whether the account is archived. An archived account keeps its data but is hidden from the places an active one appears. Update only.", "examples": [ 0 ] }, "custom_*": { "type": "string", "description": "A custom attribute, named by its code - custom_shirt_size, for example. The value follows the attribute's own type, so it may be a string, a number, a boolean or a list. See the custom attributes documentation.", "examples": [ null ] } } } } } } }, "delete": { "summary": "Delete a sub-account", "operationId": "deleteASubAccount", "description": "Removes a sub-account. The account and its records are retained rather than erased,\nbut no endpoint restores them, so treat this as final.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "204": { "description": "No content, successful deletion", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Account Module" ] }, "parameters": [ { "in": "path", "name": "id", "description": "The ID of the account.", "required": true, "schema": { "type": "integer", "examples": [ 20101 ] } } ] }, "/api/v2/account/role": { "get": { "summary": "List roles", "operationId": "listRoles", "description": "Returns the roles belonging to the account you are calling as. Roles an account\nabove this one has marked inheritable are not included here - each account's\nlisting is its own.", "parameters": [ { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 5 ] }, "name": { "type": "string", "examples": [ "Example Role" ] }, "code": { "type": "string", "examples": [ "example-role" ] }, "permissions": { "type": "object", "properties": { "account": { "type": "boolean", "examples": [ true ] }, "account:read": { "type": "boolean", "examples": [ true ] }, "account:update": { "type": "boolean", "examples": [ true ] }, "event": { "type": "boolean", "examples": [ true ] }, "event:read": { "type": "boolean", "examples": [ true ] }, "event:create": { "type": "boolean", "examples": [ true ] }, "event:update": { "type": "boolean", "examples": [ true ] }, "user": { "type": "boolean", "examples": [ true ] }, "user:read": { "type": "boolean", "examples": [ true ] }, "user:update": { "type": "boolean", "examples": [ true ] }, "report": { "type": "boolean", "examples": [ true ] }, "report:read": { "type": "boolean", "examples": [ true ] } } }, "horizontal": { "type": [ "string", "null" ], "examples": [ null ] }, "prefill": { "type": [ "string", "null" ], "examples": [ null ] }, "is_system": { "type": "integer", "examples": [ 1 ] }, "is_lite_admin": { "type": "integer", "examples": [ 0 ] }, "is_simple_attribute_selection": { "type": "integer", "examples": [ 0 ] }, "is_restricted": { "type": "integer", "examples": [ 0 ] }, "is_inheritable": { "type": "integer", "examples": [ 0 ] }, "access_required_modules": { "type": [ "string", "null" ], "examples": [ null ] }, "options": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:33:39.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:33:39.000000Z" ] }, "user_dashboard_id": { "type": [ "string", "null" ], "examples": [ null ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:role:5" ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ false ] }, "delete": { "type": "boolean", "examples": [ false ] }, "update_message": { "type": "string", "examples": [ "You cannot update a role you are assigned to." ] }, "copy": { "type": "boolean", "examples": [ true ] } } } } }, "examples": [ [ { "object": { "id": 5, "name": "Example Role", "code": "example-role", "permissions": { "account": true, "account:read": true, "account:update": true, "event": true, "event:read": true, "event:create": true, "event:update": true, "user": true, "user:read": true, "user:update": true, "report": true, "report:read": true }, "horizontal": null, "prefill": null, "is_system": 1, "is_lite_admin": 0, "is_simple_attribute_selection": 0, "is_restricted": 0, "is_inheritable": 0, "access_required_modules": null, "options": null, "created_at": "2026-06-09T05:33:39.000000Z", "updated_at": "2026-06-09T05:33:39.000000Z", "user_dashboard_id": null }, "nice": { "rrn": "rrn:local:20101:role:5" }, "relations": [], "permissions": { "read": true, "update": false, "delete": false, "update_message": "You cannot update a role you are assigned to.", "copy": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/account/role?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/account/role?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/account/role" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 5, "name": "Example Role", "code": "example-role", "permissions": { "account": true, "account:read": true, "account:update": true, "event": true, "event:read": true, "event:create": true, "event:update": true, "user": true, "user:read": true, "user:update": true, "report": true, "report:read": true }, "horizontal": null, "prefill": null, "is_system": 1, "is_lite_admin": 0, "is_simple_attribute_selection": 0, "is_restricted": 0, "is_inheritable": 0, "access_required_modules": null, "options": null, "created_at": "2026-06-09T05:33:39.000000Z", "updated_at": "2026-06-09T05:33:39.000000Z", "user_dashboard_id": null }, "nice": { "rrn": "rrn:local:20101:role:5" }, "relations": [], "permissions": { "read": true, "update": false, "delete": false, "update_message": "You cannot update a role you are assigned to.", "copy": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/account/role?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/account/role?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/account/role", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Account Module" ] }, "post": { "summary": "Create a role", "operationId": "createARole", "description": "Creates a role in the account you are calling as. The account is taken from the\ncaller and cannot be set from the request. The response is the same shape as\nreading the role, so a follow-up read is not needed.\n\n`name`, `code` and `permissions` are all required; a request missing any of them\ncomes back as a `422` naming the ones at fault. A `permissions` object granting\nmore than the caller's own role holds is rejected the same way.\n\n**`options` is stored whole.** The object you send replaces the stored one rather\nthan merging into it, so send every key you want to keep.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 5 ] }, "name": { "type": "string", "examples": [ "Example Role" ] }, "code": { "type": "string", "examples": [ "example-role" ] }, "permissions": { "type": "object", "properties": { "account": { "type": "boolean", "examples": [ true ] }, "account:read": { "type": "boolean", "examples": [ true ] }, "account:update": { "type": "boolean", "examples": [ true ] }, "event": { "type": "boolean", "examples": [ true ] }, "event:read": { "type": "boolean", "examples": [ true ] }, "event:create": { "type": "boolean", "examples": [ true ] }, "event:update": { "type": "boolean", "examples": [ true ] }, "user": { "type": "boolean", "examples": [ true ] }, "user:read": { "type": "boolean", "examples": [ true ] }, "user:update": { "type": "boolean", "examples": [ true ] }, "report": { "type": "boolean", "examples": [ true ] }, "report:read": { "type": "boolean", "examples": [ true ] } } }, "horizontal": { "type": [ "string", "null" ], "examples": [ null ] }, "prefill": { "type": [ "string", "null" ], "examples": [ null ] }, "is_system": { "type": "integer", "examples": [ 1 ] }, "is_lite_admin": { "type": "integer", "examples": [ 0 ] }, "is_simple_attribute_selection": { "type": "integer", "examples": [ 0 ] }, "is_restricted": { "type": "integer", "examples": [ 0 ] }, "is_inheritable": { "type": "integer", "examples": [ 0 ] }, "access_required_modules": { "type": [ "string", "null" ], "examples": [ null ] }, "options": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:33:39.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:33:39.000000Z" ] }, "user_dashboard_id": { "type": [ "string", "null" ], "examples": [ null ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:role:5" ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ false ] }, "delete": { "type": "boolean", "examples": [ false ] }, "update_message": { "type": "string", "examples": [ "You cannot update a role you are assigned to." ] }, "copy": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 5, "name": "Example Role", "code": "example-role", "permissions": { "account": true, "account:read": true, "account:update": true, "event": true, "event:read": true, "event:create": true, "event:update": true, "user": true, "user:read": true, "user:update": true, "report": true, "report:read": true }, "horizontal": null, "prefill": null, "is_system": 1, "is_lite_admin": 0, "is_simple_attribute_selection": 0, "is_restricted": 0, "is_inheritable": 0, "access_required_modules": null, "options": null, "created_at": "2026-06-09T05:33:39.000000Z", "updated_at": "2026-06-09T05:33:39.000000Z", "user_dashboard_id": null }, "nice": { "rrn": "rrn:local:20101:role:5" }, "relations": [], "permissions": { "read": true, "update": false, "delete": false, "update_message": "You cannot update a role you are assigned to.", "copy": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Account Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the role, up to 255 characters. This is what administrators pick from when assigning someone a role.", "examples": [ "Example Role" ] }, "permissions": { "type": "object", "description": "What the role may do, as an object of permission names against true or false. The set of names is the account's own and is not enumerated here - read an existing role to see the ones available to you, and send the same shape back. A role cannot be given a permission the caller's own role does not hold; attempting it is rejected.", "properties": {}, "examples": [ { "account": true, "account:read": true, "account:update": true, "event": true, "event:read": true, "event:create": true, "event:update": true, "user": true, "user:read": true, "user:update": true, "report": true, "report:read": true } ] }, "horizontal": { "type": "object", "description": "Optional limits on which records the role may act on, as an object keyed by the area being limited. Structure is not part of the contract - build the limits in the admin console and send back what a read returns. Entries naming an area the role has no permission for are dropped rather than rejected, so a role can come back with fewer limits than were sent.", "properties": {}, "examples": [ "{}" ] }, "prefill": { "type": "array", "description": "Optional values to fill in automatically on records this role creates. Structure is not part of the contract - build it in the admin console and send back what a read returns. Each attribute may appear only once.", "items": { "type": "array", "description": "", "items": { "type": "object" }, "examples": [ null ] }, "examples": [ [] ] }, "is_lite_admin": { "type": "boolean", "description": "Whether the role is a lite administrator, a reduced role whose permissions are limited to a fixed subset. Setting it discards any permission outside that subset rather than rejecting the request.", "examples": [ 0 ] }, "is_inheritable": { "type": "boolean", "description": "Whether accounts below this one may use the role as well as the account that owns it.", "examples": [ 0 ] }, "code": { "type": "string", "description": "Stable identifier for the role, up to 64 characters of letters, digits, hyphens and underscores; anything else is stripped. Use it to map the role to one in your identity provider when signing in through SSO. Must be unique within the account, and one is generated if you leave it empty.", "examples": [ "example-role" ] }, "is_simple_attribute_selection": { "type": "boolean", "description": "Whether the admin console offers this role the simplified attribute picker instead of the full one.", "examples": [ 0 ] }, "options": { "type": "object", "description": "", "properties": { "protect_pii": { "type": "boolean", "description": "Whether people with this role are blocked from seeing private fields on a record. Requires the account to have role-based field protection enabled.", "examples": [ true ] }, "protect_pii_all": { "type": "boolean", "description": "Whether the block covers every private field rather than a chosen list. Only applies when options.protect_pii is set.", "examples": [ true ] }, "protect_pii_by_field": { "type": "array", "description": "Which fields to block, as a list of attribute codes. Used only when options.protect_pii is set and options.protect_pii_all is not.", "items": { "type": "string" }, "examples": [ [] ] }, "mask_pii": { "type": "boolean", "description": "Whether private fields are shown to this role with their values obscured rather than hidden outright. Requires the account to have role-based field masking enabled.", "examples": [ true ] }, "mask_pii_all": { "type": "boolean", "description": "Whether masking covers every private field rather than a chosen list. Only applies when options.mask_pii is set.", "examples": [ true ] }, "mask_pii_by_field": { "type": "array", "description": "Which fields to mask, as a list of attribute codes. Used only when options.mask_pii is set and options.mask_pii_all is not.", "items": { "type": "string" }, "examples": [ [] ] } }, "examples": [ { "protect_pii": true } ] } }, "required": [ "name", "permissions", "code" ] } } } } } }, "/api/v2/account/role/{id}": { "get": { "summary": "Read a role", "operationId": "readARole", "description": "Returns one role: its name, its code, what it is allowed to do, and any limits on\nthe records it may act on.\n\n`object.permissions` is narrowed to what the account itself has available, so the\nsame role read from two accounts can come back with different keys. The example\nbelow shows a handful of them rather than the whole set.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 5 ] }, "name": { "type": "string", "examples": [ "Example Role" ] }, "code": { "type": "string", "examples": [ "example-role" ] }, "permissions": { "type": "object", "properties": { "account": { "type": "boolean", "examples": [ true ] }, "account:read": { "type": "boolean", "examples": [ true ] }, "account:update": { "type": "boolean", "examples": [ true ] }, "event": { "type": "boolean", "examples": [ true ] }, "event:read": { "type": "boolean", "examples": [ true ] }, "event:create": { "type": "boolean", "examples": [ true ] }, "event:update": { "type": "boolean", "examples": [ true ] }, "user": { "type": "boolean", "examples": [ true ] }, "user:read": { "type": "boolean", "examples": [ true ] }, "user:update": { "type": "boolean", "examples": [ true ] }, "report": { "type": "boolean", "examples": [ true ] }, "report:read": { "type": "boolean", "examples": [ true ] } } }, "horizontal": { "type": [ "string", "null" ], "examples": [ null ] }, "prefill": { "type": [ "string", "null" ], "examples": [ null ] }, "is_system": { "type": "integer", "examples": [ 1 ] }, "is_lite_admin": { "type": "integer", "examples": [ 0 ] }, "is_simple_attribute_selection": { "type": "integer", "examples": [ 0 ] }, "is_restricted": { "type": "integer", "examples": [ 0 ] }, "is_inheritable": { "type": "integer", "examples": [ 0 ] }, "access_required_modules": { "type": [ "string", "null" ], "examples": [ null ] }, "options": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:33:39.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:33:39.000000Z" ] }, "user_dashboard_id": { "type": [ "string", "null" ], "examples": [ null ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:role:5" ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ false ] }, "delete": { "type": "boolean", "examples": [ false ] }, "update_message": { "type": "string", "examples": [ "You cannot update a role you are assigned to." ] }, "copy": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 5, "name": "Example Role", "code": "example-role", "permissions": { "account": true, "account:read": true, "account:update": true, "event": true, "event:read": true, "event:create": true, "event:update": true, "user": true, "user:read": true, "user:update": true, "report": true, "report:read": true }, "horizontal": null, "prefill": null, "is_system": 1, "is_lite_admin": 0, "is_simple_attribute_selection": 0, "is_restricted": 0, "is_inheritable": 0, "access_required_modules": null, "options": null, "created_at": "2026-06-09T05:33:39.000000Z", "updated_at": "2026-06-09T05:33:39.000000Z", "user_dashboard_id": null }, "nice": { "rrn": "rrn:local:20101:role:5" }, "relations": [], "permissions": { "read": true, "update": false, "delete": false, "update_message": "You cannot update a role you are assigned to.", "copy": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Account Module" ] }, "put": { "summary": "Update a role", "operationId": "updateARole", "description": "Updates a role and returns it in the same shape as reading it. Every field is\noptional; a request with an empty body succeeds and changes nothing.\n\n**You cannot update a role you hold yourself.** Doing so is refused with a `403`\nand a message saying so, which is deliberate rather than an authorisation\naccident - it stops an administrator editing their own permissions. Have someone\non a different role make the change.\n\nA `permissions` object granting more than the caller's own role holds is rejected\nwith a `422`.\n\n**`options` is stored whole.** The object you send replaces the stored one rather\nthan merging into it, so an update carrying only `options.protect_pii` clears\nevery other key under it. Send every key you want to keep.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 5 ] }, "name": { "type": "string", "examples": [ "Example Role" ] }, "code": { "type": "string", "examples": [ "example-role" ] }, "permissions": { "type": "object", "properties": { "account": { "type": "boolean", "examples": [ true ] }, "account:read": { "type": "boolean", "examples": [ true ] }, "account:update": { "type": "boolean", "examples": [ true ] }, "event": { "type": "boolean", "examples": [ true ] }, "event:read": { "type": "boolean", "examples": [ true ] }, "event:create": { "type": "boolean", "examples": [ true ] }, "event:update": { "type": "boolean", "examples": [ true ] }, "user": { "type": "boolean", "examples": [ true ] }, "user:read": { "type": "boolean", "examples": [ true ] }, "user:update": { "type": "boolean", "examples": [ true ] }, "report": { "type": "boolean", "examples": [ true ] }, "report:read": { "type": "boolean", "examples": [ true ] } } }, "horizontal": { "type": [ "string", "null" ], "examples": [ null ] }, "prefill": { "type": [ "string", "null" ], "examples": [ null ] }, "is_system": { "type": "integer", "examples": [ 1 ] }, "is_lite_admin": { "type": "integer", "examples": [ 0 ] }, "is_simple_attribute_selection": { "type": "integer", "examples": [ 0 ] }, "is_restricted": { "type": "integer", "examples": [ 0 ] }, "is_inheritable": { "type": "integer", "examples": [ 0 ] }, "access_required_modules": { "type": [ "string", "null" ], "examples": [ null ] }, "options": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:33:39.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:33:39.000000Z" ] }, "user_dashboard_id": { "type": [ "string", "null" ], "examples": [ null ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:role:5" ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ false ] }, "delete": { "type": "boolean", "examples": [ false ] }, "update_message": { "type": "string", "examples": [ "You cannot update a role you are assigned to." ] }, "copy": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 5, "name": "Example Role", "code": "example-role", "permissions": { "account": true, "account:read": true, "account:update": true, "event": true, "event:read": true, "event:create": true, "event:update": true, "user": true, "user:read": true, "user:update": true, "report": true, "report:read": true }, "horizontal": null, "prefill": null, "is_system": 1, "is_lite_admin": 0, "is_simple_attribute_selection": 0, "is_restricted": 0, "is_inheritable": 0, "access_required_modules": null, "options": null, "created_at": "2026-06-09T05:33:39.000000Z", "updated_at": "2026-06-09T05:33:39.000000Z", "user_dashboard_id": null }, "nice": { "rrn": "rrn:local:20101:role:5" }, "relations": [], "permissions": { "read": true, "update": false, "delete": false, "update_message": "You cannot update a role you are assigned to.", "copy": true } } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "You cannot update a role you are assigned to." ] } }, "examples": [ { "message": "You cannot update a role you are assigned to." } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Account Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the role, up to 255 characters. This is what administrators pick from when assigning someone a role.", "examples": [ "Example Role" ] }, "permissions": { "type": "object", "description": "What the role may do, as an object of permission names against true or false. The set of names is the account's own and is not enumerated here - read an existing role to see the ones available to you, and send the same shape back. A role cannot be given a permission the caller's own role does not hold; attempting it is rejected.", "properties": {}, "examples": [ { "account": true, "account:read": true, "account:update": true, "event": true, "event:read": true, "event:create": true, "event:update": true, "user": true, "user:read": true, "user:update": true, "report": true, "report:read": true } ] }, "horizontal": { "type": "object", "description": "Optional limits on which records the role may act on, as an object keyed by the area being limited. Structure is not part of the contract - build the limits in the admin console and send back what a read returns. Entries naming an area the role has no permission for are dropped rather than rejected, so a role can come back with fewer limits than were sent.", "properties": {}, "examples": [ "{}" ] }, "prefill": { "type": "array", "description": "Optional values to fill in automatically on records this role creates. Structure is not part of the contract - build it in the admin console and send back what a read returns. Each attribute may appear only once.", "items": { "type": "array", "description": "", "items": { "type": "object" }, "examples": [ null ] }, "examples": [ [] ] }, "is_lite_admin": { "type": "boolean", "description": "Whether the role is a lite administrator, a reduced role whose permissions are limited to a fixed subset. Setting it discards any permission outside that subset rather than rejecting the request.", "examples": [ 0 ] }, "code": { "type": "string", "description": "Stable identifier for the role, up to 64 characters of letters, digits, hyphens and underscores; anything else is stripped. Use it to map the role to one in your identity provider when signing in through SSO. Must be unique within the account, and one is generated if you leave it empty.", "examples": [ "example-role" ] }, "is_simple_attribute_selection": { "type": "boolean", "description": "Whether the admin console offers this role the simplified attribute picker instead of the full one.", "examples": [ 0 ] }, "is_restricted": { "type": "boolean", "description": "Whether the role is limited to specific records within the areas named in access_required_modules, chosen per person rather than per role. Update only.", "examples": [ 0 ] }, "is_inheritable": { "type": "boolean", "description": "Whether accounts below this one may use the role as well as the account that owns it.", "examples": [ 0 ] }, "access_required_modules": { "type": "array", "description": "Which areas the per-person limits apply to, as a list of area names: headcount_functional_area, headcount_functional_area_job_title, headcount_location, headcount_location_venue or headcount_user_type. Cleared unless is_restricted is set. Update only.", "items": { "type": "string" }, "examples": [ [] ] }, "options": { "type": "object", "description": "", "properties": { "protect_pii": { "type": "boolean", "description": "Whether people with this role are blocked from seeing private fields on a record. Requires the account to have role-based field protection enabled.", "examples": [ true ] }, "protect_pii_all": { "type": "boolean", "description": "Whether the block covers every private field rather than a chosen list. Only applies when options.protect_pii is set.", "examples": [ true ] }, "protect_pii_by_field": { "type": "array", "description": "Which fields to block, as a list of attribute codes. Used only when options.protect_pii is set and options.protect_pii_all is not.", "items": { "type": "string" }, "examples": [ [] ] }, "mask_pii": { "type": "boolean", "description": "Whether private fields are shown to this role with their values obscured rather than hidden outright. Requires the account to have role-based field masking enabled.", "examples": [ true ] }, "mask_pii_all": { "type": "boolean", "description": "Whether masking covers every private field rather than a chosen list. Only applies when options.mask_pii is set.", "examples": [ true ] }, "mask_pii_by_field": { "type": "array", "description": "Which fields to mask, as a list of attribute codes. Used only when options.mask_pii is set and options.mask_pii_all is not.", "items": { "type": "string" }, "examples": [ [] ] } }, "examples": [ { "protect_pii": true } ] } } } } } } }, "delete": { "summary": "Delete a role", "operationId": "deleteARole", "description": "Removes a role. Anyone holding it loses it, and their active API tokens are\nterminated. A person left with no role at all is no longer an administrator of\nthe account.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "204": { "description": "No content, successful deletion", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Account Module" ] }, "parameters": [ { "in": "path", "name": "id", "description": "The ID of the role.", "required": true, "schema": { "type": "integer", "examples": [ 5 ] } } ] }, "/api/v2/account/role/{role_id}/user": { "get": { "summary": "List the people holding a role", "operationId": "listThePeopleHoldingARole", "description": "Returns everyone in this account who holds the role named in the URL. Each row is\nthe person's full record, not a membership record, with `object.added_at` giving\nthe moment they were assigned the role.\n\nOnly assignments made in the account you are calling as are returned. A role that\naccounts below this one also use lists its members separately in each of them.", "parameters": [ { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 23453473 ] }, "id_token": { "type": "string", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxx" ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "email": { "type": "string", "examples": [ "jordan.avery@example.com" ] }, "force_reset_password": { "type": "integer", "examples": [ 0 ] }, "password_expires_at": { "type": [ "string", "null" ], "examples": [ null ] }, "first_name": { "type": "string", "examples": [ "Jordan" ] }, "middle_name": { "type": [ "string", "null" ], "examples": [ null ] }, "last_name": { "type": "string", "examples": [ "Avery" ] }, "preferred_name": { "type": [ "string", "null" ], "examples": [ null ] }, "phone": { "type": "string", "examples": [ "au-297809703" ] }, "dob": { "type": "string", "examples": [ "1990-01-01" ] }, "picture": { "type": [ "string", "null" ], "examples": [ null ] }, "picture_status": { "type": "integer", "examples": [ 0 ] }, "is_subscribed": { "type": "integer", "examples": [ 0 ] }, "is_subscribed_transactional": { "type": "integer", "examples": [ 1 ] }, "is_unreachable": { "type": "integer", "examples": [ 0 ] }, "is_unreachable_sms": { "type": "integer", "examples": [ 0 ] }, "terms": { "type": "integer", "examples": [ 1 ] }, "rating": { "type": "string", "examples": [ "0.00" ] }, "shift_privacy": { "type": "integer", "examples": [ 1 ] }, "is_team_leader": { "type": "integer", "examples": [ 0 ] }, "email_verified": { "type": "integer", "examples": [ 0 ] }, "login_lockout_attempts": { "type": "integer", "examples": [ 0 ] }, "login_lockout_at": { "type": [ "string", "null" ], "examples": [ null ] }, "login_lockout_email_sent_at": { "type": [ "string", "null" ], "examples": [ null ] }, "last_login_at": { "type": "string", "examples": [ "2026-08-10T05:16:30.000000Z" ] }, "last_app_login_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "last_activated": { "type": [ "string", "null" ], "examples": [ null ] }, "from_source": { "type": [ "string", "null" ], "examples": [ null ] }, "delete_requested_at": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:33:39.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:33:39.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "interests": { "type": [ "string", "null" ], "examples": [ null ] }, "address": { "type": "object", "properties": { "iso": { "type": "string", "examples": [ "AUS" ] }, "region_code": { "type": "string", "examples": [ "VIC" ] }, "coordinates": { "type": "object", "properties": { "latitude": { "type": [ "string", "null" ], "examples": [ null ] }, "longitude": { "type": [ "string", "null" ], "examples": [ null ] } } }, "street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "city": { "type": "string", "examples": [ "Melbourne" ] }, "postcode": { "type": "string", "examples": [ "3000" ] }, "region": { "type": "string", "examples": [ "VIC" ] }, "country": { "type": "string", "examples": [ "AU" ] }, "latitude": { "type": [ "string", "null" ], "examples": [ null ] }, "longitude": { "type": [ "string", "null" ], "examples": [ null ] } } }, "added_at": { "type": "string", "examples": [ "2026-06-09T05:33:39.000000Z" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:user:xxxxxxxxxxxxxxxxxxxxxxxx" ] }, "address": { "type": "string", "examples": [ "1 Example Street\nMelbourne\nVictoria\nAustralia\n3000" ] }, "address_oneline": { "type": "string", "examples": [ "1 Example Street, Melbourne, Victoria, Australia, 3000" ] }, "address.country": { "type": "string", "examples": [ "Australia" ] }, "address.country:raw": { "type": "string", "examples": [ "AUS" ] }, "address.city": { "type": "string", "examples": [ "Melbourne" ] }, "address.region": { "type": "string", "examples": [ "Victoria" ] }, "address.region:raw": { "type": "string", "examples": [ "VIC" ] }, "address.postcode": { "type": "string", "examples": [ "3000" ] }, "address.street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "address.street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "address.street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "address.latitude": { "type": [ "string", "null" ], "examples": [ null ] }, "address.longitude": { "type": [ "string", "null" ], "examples": [ null ] }, "family_id": { "type": [ "string", "null" ], "examples": [ null ] }, "has_family_members": { "type": "string", "examples": [ "No" ] }, "manages_family": { "type": "boolean", "examples": [ false ] }, "family_manager": { "type": "string", "examples": [ "No" ] }, "family_member": { "type": "string", "examples": [ "No" ] }, "is_family_member": { "type": "boolean", "examples": [ false ] }, "is_engaged": { "type": "string", "examples": [ "No" ] }, "is_engaged:raw": { "type": "boolean", "examples": [ false ] }, "last_engaged_at": { "type": [ "string", "null" ], "examples": [ null ] }, "last_engaged_at:raw": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:33 AM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "5:33 AM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "email_verified": { "type": "string", "examples": [ "No" ] }, "from_source": { "type": "string", "examples": [ "" ] }, "interests": { "type": [ "string", "null" ], "examples": [ null ] }, "interests:value": { "type": [ "string", "null" ], "examples": [ null ] }, "interests:array": { "type": [ "string", "null" ], "examples": [ null ] }, "is_subscribed_transactional": { "type": "string", "examples": [ "Yes" ] }, "is_team_leader": { "type": "string", "examples": [ "No" ] }, "last_login_at": { "type": "string", "examples": [ "Aug 10, 2026, 5:16 AM" ] }, "last_login_at__date": { "type": "string", "examples": [ "Aug 10, 2026" ] }, "last_login_at__time": { "type": "string", "examples": [ "5:16 AM" ] }, "last_login_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "last_login_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "last_login_at__dayofweek": { "type": "string", "examples": [ "Monday" ] }, "middle_name": { "type": "string", "examples": [ "" ] }, "picture_status": { "type": "string", "examples": [ "N/A" ] }, "picture_status:value": { "type": "integer", "examples": [ 0 ] }, "picture_status:array": { "type": "string", "examples": [ "N/A" ] }, "shift_privacy": { "type": "string", "examples": [ "Yes" ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:33 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:33 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "first_name": { "type": "string", "examples": [ "Jordan" ] }, "last_name": { "type": "string", "examples": [ "Avery" ] }, "preferred_name": { "type": "string", "examples": [ "" ] }, "phone:qr_code_value": { "type": "string", "examples": [ "au-297809703" ] }, "phone": { "type": "string", "examples": [ "(+61) 297809703" ] }, "phone:raw": { "type": "string", "examples": [ "+61297809703" ] }, "phone:local_au": { "type": "string", "examples": [ "0297809703" ] }, "dob": { "type": "string", "examples": [ "Jan 1, 1990" ] }, "dob__dayofweek": { "type": "string", "examples": [ "Monday" ] }, "is_subscribed": { "type": "string", "examples": [ "No" ] }, "terms": { "type": "string", "examples": [ "Yes" ] }, "name": { "type": "string", "examples": [ "Jordan Avery" ] }, "age": { "type": "integer", "examples": [ 36 ] }, "age_months": { "type": "string", "examples": [ "36 years, 7 months" ] }, "info": { "type": "string", "examples": [ "Jordan Avery (jordan.avery@example.com)" ] }, "preferred_first_name": { "type": "string", "examples": [ "Jordan" ] }, "delete_requested": { "type": "boolean", "examples": [ false ] }, "updated_hours": { "type": "number", "examples": [ 1583.176031565 ] }, "is_community_user": { "type": "boolean", "examples": [ false ] }, "timezone": { "type": "string", "examples": [ "UTC" ] } } }, "relations": { "type": "object", "properties": { "user_checkpoint": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 3 ] }, "user_checkpoint_type_id": { "type": [ "string", "null" ], "examples": [ null ] }, "name": { "type": "string", "examples": [ "Default" ] }, "label": { "type": "string", "examples": [ "default" ] }, "permissions": { "type": "object", "properties": { "all": { "type": "string", "examples": [ "1" ] } } }, "actions": { "type": "array", "examples": [ [] ] }, "is_inheritable": { "type": "integer", "examples": [ 0 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:33:39.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:34:24.000000Z" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:checkpoint:3" ] }, "content_id": { "type": "integer", "examples": [ 3 ] }, "account_name_path": { "type": "string", "examples": [ "Example Organisation" ] }, "is_foreign_account": { "type": "boolean", "examples": [ false ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ false ] } } } } }, "user_type": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 2 ] }, "account_branding_id": { "type": [ "string", "null" ], "examples": [ null ] }, "name": { "type": "string", "examples": [ "Default" ] }, "code": { "type": "string", "examples": [ "default" ] }, "profile_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "training_ids": { "type": [ "string", "null" ], "examples": [ null ] }, "registration_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_limit": { "type": "integer", "examples": [ 0 ] }, "shift_max_time": { "type": [ "string", "null" ], "examples": [ null ] }, "max_shift_length": { "type": "integer", "examples": [ 0 ] }, "min_shift_length": { "type": "integer", "examples": [ 0 ] }, "min_consecutive_rest_time_per_week": { "type": "integer", "examples": [ 0 ] }, "max_work_days_per_week": { "type": "integer", "examples": [ 0 ] }, "gap_between_shifts": { "type": "integer", "examples": [ 0 ] }, "group_leader_attributes": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:33:39.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:33:39.000000Z" ] }, "uuid": { "type": "string", "examples": [ "0cdefc27-b599-4a15-a82f-18c11bb44803" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ false ] } } } } }, "account": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 20101 ] }, "parent_id": { "type": "integer", "examples": [ 1 ] }, "account_type_id": { "type": "integer", "examples": [ 3 ] }, "path": { "type": "string", "examples": [ "1/20101" ] }, "name": { "type": "string", "examples": [ "Example Organisation" ] }, "config": { "type": "object", "properties": { "active_settings": { "type": "array", "items": { "type": "string" }, "examples": [ [ "general:locale", "general:timezone", "general:country", "users:login", "users:register", "users:require_dob", "event:shift_status_default", "event:self_checkin", "branding:name", "branding:primary_color" ] ] } } }, "meta": { "type": "array", "examples": [ [] ] }, "visibility_rules": { "type": "array", "examples": [ [] ] }, "status": { "type": "string", "examples": [ "approved" ] }, "status_reason": { "type": [ "string", "null" ], "examples": [ null ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "start_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "end_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "notes": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_firstname": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_lastname": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_email": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_phone": { "type": [ "string", "null" ], "examples": [ null ] }, "support_manager_email": { "type": "string", "examples": [ "billing@example.com" ] }, "allow_deletion_request": { "type": "integer", "examples": [ 1 ] }, "organization_type": { "type": [ "string", "null" ], "examples": [ null ] }, "contract_start_date": { "type": "string", "examples": [ "2026-06-09" ] }, "contract_end_date": { "type": "string", "examples": [ "2027-06-09" ] }, "billing_contact_email": { "type": "string", "examples": [ "billing@example.com" ] }, "billing_support_email": { "type": "string", "examples": [ "billing@example.com" ] }, "is_enabled": { "type": "integer", "examples": [ 1 ] }, "additional_billing_support_email": { "type": "string", "examples": [ "billing@example.com" ] }, "delete_requested_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "trial_ends_at": { "type": [ "string", "null" ], "examples": [ null ] }, "can_erase": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:33:32.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T07:08:01.000000Z" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:1:account:20101" ] }, "address": { "type": "string", "examples": [ "No Address" ] }, "address_oneline": { "type": "string", "examples": [ "No Address" ] }, "account_type_id": { "type": "integer", "examples": [ 3 ] }, "account_type_id:value": { "type": "integer", "examples": [ 3 ] }, "account_type_id:array": { "type": "integer", "examples": [ 3 ] }, "allow_deletion_request": { "type": "string", "examples": [ "Yes" ] }, "contact_firstname": { "type": "string", "examples": [ "" ] }, "contact_lastname": { "type": "string", "examples": [ "" ] }, "contact_phone:qr_code_value": { "type": "string", "examples": [ "" ] }, "contact_phone": { "type": "string", "examples": [ "" ] }, "contact_phone:raw": { "type": "string", "examples": [ "" ] }, "contract_end_date": { "type": "string", "examples": [ "Jun 9, 2027" ] }, "contract_end_date__dayofweek": { "type": "string", "examples": [ "Wednesday" ] }, "contract_start_date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "contract_start_date__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "name": { "type": "string", "examples": [ "Example Organisation" ] }, "notes": { "type": "string", "examples": [ "" ] }, "organization_type": { "type": [ "string", "null" ], "examples": [ null ] }, "organization_type:value": { "type": [ "string", "null" ], "examples": [ null ] }, "organization_type:array": { "type": [ "string", "null" ], "examples": [ null ] }, "status": { "type": "string", "examples": [ "Approved" ] }, "status:value": { "type": "string", "examples": [ "approved" ] }, "status:array": { "type": "string", "examples": [ "approved" ] }, "status_reason": { "type": "string", "examples": [ "" ] }, "created_at": { "type": "string", "examples": [ "2026-06-09 05:33:32" ] }, "url": { "type": "string", "examples": [ "https://example.rosterfy.com/" ] }, "branding_name": { "type": "string", "examples": [ "Example Organisation" ] }, "branding_subtitle": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo_mono": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo_stacked": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_banner": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_favicon": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_description": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_primary_color": { "type": "string", "examples": [ "#3131c7" ] }, "branding_complimentary_color": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_secondary_color": { "type": "string", "examples": [ "#38b6ff" ] }, "register": { "type": "boolean", "examples": [ false ] }, "organisation_contact": { "type": "string", "examples": [ " " ] }, "has_subaccount_approved_email_template": { "type": "boolean", "examples": [ false ] }, "has_subaccount_rejected_email_template": { "type": "boolean", "examples": [ false ] }, "parent_account_name": { "type": "string", "examples": [ "Example Parent Organisation" ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ false ] }, "delete": { "type": "boolean", "examples": [ false ] } } } } }, "family": { "type": [ "string", "null" ], "examples": [ null ] }, "family_user": { "type": [ "string", "null" ], "examples": [ null ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ false ] }, "delete": { "type": "boolean", "examples": [ false ] } } }, "attributes": { "type": "array", "examples": [ [] ] } } }, "examples": [ [ { "object": { "id": 23453473, "id_token": "xxxxxxxxxxxxxxxxxxxxxxxx", "account_id": 20101, "email": "jordan.avery@example.com", "force_reset_password": 0, "password_expires_at": null, "first_name": "Jordan", "middle_name": null, "last_name": "Avery", "preferred_name": null, "phone": "au-297809703", "dob": "1990-01-01", "picture": null, "picture_status": 0, "is_subscribed": 0, "is_subscribed_transactional": 1, "is_unreachable": 0, "is_unreachable_sms": 0, "terms": 1, "rating": "0.00", "shift_privacy": 1, "is_team_leader": 0, "email_verified": 0, "login_lockout_attempts": 0, "login_lockout_at": null, "login_lockout_email_sent_at": null, "last_login_at": "2026-08-10T05:16:30.000000Z", "last_app_login_at": null, "is_archived": 0, "last_activated": null, "from_source": null, "delete_requested_at": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:33:39.000000Z", "updated_at": "2026-06-09T05:33:39.000000Z", "deleted_by": null, "interests": null, "address": { "iso": "AUS", "region_code": "VIC", "coordinates": { "latitude": null, "longitude": null }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "Melbourne", "postcode": "3000", "region": "VIC", "country": "AU", "latitude": null, "longitude": null }, "added_at": "2026-06-09T05:33:39.000000Z" }, "nice": { "rrn": "rrn:local:20101:user:xxxxxxxxxxxxxxxxxxxxxxxx", "address": "1 Example Street\nMelbourne\nVictoria\nAustralia\n3000", "address_oneline": "1 Example Street, Melbourne, Victoria, Australia, 3000", "address.country": "Australia", "address.country:raw": "AUS", "address.city": "Melbourne", "address.region": "Victoria", "address.region:raw": "VIC", "address.postcode": "3000", "address.street_address_1": "1 Example Street", "address.street_address_2": null, "address.street_address_3": null, "address.latitude": null, "address.longitude": null, "family_id": null, "has_family_members": "No", "manages_family": false, "family_manager": "No", "family_member": "No", "is_family_member": false, "is_engaged": "No", "is_engaged:raw": false, "last_engaged_at": null, "last_engaged_at:raw": null, "created_at": "Jun 9, 2026, 5:33 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:33 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "email_verified": "No", "from_source": "", "interests": null, "interests:value": null, "interests:array": null, "is_subscribed_transactional": "Yes", "is_team_leader": "No", "last_login_at": "Aug 10, 2026, 5:16 AM", "last_login_at__date": "Aug 10, 2026", "last_login_at__time": "5:16 AM", "last_login_at__offset": " (+00:00 UTC)", "last_login_at__offset_minutes": 0, "last_login_at__dayofweek": "Monday", "middle_name": "", "picture_status": "N/A", "picture_status:value": 0, "picture_status:array": "N/A", "shift_privacy": "Yes", "updated_at": "Jun 9, 2026, 5:33 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:33 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "first_name": "Jordan", "last_name": "Avery", "preferred_name": "", "phone:qr_code_value": "au-297809703", "phone": "(+61) 297809703", "phone:raw": "+61297809703", "phone:local_au": "0297809703", "dob": "Jan 1, 1990", "dob__dayofweek": "Monday", "is_subscribed": "No", "terms": "Yes", "name": "Jordan Avery", "age": 36, "age_months": "36 years, 7 months", "info": "Jordan Avery (jordan.avery@example.com)", "preferred_first_name": "Jordan", "delete_requested": false, "updated_hours": 1583.176031565, "is_community_user": false, "timezone": "UTC" }, "relations": { "user_checkpoint": { "object": { "id": 3, "user_checkpoint_type_id": null, "name": "Default", "label": "default", "permissions": { "all": "1" }, "actions": [], "is_inheritable": 0, "sort_order": 0, "deleted_at": null, "created_at": "2026-06-09T05:33:39.000000Z", "updated_at": "2026-06-09T05:34:24.000000Z" }, "nice": { "rrn": "rrn:local:20101:checkpoint:3", "content_id": 3, "account_name_path": "Example Organisation", "is_foreign_account": false }, "permissions": { "read": true, "update": true, "delete": false } }, "user_type": { "object": { "id": 2, "account_branding_id": null, "name": "Default", "code": "default", "profile_form_id": null, "training_ids": null, "registration_form_id": null, "shift_limit": 0, "shift_max_time": null, "max_shift_length": 0, "min_shift_length": 0, "min_consecutive_rest_time_per_week": 0, "max_work_days_per_week": 0, "gap_between_shifts": 0, "group_leader_attributes": null, "deleted_at": null, "created_at": "2026-06-09T05:33:39.000000Z", "updated_at": "2026-06-09T05:33:39.000000Z", "uuid": "0cdefc27-b599-4a15-a82f-18c11bb44803" }, "nice": [], "permissions": { "read": true, "update": true, "delete": false } }, "account": { "object": { "id": 20101, "parent_id": 1, "account_type_id": 3, "path": "1/20101", "name": "Example Organisation", "config": { "active_settings": [ "general:locale", "general:timezone", "general:country", "users:login", "users:register", "users:require_dob", "event:shift_status_default", "event:self_checkin", "branding:name", "branding:primary_color" ] }, "meta": [], "visibility_rules": [], "status": "approved", "status_reason": null, "sort_order": 0, "start_timestamp": null, "end_timestamp": null, "notes": null, "contact_firstname": null, "contact_lastname": null, "contact_email": null, "contact_phone": null, "support_manager_email": "billing@example.com", "allow_deletion_request": 1, "organization_type": null, "contract_start_date": "2026-06-09", "contract_end_date": "2027-06-09", "billing_contact_email": "billing@example.com", "billing_support_email": "billing@example.com", "is_enabled": 1, "additional_billing_support_email": "billing@example.com", "delete_requested_at": null, "is_archived": 0, "trial_ends_at": null, "can_erase": 0, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:33:32.000000Z", "updated_at": "2026-06-09T07:08:01.000000Z" }, "nice": { "rrn": "rrn:local:1:account:20101", "address": "No Address", "address_oneline": "No Address", "account_type_id": 3, "account_type_id:value": 3, "account_type_id:array": 3, "allow_deletion_request": "Yes", "contact_firstname": "", "contact_lastname": "", "contact_phone:qr_code_value": "", "contact_phone": "", "contact_phone:raw": "", "contract_end_date": "Jun 9, 2027", "contract_end_date__dayofweek": "Wednesday", "contract_start_date": "Jun 9, 2026", "contract_start_date__dayofweek": "Tuesday", "name": "Example Organisation", "notes": "", "organization_type": null, "organization_type:value": null, "organization_type:array": null, "status": "Approved", "status:value": "approved", "status:array": "approved", "status_reason": "", "created_at": "2026-06-09 05:33:32", "url": "https://example.rosterfy.com/", "branding_name": "Example Organisation", "branding_subtitle": null, "branding_logo": null, "branding_logo_mono": null, "branding_logo_stacked": null, "branding_banner": null, "branding_favicon": null, "branding_description": null, "branding_primary_color": "#3131c7", "branding_complimentary_color": null, "branding_secondary_color": "#38b6ff", "register": false, "organisation_contact": " ", "has_subaccount_approved_email_template": false, "has_subaccount_rejected_email_template": false, "parent_account_name": "Example Parent Organisation" }, "permissions": { "read": true, "update": false, "delete": false } }, "family": null, "family_user": null }, "permissions": { "read": true, "update": false, "delete": false }, "attributes": [] }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/account/role/{role}/user?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/account/role/{role}/user?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/account/role/{role}/user" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 23453473, "id_token": "xxxxxxxxxxxxxxxxxxxxxxxx", "account_id": 20101, "email": "jordan.avery@example.com", "force_reset_password": 0, "password_expires_at": null, "first_name": "Jordan", "middle_name": null, "last_name": "Avery", "preferred_name": null, "phone": "au-297809703", "dob": "1990-01-01", "picture": null, "picture_status": 0, "is_subscribed": 0, "is_subscribed_transactional": 1, "is_unreachable": 0, "is_unreachable_sms": 0, "terms": 1, "rating": "0.00", "shift_privacy": 1, "is_team_leader": 0, "email_verified": 0, "login_lockout_attempts": 0, "login_lockout_at": null, "login_lockout_email_sent_at": null, "last_login_at": "2026-08-10T05:16:30.000000Z", "last_app_login_at": null, "is_archived": 0, "last_activated": null, "from_source": null, "delete_requested_at": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:33:39.000000Z", "updated_at": "2026-06-09T05:33:39.000000Z", "deleted_by": null, "interests": null, "address": { "iso": "AUS", "region_code": "VIC", "coordinates": { "latitude": null, "longitude": null }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "Melbourne", "postcode": "3000", "region": "VIC", "country": "AU", "latitude": null, "longitude": null }, "added_at": "2026-06-09T05:33:39.000000Z" }, "nice": { "rrn": "rrn:local:20101:user:xxxxxxxxxxxxxxxxxxxxxxxx", "address": "1 Example Street\nMelbourne\nVictoria\nAustralia\n3000", "address_oneline": "1 Example Street, Melbourne, Victoria, Australia, 3000", "address.country": "Australia", "address.country:raw": "AUS", "address.city": "Melbourne", "address.region": "Victoria", "address.region:raw": "VIC", "address.postcode": "3000", "address.street_address_1": "1 Example Street", "address.street_address_2": null, "address.street_address_3": null, "address.latitude": null, "address.longitude": null, "family_id": null, "has_family_members": "No", "manages_family": false, "family_manager": "No", "family_member": "No", "is_family_member": false, "is_engaged": "No", "is_engaged:raw": false, "last_engaged_at": null, "last_engaged_at:raw": null, "created_at": "Jun 9, 2026, 5:33 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:33 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "email_verified": "No", "from_source": "", "interests": null, "interests:value": null, "interests:array": null, "is_subscribed_transactional": "Yes", "is_team_leader": "No", "last_login_at": "Aug 10, 2026, 5:16 AM", "last_login_at__date": "Aug 10, 2026", "last_login_at__time": "5:16 AM", "last_login_at__offset": " (+00:00 UTC)", "last_login_at__offset_minutes": 0, "last_login_at__dayofweek": "Monday", "middle_name": "", "picture_status": "N/A", "picture_status:value": 0, "picture_status:array": "N/A", "shift_privacy": "Yes", "updated_at": "Jun 9, 2026, 5:33 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:33 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "first_name": "Jordan", "last_name": "Avery", "preferred_name": "", "phone:qr_code_value": "au-297809703", "phone": "(+61) 297809703", "phone:raw": "+61297809703", "phone:local_au": "0297809703", "dob": "Jan 1, 1990", "dob__dayofweek": "Monday", "is_subscribed": "No", "terms": "Yes", "name": "Jordan Avery", "age": 36, "age_months": "36 years, 7 months", "info": "Jordan Avery (jordan.avery@example.com)", "preferred_first_name": "Jordan", "delete_requested": false, "updated_hours": 1583.176031565, "is_community_user": false, "timezone": "UTC" }, "relations": { "user_checkpoint": { "object": { "id": 3, "user_checkpoint_type_id": null, "name": "Default", "label": "default", "permissions": { "all": "1" }, "actions": [], "is_inheritable": 0, "sort_order": 0, "deleted_at": null, "created_at": "2026-06-09T05:33:39.000000Z", "updated_at": "2026-06-09T05:34:24.000000Z" }, "nice": { "rrn": "rrn:local:20101:checkpoint:3", "content_id": 3, "account_name_path": "Example Organisation", "is_foreign_account": false }, "permissions": { "read": true, "update": true, "delete": false } }, "user_type": { "object": { "id": 2, "account_branding_id": null, "name": "Default", "code": "default", "profile_form_id": null, "training_ids": null, "registration_form_id": null, "shift_limit": 0, "shift_max_time": null, "max_shift_length": 0, "min_shift_length": 0, "min_consecutive_rest_time_per_week": 0, "max_work_days_per_week": 0, "gap_between_shifts": 0, "group_leader_attributes": null, "deleted_at": null, "created_at": "2026-06-09T05:33:39.000000Z", "updated_at": "2026-06-09T05:33:39.000000Z", "uuid": "0cdefc27-b599-4a15-a82f-18c11bb44803" }, "nice": [], "permissions": { "read": true, "update": true, "delete": false } }, "account": { "object": { "id": 20101, "parent_id": 1, "account_type_id": 3, "path": "1/20101", "name": "Example Organisation", "config": { "active_settings": [ "general:locale", "general:timezone", "general:country", "users:login", "users:register", "users:require_dob", "event:shift_status_default", "event:self_checkin", "branding:name", "branding:primary_color" ] }, "meta": [], "visibility_rules": [], "status": "approved", "status_reason": null, "sort_order": 0, "start_timestamp": null, "end_timestamp": null, "notes": null, "contact_firstname": null, "contact_lastname": null, "contact_email": null, "contact_phone": null, "support_manager_email": "billing@example.com", "allow_deletion_request": 1, "organization_type": null, "contract_start_date": "2026-06-09", "contract_end_date": "2027-06-09", "billing_contact_email": "billing@example.com", "billing_support_email": "billing@example.com", "is_enabled": 1, "additional_billing_support_email": "billing@example.com", "delete_requested_at": null, "is_archived": 0, "trial_ends_at": null, "can_erase": 0, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:33:32.000000Z", "updated_at": "2026-06-09T07:08:01.000000Z" }, "nice": { "rrn": "rrn:local:1:account:20101", "address": "No Address", "address_oneline": "No Address", "account_type_id": 3, "account_type_id:value": 3, "account_type_id:array": 3, "allow_deletion_request": "Yes", "contact_firstname": "", "contact_lastname": "", "contact_phone:qr_code_value": "", "contact_phone": "", "contact_phone:raw": "", "contract_end_date": "Jun 9, 2027", "contract_end_date__dayofweek": "Wednesday", "contract_start_date": "Jun 9, 2026", "contract_start_date__dayofweek": "Tuesday", "name": "Example Organisation", "notes": "", "organization_type": null, "organization_type:value": null, "organization_type:array": null, "status": "Approved", "status:value": "approved", "status:array": "approved", "status_reason": "", "created_at": "2026-06-09 05:33:32", "url": "https://example.rosterfy.com/", "branding_name": "Example Organisation", "branding_subtitle": null, "branding_logo": null, "branding_logo_mono": null, "branding_logo_stacked": null, "branding_banner": null, "branding_favicon": null, "branding_description": null, "branding_primary_color": "#3131c7", "branding_complimentary_color": null, "branding_secondary_color": "#38b6ff", "register": false, "organisation_contact": " ", "has_subaccount_approved_email_template": false, "has_subaccount_rejected_email_template": false, "parent_account_name": "Example Parent Organisation" }, "permissions": { "read": true, "update": false, "delete": false } }, "family": null, "family_user": null }, "permissions": { "read": true, "update": false, "delete": false }, "attributes": [] }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/account/role/{role}/user?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/account/role/{role}/user?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/account/role/{role}/user", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Account Module" ] }, "post": { "summary": "Give a person a role", "operationId": "giveAPersonARole", "description": "Assigns one person the role named in the URL. **A 201 carries no body** - read the\nrole's members afterwards if you need the resulting record.\n\nA person may hold only one role per account. Naming someone who already holds one\nis refused with a `400` and a message saying so, and the way to move them is to\nremove the existing assignment first. A `400` is also what you get when `user_id`\nis missing altogether.\n\nThe person has to belong to the same account as the role, and an administrator\ncannot assign a role to themselves.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "examples": [ {} ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "User already exists in this role" ] } }, "examples": [ { "message": "User already exists in this role" } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Account Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "The person to give the role to.", "examples": [ 23453473 ] } }, "required": [ "user_id" ] } } } } }, "parameters": [ { "in": "path", "name": "role_id", "description": "The ID of the role.", "required": true, "schema": { "type": "integer", "examples": [ 5 ] } } ] }, "/api/v2/account/role/{role_id}/user/mass-create": { "post": { "summary": "Give a role to many people", "operationId": "giveARoleToManyPeople", "description": "Queues the work of assigning a set of people the role named in the URL and returns\na token for the queued job. **Nothing is assigned by the time the response comes\nback**, and the token is not something you can poll - confirm the outcome by\nlisting the role's members.\n\n**Send the fields as form fields or in the query string, not as a JSON body.**\n`selected` is read from the query and form data only, so a request carrying it as\nJSON comes back as a `404` with nothing assigned.\n\nA request whose fields are the right shape always returns a queue token, whether\nor not the background work then succeeds: someone who belongs to another account,\nalready holds a role here, or would exceed the account's administrator limit is\nskipped rather than reported.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "queue": { "type": "string", "examples": [ "mTsVQ1NCLS3vg7WwP5kG1Vbt" ] } }, "examples": [ { "queue": "mTsVQ1NCLS3vg7WwP5kG1Vbt" } ] } } } } }, "tags": [ "Account Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "applyTo": { "type": "string", "description": "Must be sent, with the value selected. This endpoint only ever adds the people named in selected; no other value changes what it does.", "examples": [ null ] }, "selected": { "type": "array", "description": "The people to add, as a list of user ids. A person who cannot be given the role - because they belong to a different account, or already hold a role in this one - is skipped rather than reported.", "items": { "type": "integer" }, "examples": [ [] ] } }, "required": [ "applyTo", "selected" ] } } } } }, "parameters": [ { "in": "path", "name": "role_id", "description": "The ID of the role.", "required": true, "schema": { "type": "integer", "examples": [ 5 ] } } ] }, "/api/v2/blog/article": { "get": { "summary": "List articles", "operationId": "listArticles", "description": "Returns a paginated list of the articles the caller is allowed to read, in\nthe current account and the accounts above it. A caller with the\nblog:article:read permission sees every article; anyone else sees only\npublished ones, and an unauthenticated caller sees only articles that are\nboth published and marked public.", "parameters": [ { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "suscipit laudantium iste" ] }, "sub_heading": { "type": [ "string", "null" ], "examples": [ null ] }, "description": { "type": "string", "examples": [ "" ] }, "content": { "type": "string", "examples": [ "

Iste tempore autem saepe eligendi tempore rerum saepe. Doloremque consectetur sint earum corrupti officia omnis. Omnis iusto corporis et non ut.

Odio sed aliquam iure architecto optio ea. Quae sit occaecati quas quia. Praesentium ipsam nobis nesciunt nam.

Aut tempore eos perferendis aliquid suscipit ut qui dolorem. Consequatur voluptatibus cumque molestiae. Harum itaque qui ad ipsa tempora commodi earum.

Tenetur officiis sunt delectus. Minima voluptas eum debitis omnis rerum numquam unde ipsa. Ut asperiores velit quisquam et amet earum. Eligendi est debitis sit quos voluptatem. Atque aut quae officiis sint voluptatem.

" ] }, "blog_article_type_id": { "type": [ "string", "null" ], "examples": [ null ] }, "author_id": { "type": "integer", "examples": [ 23453598 ] }, "thumbnail": { "type": "string", "examples": [ "https://qa.rosterfy.com/static/img/testing/thumbnail_400_400.jpg" ] }, "wide_thumbnail": { "type": [ "string", "null" ], "examples": [ null ] }, "banner_image": { "type": "string", "examples": [ "https://qa.rosterfy.com/static/img/testing/banner_image_1200_300.jpeg" ] }, "token": { "type": "string", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] }, "public": { "type": "integer", "examples": [ 1 ] }, "publish": { "type": "integer", "examples": [ 1 ] }, "promoted": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:26.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:26.000000Z" ] } } }, "nice": { "type": "object", "properties": { "description": { "type": "string", "examples": [ "Iste tempore autem saepe eligendi tempore rerum saepe. Doloremque consectetur sint earum corrupti of..." ] }, "read_at": { "type": "string", "examples": [ "2026-07-29 01:25:31" ] }, "liked": { "type": "boolean", "examples": [ false ] }, "total_likes": { "type": "integer", "examples": [ 0 ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } }, "examples": [ [ { "object": { "id": 1, "name": "suscipit laudantium iste", "sub_heading": null, "description": "", "content": "

Iste tempore autem saepe eligendi tempore rerum saepe. Doloremque consectetur sint earum corrupti officia omnis. Omnis iusto corporis et non ut.

Odio sed aliquam iure architecto optio ea. Quae sit occaecati quas quia. Praesentium ipsam nobis nesciunt nam.

Aut tempore eos perferendis aliquid suscipit ut qui dolorem. Consequatur voluptatibus cumque molestiae. Harum itaque qui ad ipsa tempora commodi earum.

Tenetur officiis sunt delectus. Minima voluptas eum debitis omnis rerum numquam unde ipsa. Ut asperiores velit quisquam et amet earum. Eligendi est debitis sit quos voluptatem. Atque aut quae officiis sint voluptatem.

", "blog_article_type_id": null, "author_id": 23453598, "thumbnail": "https://qa.rosterfy.com/static/img/testing/thumbnail_400_400.jpg", "wide_thumbnail": null, "banner_image": "https://qa.rosterfy.com/static/img/testing/banner_image_1200_300.jpeg", "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "public": 1, "publish": 1, "promoted": 0, "created_at": "2026-06-09T05:36:26.000000Z", "updated_at": "2026-06-09T05:36:26.000000Z" }, "nice": { "description": "Iste tempore autem saepe eligendi tempore rerum saepe. Doloremque consectetur sint earum corrupti of...", "read_at": "2026-07-29 01:25:31", "liked": false, "total_likes": 0 }, "relations": [], "permissions": { "read": true, "update": true, "delete": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/blog/article?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/blog/article?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/blog/article" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 1, "name": "suscipit laudantium iste", "sub_heading": null, "description": "", "content": "

Iste tempore autem saepe eligendi tempore rerum saepe. Doloremque consectetur sint earum corrupti officia omnis. Omnis iusto corporis et non ut.

Odio sed aliquam iure architecto optio ea. Quae sit occaecati quas quia. Praesentium ipsam nobis nesciunt nam.

Aut tempore eos perferendis aliquid suscipit ut qui dolorem. Consequatur voluptatibus cumque molestiae. Harum itaque qui ad ipsa tempora commodi earum.

Tenetur officiis sunt delectus. Minima voluptas eum debitis omnis rerum numquam unde ipsa. Ut asperiores velit quisquam et amet earum. Eligendi est debitis sit quos voluptatem. Atque aut quae officiis sint voluptatem.

", "blog_article_type_id": null, "author_id": 23453598, "thumbnail": "https://qa.rosterfy.com/static/img/testing/thumbnail_400_400.jpg", "wide_thumbnail": null, "banner_image": "https://qa.rosterfy.com/static/img/testing/banner_image_1200_300.jpeg", "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "public": 1, "publish": 1, "promoted": 0, "created_at": "2026-06-09T05:36:26.000000Z", "updated_at": "2026-06-09T05:36:26.000000Z" }, "nice": { "description": "Iste tempore autem saepe eligendi tempore rerum saepe. Doloremque consectetur sint earum corrupti of...", "read_at": "2026-07-29 01:25:31", "liked": false, "total_likes": 0 }, "relations": [], "permissions": { "read": true, "update": true, "delete": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/blog/article?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/blog/article?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/blog/article", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Blog Module" ] }, "post": { "summary": "Create an article", "operationId": "createAnArticle", "description": "Creates an article in the current account, with the calling user recorded\nas its author. The response is the same shape as reading the article, so a\nfollow-up read is not needed.\n\nA public token is generated on create and returned as object.token. It is\nthe token the publicly accessible URL uses, and it cannot be set by the\ncaller.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "suscipit laudantium iste" ] }, "sub_heading": { "type": [ "string", "null" ], "examples": [ null ] }, "description": { "type": "string", "examples": [ "" ] }, "content": { "type": "string", "examples": [ "

Iste tempore autem saepe eligendi tempore rerum saepe. Doloremque consectetur sint earum corrupti officia omnis. Omnis iusto corporis et non ut.

Odio sed aliquam iure architecto optio ea. Quae sit occaecati quas quia. Praesentium ipsam nobis nesciunt nam.

Aut tempore eos perferendis aliquid suscipit ut qui dolorem. Consequatur voluptatibus cumque molestiae. Harum itaque qui ad ipsa tempora commodi earum.

Tenetur officiis sunt delectus. Minima voluptas eum debitis omnis rerum numquam unde ipsa. Ut asperiores velit quisquam et amet earum. Eligendi est debitis sit quos voluptatem. Atque aut quae officiis sint voluptatem.

" ] }, "blog_article_type_id": { "type": [ "string", "null" ], "examples": [ null ] }, "author_id": { "type": "integer", "examples": [ 23453598 ] }, "thumbnail": { "type": "string", "examples": [ "https://qa.rosterfy.com/static/img/testing/thumbnail_400_400.jpg" ] }, "wide_thumbnail": { "type": [ "string", "null" ], "examples": [ null ] }, "banner_image": { "type": "string", "examples": [ "https://qa.rosterfy.com/static/img/testing/banner_image_1200_300.jpeg" ] }, "token": { "type": "string", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] }, "public": { "type": "integer", "examples": [ 1 ] }, "publish": { "type": "integer", "examples": [ 1 ] }, "promoted": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:26.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:26.000000Z" ] } } }, "nice": { "type": "object", "properties": { "description": { "type": "string", "examples": [ "Iste tempore autem saepe eligendi tempore rerum saepe. Doloremque consectetur sint earum corrupti of..." ] }, "read_at": { "type": "string", "examples": [ "2026-07-29 01:25:31" ] }, "liked": { "type": "boolean", "examples": [ false ] }, "total_likes": { "type": "integer", "examples": [ 0 ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "name": "suscipit laudantium iste", "sub_heading": null, "description": "", "content": "

Iste tempore autem saepe eligendi tempore rerum saepe. Doloremque consectetur sint earum corrupti officia omnis. Omnis iusto corporis et non ut.

Odio sed aliquam iure architecto optio ea. Quae sit occaecati quas quia. Praesentium ipsam nobis nesciunt nam.

Aut tempore eos perferendis aliquid suscipit ut qui dolorem. Consequatur voluptatibus cumque molestiae. Harum itaque qui ad ipsa tempora commodi earum.

Tenetur officiis sunt delectus. Minima voluptas eum debitis omnis rerum numquam unde ipsa. Ut asperiores velit quisquam et amet earum. Eligendi est debitis sit quos voluptatem. Atque aut quae officiis sint voluptatem.

", "blog_article_type_id": null, "author_id": 23453598, "thumbnail": "https://qa.rosterfy.com/static/img/testing/thumbnail_400_400.jpg", "wide_thumbnail": null, "banner_image": "https://qa.rosterfy.com/static/img/testing/banner_image_1200_300.jpeg", "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "public": 1, "publish": 1, "promoted": 0, "created_at": "2026-06-09T05:36:26.000000Z", "updated_at": "2026-06-09T05:36:26.000000Z" }, "nice": { "description": "Iste tempore autem saepe eligendi tempore rerum saepe. Doloremque consectetur sint earum corrupti of...", "read_at": "2026-07-29 01:25:31", "liked": false, "total_likes": 0 }, "relations": [], "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Blog Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The article title. Translatable: send a plain string to set it for the request locale, or an object keyed by locale such as {\"en-US\": \"Title\"}.", "examples": [ "suscipit laudantium iste" ] }, "content": { "type": "string", "description": "The article body as HTML. Translatable, as for name. HTML is sanitised on read, so scripts and unsafe attributes are stripped from responses.", "examples": [ "

Iste tempore autem saepe eligendi tempore rerum saepe. Doloremque consectetur sint earum corrupti officia omnis. Omnis iusto corporis et non ut.

Odio sed aliquam iure architecto optio ea. Quae sit occaecati quas quia. Praesentium ipsam nobis nesciunt nam.

Aut tempore eos perferendis aliquid suscipit ut qui dolorem. Consequatur voluptatibus cumque molestiae. Harum itaque qui ad ipsa tempora commodi earum.

Tenetur officiis sunt delectus. Minima voluptas eum debitis omnis rerum numquam unde ipsa. Ut asperiores velit quisquam et amet earum. Eligendi est debitis sit quos voluptatem. Atque aut quae officiis sint voluptatem.

" ] }, "sub_heading": { "type": "string", "description": "A secondary heading shown under the title. Translatable, as for name.", "examples": [ null ] }, "publish": { "type": "boolean", "description": "Boolean. Whether the article appears in the portal News Articles section.", "examples": [ 1 ] }, "public": { "type": "boolean", "description": "Boolean. Whether the article is reachable without logging in, via its token. Independent of publish.", "examples": [ 1 ] }, "promoted": { "type": "boolean", "description": "Boolean. Whether the article appears on the portal dashboard. Rejected if it would exceed the account's limit:max_promoted_news setting.", "examples": [ 0 ] }, "banner_image": { "type": "string", "description": "URL of, or an upload for, the banner image shown at the top of the article. Recommended 1200x300 pixels.", "examples": [ "https://qa.rosterfy.com/static/img/testing/banner_image_1200_300.jpeg" ] }, "thumbnail": { "type": "string", "description": "URL of, or an upload for, the thumbnail image shown in the half-width article list. Recommended 300x300 pixels.", "examples": [ "https://qa.rosterfy.com/static/img/testing/thumbnail_400_400.jpg" ] }, "wide_thumbnail": { "type": "string", "description": "URL of, or an upload for, the thumbnail image shown in the full-width article list. Recommended 600x300 pixels.", "examples": [ null ] }, "description": { "type": "string", "description": "A short summary of the article. Translatable, as for name. When empty, the nice.description in responses falls back to the first 100 characters of content.", "examples": [ "" ] }, "blog_article_type_id": { "type": "integer", "description": "The ID of the article type to categorise this article under.", "examples": [ 1 ] } }, "required": [ "name", "content", "publish", "public" ] } } } } } }, "/api/v2/blog/article/{id}": { "get": { "summary": "Read an article", "operationId": "readAnArticle", "description": "Returns a single article. Reading also records the article as read for the\ncalling user the first time they fetch it, which is what populates\nnice.read_at and makes nice.liked meaningful on later reads.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "suscipit laudantium iste" ] }, "sub_heading": { "type": [ "string", "null" ], "examples": [ null ] }, "description": { "type": "string", "examples": [ "" ] }, "content": { "type": "string", "examples": [ "

Iste tempore autem saepe eligendi tempore rerum saepe. Doloremque consectetur sint earum corrupti officia omnis. Omnis iusto corporis et non ut.

Odio sed aliquam iure architecto optio ea. Quae sit occaecati quas quia. Praesentium ipsam nobis nesciunt nam.

Aut tempore eos perferendis aliquid suscipit ut qui dolorem. Consequatur voluptatibus cumque molestiae. Harum itaque qui ad ipsa tempora commodi earum.

Tenetur officiis sunt delectus. Minima voluptas eum debitis omnis rerum numquam unde ipsa. Ut asperiores velit quisquam et amet earum. Eligendi est debitis sit quos voluptatem. Atque aut quae officiis sint voluptatem.

" ] }, "blog_article_type_id": { "type": [ "string", "null" ], "examples": [ null ] }, "author_id": { "type": "integer", "examples": [ 23453598 ] }, "thumbnail": { "type": "string", "examples": [ "https://qa.rosterfy.com/static/img/testing/thumbnail_400_400.jpg" ] }, "wide_thumbnail": { "type": [ "string", "null" ], "examples": [ null ] }, "banner_image": { "type": "string", "examples": [ "https://qa.rosterfy.com/static/img/testing/banner_image_1200_300.jpeg" ] }, "token": { "type": "string", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] }, "public": { "type": "integer", "examples": [ 1 ] }, "publish": { "type": "integer", "examples": [ 1 ] }, "promoted": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:26.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:26.000000Z" ] } } }, "nice": { "type": "object", "properties": { "description": { "type": "string", "examples": [ "Iste tempore autem saepe eligendi tempore rerum saepe. Doloremque consectetur sint earum corrupti of..." ] }, "read_at": { "type": "string", "examples": [ "2026-07-29 01:25:31" ] }, "liked": { "type": "boolean", "examples": [ false ] }, "total_likes": { "type": "integer", "examples": [ 0 ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "name": "suscipit laudantium iste", "sub_heading": null, "description": "", "content": "

Iste tempore autem saepe eligendi tempore rerum saepe. Doloremque consectetur sint earum corrupti officia omnis. Omnis iusto corporis et non ut.

Odio sed aliquam iure architecto optio ea. Quae sit occaecati quas quia. Praesentium ipsam nobis nesciunt nam.

Aut tempore eos perferendis aliquid suscipit ut qui dolorem. Consequatur voluptatibus cumque molestiae. Harum itaque qui ad ipsa tempora commodi earum.

Tenetur officiis sunt delectus. Minima voluptas eum debitis omnis rerum numquam unde ipsa. Ut asperiores velit quisquam et amet earum. Eligendi est debitis sit quos voluptatem. Atque aut quae officiis sint voluptatem.

", "blog_article_type_id": null, "author_id": 23453598, "thumbnail": "https://qa.rosterfy.com/static/img/testing/thumbnail_400_400.jpg", "wide_thumbnail": null, "banner_image": "https://qa.rosterfy.com/static/img/testing/banner_image_1200_300.jpeg", "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "public": 1, "publish": 1, "promoted": 0, "created_at": "2026-06-09T05:36:26.000000Z", "updated_at": "2026-06-09T05:36:26.000000Z" }, "nice": { "description": "Iste tempore autem saepe eligendi tempore rerum saepe. Doloremque consectetur sint earum corrupti of...", "read_at": "2026-07-29 01:25:31", "liked": false, "total_likes": 0 }, "relations": [], "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Blog Module" ] }, "put": { "summary": "Update an article", "operationId": "updateAnArticle", "description": "Updates the fields supplied and leaves the rest untouched, then returns the\narticle in the same shape as reading it. Every field is optional. Invalid\ninput returns a 422 identifying the fields at fault.\n\nSending a translatable field as a plain string replaces only the value for\nthe request locale. Send an object keyed by locale to set several at once.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "suscipit laudantium iste" ] }, "sub_heading": { "type": [ "string", "null" ], "examples": [ null ] }, "description": { "type": "string", "examples": [ "" ] }, "content": { "type": "string", "examples": [ "

Iste tempore autem saepe eligendi tempore rerum saepe. Doloremque consectetur sint earum corrupti officia omnis. Omnis iusto corporis et non ut.

Odio sed aliquam iure architecto optio ea. Quae sit occaecati quas quia. Praesentium ipsam nobis nesciunt nam.

Aut tempore eos perferendis aliquid suscipit ut qui dolorem. Consequatur voluptatibus cumque molestiae. Harum itaque qui ad ipsa tempora commodi earum.

Tenetur officiis sunt delectus. Minima voluptas eum debitis omnis rerum numquam unde ipsa. Ut asperiores velit quisquam et amet earum. Eligendi est debitis sit quos voluptatem. Atque aut quae officiis sint voluptatem.

" ] }, "blog_article_type_id": { "type": [ "string", "null" ], "examples": [ null ] }, "author_id": { "type": "integer", "examples": [ 23453598 ] }, "thumbnail": { "type": "string", "examples": [ "https://qa.rosterfy.com/static/img/testing/thumbnail_400_400.jpg" ] }, "wide_thumbnail": { "type": [ "string", "null" ], "examples": [ null ] }, "banner_image": { "type": "string", "examples": [ "https://qa.rosterfy.com/static/img/testing/banner_image_1200_300.jpeg" ] }, "token": { "type": "string", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] }, "public": { "type": "integer", "examples": [ 1 ] }, "publish": { "type": "integer", "examples": [ 1 ] }, "promoted": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:26.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:26.000000Z" ] } } }, "nice": { "type": "object", "properties": { "description": { "type": "string", "examples": [ "Iste tempore autem saepe eligendi tempore rerum saepe. Doloremque consectetur sint earum corrupti of..." ] }, "read_at": { "type": "string", "examples": [ "2026-07-29 01:25:31" ] }, "liked": { "type": "boolean", "examples": [ false ] }, "total_likes": { "type": "integer", "examples": [ 0 ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "name": "suscipit laudantium iste", "sub_heading": null, "description": "", "content": "

Iste tempore autem saepe eligendi tempore rerum saepe. Doloremque consectetur sint earum corrupti officia omnis. Omnis iusto corporis et non ut.

Odio sed aliquam iure architecto optio ea. Quae sit occaecati quas quia. Praesentium ipsam nobis nesciunt nam.

Aut tempore eos perferendis aliquid suscipit ut qui dolorem. Consequatur voluptatibus cumque molestiae. Harum itaque qui ad ipsa tempora commodi earum.

Tenetur officiis sunt delectus. Minima voluptas eum debitis omnis rerum numquam unde ipsa. Ut asperiores velit quisquam et amet earum. Eligendi est debitis sit quos voluptatem. Atque aut quae officiis sint voluptatem.

", "blog_article_type_id": null, "author_id": 23453598, "thumbnail": "https://qa.rosterfy.com/static/img/testing/thumbnail_400_400.jpg", "wide_thumbnail": null, "banner_image": "https://qa.rosterfy.com/static/img/testing/banner_image_1200_300.jpeg", "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "public": 1, "publish": 1, "promoted": 0, "created_at": "2026-06-09T05:36:26.000000Z", "updated_at": "2026-06-09T05:36:26.000000Z" }, "nice": { "description": "Iste tempore autem saepe eligendi tempore rerum saepe. Doloremque consectetur sint earum corrupti of...", "read_at": "2026-07-29 01:25:31", "liked": false, "total_likes": 0 }, "relations": [], "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Blog Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The article title. Translatable: send a plain string to set it for the request locale, or an object keyed by locale such as {\"en-US\": \"Title\"}.", "examples": [ "suscipit laudantium iste" ] }, "sub_heading": { "type": "string", "description": "A secondary heading shown under the title. Translatable, as for name.", "examples": [ null ] }, "description": { "type": "string", "description": "A short summary of the article. Translatable, as for name. When empty, the nice.description in responses falls back to the first 100 characters of content.", "examples": [ "" ] }, "content": { "type": "string", "description": "The article body as HTML. Translatable, as for name. HTML is sanitised on read, so scripts and unsafe attributes are stripped from responses.", "examples": [ "

Iste tempore autem saepe eligendi tempore rerum saepe. Doloremque consectetur sint earum corrupti officia omnis. Omnis iusto corporis et non ut.

Odio sed aliquam iure architecto optio ea. Quae sit occaecati quas quia. Praesentium ipsam nobis nesciunt nam.

Aut tempore eos perferendis aliquid suscipit ut qui dolorem. Consequatur voluptatibus cumque molestiae. Harum itaque qui ad ipsa tempora commodi earum.

Tenetur officiis sunt delectus. Minima voluptas eum debitis omnis rerum numquam unde ipsa. Ut asperiores velit quisquam et amet earum. Eligendi est debitis sit quos voluptatem. Atque aut quae officiis sint voluptatem.

" ] }, "thumbnail": { "type": "string", "description": "URL of, or an upload for, the thumbnail image shown in the half-width article list. Recommended 300x300 pixels.", "examples": [ "https://qa.rosterfy.com/static/img/testing/thumbnail_400_400.jpg" ] }, "wide_thumbnail": { "type": "string", "description": "URL of, or an upload for, the thumbnail image shown in the full-width article list. Recommended 600x300 pixels.", "examples": [ null ] }, "banner_image": { "type": "string", "description": "URL of, or an upload for, the banner image shown at the top of the article. Recommended 1200x300 pixels.", "examples": [ "https://qa.rosterfy.com/static/img/testing/banner_image_1200_300.jpeg" ] }, "blog_article_type_id": { "type": "integer", "description": "The ID of the article type to categorise this article under.", "examples": [ 1 ] }, "publish": { "type": "boolean", "description": "Boolean. Whether the article appears in the portal News Articles section.", "examples": [ 1 ] }, "public": { "type": "boolean", "description": "Boolean. Whether the article is reachable without logging in, via its token. Independent of publish.", "examples": [ 1 ] }, "promoted": { "type": "boolean", "description": "Boolean. Whether the article appears on the portal dashboard. Rejected if it would exceed the account's limit:max_promoted_news setting.", "examples": [ 0 ] } } } } } } }, "delete": { "summary": "Delete an article", "operationId": "deleteAnArticle", "description": "Permanently deletes the article. Its publicly accessible URL stops resolving\nimmediately.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "204": { "description": "No content, successful deletion", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Blog Module" ] }, "parameters": [ { "in": "path", "name": "id", "description": "The ID of the article.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/certificate/{certificate_id}/user": { "get": { "summary": "List certificate holders", "operationId": "listCertificateHolders", "description": "Returns the users a certificate has been issued to, one row per issue. With a\ncertificate ID in the path, the list is that certificate's holders; on the path\nwithout one, it spans every certificate in the account.\n\nOnly holders the caller is allowed to see are returned, so the list can be shorter\nthan the number of certificates issued.\n\nRows carry no related records unless asked for. Request `user` with `with` for the\nholder's profile, or `certificate` for the certificate's name, which is what the\naccount-wide list usually calls for. Reading a single holder always includes the\nuser, so this is only a concern for lists.", "parameters": [ { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "certificate_id": { "type": "integer", "examples": [ 1 ] }, "user_id": { "type": "integer", "examples": [ 23453479 ] }, "label": { "type": [ "string", "null" ], "examples": [ null ] }, "meta": { "type": "object", "properties": { "entities": { "type": "object", "properties": { "user": { "type": "integer", "examples": [ 23453479 ] }, "event": { "type": "integer", "examples": [ 1 ] }, "event_user": { "type": "integer", "examples": [ 1 ] }, "role_offer": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift": { "type": [ "string", "null" ], "examples": [ null ] }, "role_offer_user": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_user": { "type": [ "string", "null" ], "examples": [ null ] } } } } }, "created_at": { "type": "string", "examples": [ "2026-10-20T00:11:41.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-10-20T00:11:41.000000Z" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } }, "examples": [ [ { "object": { "id": 1, "certificate_id": 1, "user_id": 23453479, "label": null, "meta": { "entities": { "user": 23453479, "event": 1, "event_user": 1, "role_offer": null, "event_shift": null, "role_offer_user": null, "event_shift_user": null } }, "created_at": "2026-10-20T00:11:41.000000Z", "updated_at": "2026-10-20T00:11:41.000000Z" }, "nice": [], "relations": [], "permissions": { "read": true, "update": true, "delete": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/certificate/{certificate}/user?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/certificate/{certificate}/user?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/certificate/{certificate}/user" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 1, "certificate_id": 1, "user_id": 23453479, "label": null, "meta": { "entities": { "user": 23453479, "event": 1, "event_user": 1, "role_offer": null, "event_shift": null, "role_offer_user": null, "event_shift_user": null } }, "created_at": "2026-10-20T00:11:41.000000Z", "updated_at": "2026-10-20T00:11:41.000000Z" }, "nice": [], "relations": [], "permissions": { "read": true, "update": true, "delete": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/certificate/{certificate}/user?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/certificate/{certificate}/user?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/certificate/{certificate}/user", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Certificate Module" ] }, "parameters": [ { "in": "path", "name": "certificate_id", "description": "The ID of the certificate.", "required": true, "schema": { "type": "integer", "examples": [ 16 ] } } ] }, "/api/v2/certificate/{certificate_id}/user/{id}": { "get": { "summary": "Read a certificate holder", "operationId": "readACertificateHolder", "description": "Returns one issue of a certificate to a user: who holds it, the label printed on\nit, and when it was issued.\n\nThe holder's user record is always included under relations. meta.entities lists\nthe records the certificate was issued in connection with - an event, shift, role\noffer or training module - whose details can be printed on the certificate. Any of\nthem may be null.\n\nThe record must belong to the certificate in the URL; a mismatched pair returns a\n404.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "certificate_id": { "type": "integer", "examples": [ 1 ] }, "user_id": { "type": "integer", "examples": [ 23453479 ] }, "label": { "type": [ "string", "null" ], "examples": [ null ] }, "meta": { "type": "object", "properties": { "entities": { "type": "object", "properties": { "user": { "type": "integer", "examples": [ 23453479 ] }, "event": { "type": "integer", "examples": [ 1 ] }, "event_user": { "type": "integer", "examples": [ 1 ] }, "role_offer": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift": { "type": [ "string", "null" ], "examples": [ null ] }, "role_offer_user": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_user": { "type": [ "string", "null" ], "examples": [ null ] } } } } }, "created_at": { "type": "string", "examples": [ "2026-10-20T00:11:41.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-10-20T00:11:41.000000Z" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "relations": { "type": "object", "properties": { "user": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 23453479 ] }, "id_token": { "type": "string", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxx" ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "email": { "type": "string", "examples": [ "alex.taylor@example.com" ] }, "force_reset_password": { "type": "integer", "examples": [ 0 ] }, "password_expires_at": { "type": [ "string", "null" ], "examples": [ null ] }, "first_name": { "type": "string", "examples": [ "Alex" ] }, "middle_name": { "type": [ "string", "null" ], "examples": [ null ] }, "last_name": { "type": "string", "examples": [ "Taylor" ] }, "preferred_name": { "type": [ "string", "null" ], "examples": [ null ] }, "phone": { "type": "string", "examples": [ "au-390000000" ] }, "dob": { "type": "string", "examples": [ "1990-04-12" ] }, "picture": { "type": [ "string", "null" ], "examples": [ null ] }, "picture_status": { "type": "integer", "examples": [ 0 ] }, "is_subscribed": { "type": "integer", "examples": [ 0 ] }, "is_subscribed_transactional": { "type": "integer", "examples": [ 1 ] }, "is_unreachable": { "type": "integer", "examples": [ 0 ] }, "is_unreachable_sms": { "type": "integer", "examples": [ 0 ] }, "terms": { "type": "integer", "examples": [ 1 ] }, "rating": { "type": "string", "examples": [ "0.00" ] }, "shift_privacy": { "type": "integer", "examples": [ 1 ] }, "is_team_leader": { "type": "integer", "examples": [ 0 ] }, "email_verified": { "type": "integer", "examples": [ 0 ] }, "login_lockout_attempts": { "type": "integer", "examples": [ 0 ] }, "login_lockout_at": { "type": [ "string", "null" ], "examples": [ null ] }, "login_lockout_email_sent_at": { "type": [ "string", "null" ], "examples": [ null ] }, "last_login_at": { "type": [ "string", "null" ], "examples": [ null ] }, "last_app_login_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "last_activated": { "type": [ "string", "null" ], "examples": [ null ] }, "from_source": { "type": [ "string", "null" ], "examples": [ null ] }, "delete_requested_at": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-05-29T18:30:58.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:35:38.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "interests": { "type": [ "string", "null" ], "examples": [ null ] }, "address": { "type": "object", "properties": { "iso": { "type": "string", "examples": [ "AUS" ] }, "region_code": { "type": "string", "examples": [ "VIC" ] }, "coordinates": { "type": "object", "properties": { "latitude": { "type": "string", "examples": [ "-37.814000" ] }, "longitude": { "type": "string", "examples": [ "144.963200" ] } } }, "street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "city": { "type": "string", "examples": [ "Melbourne" ] }, "postcode": { "type": "string", "examples": [ "3000" ] }, "region": { "type": "string", "examples": [ "VIC" ] }, "country": { "type": "string", "examples": [ "AU" ] }, "latitude": { "type": "string", "examples": [ "-37.814000" ] }, "longitude": { "type": "string", "examples": [ "144.963200" ] } } } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:user:xxxxxxxxxxxxxxxxxxxxxxxx" ] }, "address": { "type": "string", "examples": [ "1 Example Street\nMelbourne\nVictoria\nAustralia\n3000" ] }, "address_oneline": { "type": "string", "examples": [ "1 Example Street, Melbourne, Victoria, Australia, 3000" ] }, "address.country": { "type": "string", "examples": [ "Australia" ] }, "address.country:raw": { "type": "string", "examples": [ "AUS" ] }, "address.city": { "type": "string", "examples": [ "Melbourne" ] }, "address.region": { "type": "string", "examples": [ "Victoria" ] }, "address.region:raw": { "type": "string", "examples": [ "VIC" ] }, "address.postcode": { "type": "string", "examples": [ "3000" ] }, "address.street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "address.street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "address.street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "address.latitude": { "type": "string", "examples": [ "-37.814000" ] }, "address.longitude": { "type": "string", "examples": [ "144.963200" ] }, "family_id": { "type": [ "string", "null" ], "examples": [ null ] }, "has_family_members": { "type": "string", "examples": [ "No" ] }, "manages_family": { "type": "boolean", "examples": [ false ] }, "family_manager": { "type": "string", "examples": [ "No" ] }, "family_member": { "type": "string", "examples": [ "No" ] }, "is_family_member": { "type": "boolean", "examples": [ false ] }, "is_engaged": { "type": "string", "examples": [ "No" ] }, "is_engaged:raw": { "type": "boolean", "examples": [ false ] }, "last_engaged_at": { "type": [ "string", "null" ], "examples": [ null ] }, "last_engaged_at:raw": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "May 29, 2026, 6:30 PM" ] }, "created_at__date": { "type": "string", "examples": [ "May 29, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "6:30 PM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Friday" ] }, "email_verified": { "type": "string", "examples": [ "No" ] }, "from_source": { "type": "string", "examples": [ "" ] }, "interests": { "type": [ "string", "null" ], "examples": [ null ] }, "interests:value": { "type": [ "string", "null" ], "examples": [ null ] }, "interests:array": { "type": [ "string", "null" ], "examples": [ null ] }, "is_subscribed_transactional": { "type": "string", "examples": [ "Yes" ] }, "is_team_leader": { "type": "string", "examples": [ "No" ] }, "middle_name": { "type": "string", "examples": [ "" ] }, "picture_status": { "type": "string", "examples": [ "N/A" ] }, "picture_status:value": { "type": "integer", "examples": [ 0 ] }, "picture_status:array": { "type": "string", "examples": [ "N/A" ] }, "shift_privacy": { "type": "string", "examples": [ "Yes" ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:35 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:35 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "first_name": { "type": "string", "examples": [ "Alex" ] }, "last_name": { "type": "string", "examples": [ "Taylor" ] }, "preferred_name": { "type": "string", "examples": [ "" ] }, "phone:qr_code_value": { "type": "string", "examples": [ "au-390000000" ] }, "phone": { "type": "string", "examples": [ "(+61) 390000000" ] }, "phone:raw": { "type": "string", "examples": [ "+61390000000" ] }, "phone:local_au": { "type": "string", "examples": [ "0390000000" ] }, "dob": { "type": "string", "examples": [ "Apr 12, 1990" ] }, "dob__dayofweek": { "type": "string", "examples": [ "Thursday" ] }, "is_subscribed": { "type": "string", "examples": [ "No" ] }, "terms": { "type": "string", "examples": [ "Yes" ] }, "name": { "type": "string", "examples": [ "Alex Taylor" ] }, "age": { "type": "integer", "examples": [ 36 ] }, "age_months": { "type": "string", "examples": [ "36 years, 4 months" ] }, "info": { "type": "string", "examples": [ "Alex Taylor (alex.taylor@example.com)" ] }, "preferred_first_name": { "type": "string", "examples": [ "Alex" ] }, "delete_requested": { "type": "boolean", "examples": [ false ] }, "updated_hours": { "type": "number", "examples": [ 1673.4862143775 ] }, "is_community_user": { "type": "boolean", "examples": [ false ] }, "timezone": { "type": "string", "examples": [ "UTC" ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } }, "id": { "type": "integer", "examples": [ 23453479 ] }, "name": { "type": "string", "examples": [ "Alex Taylor" ] } } } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "certificate_id": 1, "user_id": 23453479, "label": null, "meta": { "entities": { "user": 23453479, "event": 1, "event_user": 1, "role_offer": null, "event_shift": null, "role_offer_user": null, "event_shift_user": null } }, "created_at": "2026-10-20T00:11:41.000000Z", "updated_at": "2026-10-20T00:11:41.000000Z" }, "nice": [], "relations": { "user": { "object": { "id": 23453479, "id_token": "xxxxxxxxxxxxxxxxxxxxxxxx", "account_id": 20101, "email": "alex.taylor@example.com", "force_reset_password": 0, "password_expires_at": null, "first_name": "Alex", "middle_name": null, "last_name": "Taylor", "preferred_name": null, "phone": "au-390000000", "dob": "1990-04-12", "picture": null, "picture_status": 0, "is_subscribed": 0, "is_subscribed_transactional": 1, "is_unreachable": 0, "is_unreachable_sms": 0, "terms": 1, "rating": "0.00", "shift_privacy": 1, "is_team_leader": 0, "email_verified": 0, "login_lockout_attempts": 0, "login_lockout_at": null, "login_lockout_email_sent_at": null, "last_login_at": null, "last_app_login_at": null, "is_archived": 0, "last_activated": null, "from_source": null, "delete_requested_at": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-05-29T18:30:58.000000Z", "updated_at": "2026-06-09T05:35:38.000000Z", "deleted_by": null, "interests": null, "address": { "iso": "AUS", "region_code": "VIC", "coordinates": { "latitude": "-37.814000", "longitude": "144.963200" }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "Melbourne", "postcode": "3000", "region": "VIC", "country": "AU", "latitude": "-37.814000", "longitude": "144.963200" } }, "nice": { "rrn": "rrn:local:20101:user:xxxxxxxxxxxxxxxxxxxxxxxx", "address": "1 Example Street\nMelbourne\nVictoria\nAustralia\n3000", "address_oneline": "1 Example Street, Melbourne, Victoria, Australia, 3000", "address.country": "Australia", "address.country:raw": "AUS", "address.city": "Melbourne", "address.region": "Victoria", "address.region:raw": "VIC", "address.postcode": "3000", "address.street_address_1": "1 Example Street", "address.street_address_2": null, "address.street_address_3": null, "address.latitude": "-37.814000", "address.longitude": "144.963200", "family_id": null, "has_family_members": "No", "manages_family": false, "family_manager": "No", "family_member": "No", "is_family_member": false, "is_engaged": "No", "is_engaged:raw": false, "last_engaged_at": null, "last_engaged_at:raw": null, "created_at": "May 29, 2026, 6:30 PM", "created_at__date": "May 29, 2026", "created_at__time": "6:30 PM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Friday", "email_verified": "No", "from_source": "", "interests": null, "interests:value": null, "interests:array": null, "is_subscribed_transactional": "Yes", "is_team_leader": "No", "middle_name": "", "picture_status": "N/A", "picture_status:value": 0, "picture_status:array": "N/A", "shift_privacy": "Yes", "updated_at": "Jun 9, 2026, 5:35 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:35 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "first_name": "Alex", "last_name": "Taylor", "preferred_name": "", "phone:qr_code_value": "au-390000000", "phone": "(+61) 390000000", "phone:raw": "+61390000000", "phone:local_au": "0390000000", "dob": "Apr 12, 1990", "dob__dayofweek": "Thursday", "is_subscribed": "No", "terms": "Yes", "name": "Alex Taylor", "age": 36, "age_months": "36 years, 4 months", "info": "Alex Taylor (alex.taylor@example.com)", "preferred_first_name": "Alex", "delete_requested": false, "updated_hours": 1673.4862143775, "is_community_user": false, "timezone": "UTC" }, "permissions": { "read": true, "update": true, "delete": true }, "id": 23453479, "name": "Alex Taylor" } }, "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Certificate Module" ] }, "parameters": [ { "in": "path", "name": "certificate_id", "description": "The ID of the certificate.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } }, { "in": "path", "name": "id", "description": "The ID of the certificate holder record.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/certificate/user": { "get": { "summary": "List certificate holders", "operationId": "listAllCertificateHolders", "description": "Returns the users a certificate has been issued to, one row per issue. With a\ncertificate ID in the path, the list is that certificate's holders; on the path\nwithout one, it spans every certificate in the account.\n\nOnly holders the caller is allowed to see are returned, so the list can be shorter\nthan the number of certificates issued.\n\nRows carry no related records unless asked for. Request `user` with `with` for the\nholder's profile, or `certificate` for the certificate's name, which is what the\naccount-wide list usually calls for. Reading a single holder always includes the\nuser, so this is only a concern for lists.", "parameters": [ { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "certificate_id": { "type": "integer", "examples": [ 1 ] }, "user_id": { "type": "integer", "examples": [ 23453479 ] }, "label": { "type": [ "string", "null" ], "examples": [ null ] }, "meta": { "type": "object", "properties": { "entities": { "type": "object", "properties": { "user": { "type": "integer", "examples": [ 23453479 ] }, "event": { "type": "integer", "examples": [ 1 ] }, "event_user": { "type": "integer", "examples": [ 1 ] }, "role_offer": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift": { "type": [ "string", "null" ], "examples": [ null ] }, "role_offer_user": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_user": { "type": [ "string", "null" ], "examples": [ null ] } } } } }, "created_at": { "type": "string", "examples": [ "2026-10-20T00:11:41.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-10-20T00:11:41.000000Z" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } }, "examples": [ [ { "object": { "id": 1, "certificate_id": 1, "user_id": 23453479, "label": null, "meta": { "entities": { "user": 23453479, "event": 1, "event_user": 1, "role_offer": null, "event_shift": null, "role_offer_user": null, "event_shift_user": null } }, "created_at": "2026-10-20T00:11:41.000000Z", "updated_at": "2026-10-20T00:11:41.000000Z" }, "nice": [], "relations": [], "permissions": { "read": true, "update": true, "delete": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/certificate/user?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/certificate/user?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/certificate/user" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 1, "certificate_id": 1, "user_id": 23453479, "label": null, "meta": { "entities": { "user": 23453479, "event": 1, "event_user": 1, "role_offer": null, "event_shift": null, "role_offer_user": null, "event_shift_user": null } }, "created_at": "2026-10-20T00:11:41.000000Z", "updated_at": "2026-10-20T00:11:41.000000Z" }, "nice": [], "relations": [], "permissions": { "read": true, "update": true, "delete": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/certificate/user?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/certificate/user?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/certificate/user", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Certificate Module" ] } }, "/api/v2/training": { "get": { "summary": "List training modules", "operationId": "listTrainingModules", "description": "Returns a paginated list of the training modules the current account can\nuse. That is the account's own modules, plus modules owned by an account\nabove it in the hierarchy that are marked is_inheritable. On each item,\nnice.is_foreign_account says whether the module belongs to another account\nand nice.acts_as_native whether an inherited one behaves as if it were the\ncurrent account's own.", "parameters": [ { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "query", "name": "extras", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "required": false, "schema": { "type": "array", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "items": { "type": "string", "enum": [ "certificate_stats" ] }, "examples": [ [ "certificate_stats" ] ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Paper Goods Machine Operator_EBMsffvoa9Ht" ] }, "short_description": { "type": [ "string", "null" ], "examples": [ null ] }, "thumbnail_url": { "type": [ "string", "null" ], "examples": [ null ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:31.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:31.000000Z" ] }, "success_message": { "type": "string", "examples": [ "Quia quo est et consequatur qui quis quibusdam." ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "is_elective": { "type": "integer", "examples": [ 0 ] }, "estimated_complete_time": { "type": "integer", "examples": [ 11 ] }, "ttl": { "type": "integer", "examples": [ 0 ] }, "pass_score": { "type": "integer", "examples": [ 0 ] }, "is_library": { "type": "integer", "examples": [ 0 ] }, "publish": { "type": "integer", "examples": [ 1 ] }, "service": { "type": "string", "examples": [ "online" ] }, "external_id": { "type": [ "string", "null" ], "examples": [ null ] }, "meta": { "type": "array", "examples": [ [] ] }, "token": { "type": "string", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "certificate_id": { "type": [ "string", "null" ], "examples": [ null ] }, "form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "type_id": { "type": [ "string", "null" ], "examples": [ null ] }, "is_inheritable": { "type": "integer", "examples": [ 0 ] } } }, "nice": { "type": "object", "properties": { "publish": { "type": "string", "examples": [ "Yes" ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "account_url": { "type": "string", "examples": [ "https://sub.rosterfy2.localhost.com/" ] }, "external": { "type": "boolean", "examples": [ false ] }, "has_certificate": { "type": "boolean", "examples": [ false ] }, "account_name_path": { "type": "string", "examples": [ "Rosterfy Subaccount" ] }, "is_foreign_account": { "type": "boolean", "examples": [ false ] }, "acts_as_native": { "type": "boolean", "examples": [ false ] }, "number_of_steps": { "type": "integer", "examples": [ 3 ] }, "number_of_questions": { "type": "integer", "examples": [ 0 ] } } }, "relations": { "type": "object", "properties": { "account": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 20101 ] }, "parent_id": { "type": "integer", "examples": [ 1 ] }, "account_type_id": { "type": "integer", "examples": [ 3 ] }, "path": { "type": "string", "examples": [ "1/20101" ] }, "name": { "type": "string", "examples": [ "Rosterfy Subaccount" ] }, "config": { "type": "object", "properties": { "active_settings": { "type": "array", "items": { "type": "string" }, "examples": [ [ "general:available_locales", "general:locale", "general:timezone", "general:country", "general:distance_unit", "general:approved_countries", "general:start_day_of_week", "general:location", "users:photo_width", "users:photo_height", "users:login", "users:login_session_length", "users:login_social", "users:login_recaptcha", "users:register", "users:require_dob", "users:minimum_age", "users:minimum_age_by_date", "users:allow_availability_form_field", "event:advanced_scheduling", "event:shift_max_time", "event:gap_between_shifts", "event:min_shift_length", "event:max_shift_length", "event:min_shift_apps_per_user", "event:max_shift_apps_per_user", "event:shift_status_default", "event:shift_confirmed_status_default", "event:shift_rejected_status_default", "event:shift_can_withdraw_default", "event:shift_can_withdraw_limit", "event:shift_can_confirm_limit", "event:shift_checked_in_status_default", "event:shift_application_form_id_default", "event:shift_checkin_form_id_default", "event:shift_attended_form_id_default", "event:shift_checkout_form_id_default", "event:shift_feedback_form_id_default", "event:self_checkin", "event:self_checkin_open", "event:self_checkin_close", "event:self_checkout_close", "event:checkin_visible_attributes", "event:shift_show_demand", "training:id", "email:from_name", "email:reply_to", "email:forgot_password_template_id", "email:email_verification_template_id", "email:user_lockout_template_id", "email:user_invitation_email_template_id", "email:contact_us_email_template_id", "email:admin_invitation_email_template_id", "email:banner", "branding:name", "branding:subtitle", "branding:address", "branding:logo", "branding:logo_mono", "branding:background_image", "branding:banner_image", "branding:favicon", "branding:primary_color", "branding:secondary_color", "branding:custom_css", "advanced:default_dashboard", "portal:visible_stats" ] ] } } }, "meta": { "type": "array", "examples": [ [] ] }, "visibility_rules": { "type": "array", "examples": [ [] ] }, "status": { "type": "string", "examples": [ "approved" ] }, "status_reason": { "type": [ "string", "null" ], "examples": [ null ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "start_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "end_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "notes": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_firstname": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_lastname": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_email": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_phone": { "type": [ "string", "null" ], "examples": [ null ] }, "support_manager_email": { "type": "string", "examples": [ "support_manager@rosterfy.com" ] }, "allow_deletion_request": { "type": "integer", "examples": [ 1 ] }, "organization_type": { "type": [ "string", "null" ], "examples": [ null ] }, "contract_start_date": { "type": "string", "examples": [ "2026-06-09" ] }, "contract_end_date": { "type": "string", "examples": [ "2027-06-09" ] }, "billing_contact_email": { "type": "string", "examples": [ "billing_contact@rosterfy.com" ] }, "billing_support_email": { "type": "string", "examples": [ "billing_support@rosterfy.com" ] }, "is_enabled": { "type": "integer", "examples": [ 1 ] }, "additional_billing_support_email": { "type": "string", "examples": [ "additional_billing_contact@rosterfy.com" ] }, "delete_requested_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "trial_ends_at": { "type": [ "string", "null" ], "examples": [ null ] }, "can_erase": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:33:32.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T07:08:01.000000Z" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:1:account:20101" ] }, "address": { "type": "string", "examples": [ "No Address" ] }, "address_oneline": { "type": "string", "examples": [ "No Address" ] }, "account_type_id": { "type": "string", "examples": [ "Enterprise" ] }, "account_type_id:value": { "type": "integer", "examples": [ 3 ] }, "account_type_id:array": { "type": "string", "examples": [ "Enterprise" ] }, "allow_deletion_request": { "type": "string", "examples": [ "Yes" ] }, "contact_firstname": { "type": "string", "examples": [ "" ] }, "contact_lastname": { "type": "string", "examples": [ "" ] }, "contact_phone:qr_code_value": { "type": "string", "examples": [ "" ] }, "contact_phone": { "type": "string", "examples": [ "" ] }, "contact_phone:raw": { "type": "string", "examples": [ "" ] }, "contract_end_date": { "type": "string", "examples": [ "Jun 9, 2027" ] }, "contract_end_date__dayofweek": { "type": "string", "examples": [ "Wednesday" ] }, "contract_start_date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "contract_start_date__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "name": { "type": "string", "examples": [ "Rosterfy Subaccount" ] }, "notes": { "type": "string", "examples": [ "" ] }, "organization_type": { "type": [ "string", "null" ], "examples": [ null ] }, "organization_type:value": { "type": [ "string", "null" ], "examples": [ null ] }, "organization_type:array": { "type": [ "string", "null" ], "examples": [ null ] }, "status": { "type": "string", "examples": [ "Approved" ] }, "status:value": { "type": "string", "examples": [ "approved" ] }, "status:array": { "type": "string", "examples": [ "approved" ] }, "status_reason": { "type": "string", "examples": [ "" ] }, "created_at": { "type": "string", "examples": [ "2026-06-09 05:33:32" ] }, "url": { "type": "string", "examples": [ "https://sub.rosterfy2.localhost.com/" ] }, "branding_name": { "type": "string", "examples": [ "Rosterfy" ] }, "branding_subtitle": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo_mono": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo_stacked": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_banner": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_description": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_primary_color": { "type": "string", "examples": [ "#3131c7" ] }, "branding_complimentary_color": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_secondary_color": { "type": "string", "examples": [ "#38b6ff" ] }, "register": { "type": "boolean", "examples": [ false ] }, "organisation_contact": { "type": "string", "examples": [ " " ] }, "has_subaccount_approved_email_template": { "type": "boolean", "examples": [ false ] }, "has_subaccount_rejected_email_template": { "type": "boolean", "examples": [ false ] }, "parent_account_name": { "type": "string", "examples": [ "Rosterfy2" ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ false ] }, "delete": { "type": "boolean", "examples": [ false ] } } } } }, "certificate": { "type": [ "string", "null" ], "examples": [ null ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } }, "examples": [ [ { "object": { "id": 1, "name": "Paper Goods Machine Operator_EBMsffvoa9Ht", "short_description": null, "thumbnail_url": null, "account_id": 20101, "deleted_at": null, "created_at": "2026-06-09T05:36:31.000000Z", "updated_at": "2026-06-09T05:36:31.000000Z", "success_message": "Quia quo est et consequatur qui quis quibusdam.", "is_archived": 0, "is_elective": 0, "estimated_complete_time": 11, "ttl": 0, "pass_score": 0, "is_library": 0, "publish": 1, "service": "online", "external_id": null, "meta": [], "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "sort_order": 0, "certificate_id": null, "form_id": null, "type_id": null, "is_inheritable": 0 }, "nice": { "publish": "Yes", "account_id": 20101, "account_url": "https://sub.rosterfy2.localhost.com/", "external": false, "has_certificate": false, "account_name_path": "Rosterfy Subaccount", "is_foreign_account": false, "acts_as_native": false, "number_of_steps": 3, "number_of_questions": 0 }, "relations": { "account": { "object": { "id": 20101, "parent_id": 1, "account_type_id": 3, "path": "1/20101", "name": "Rosterfy Subaccount", "config": { "active_settings": [ "general:available_locales", "general:locale", "general:timezone", "general:country", "general:distance_unit", "general:approved_countries", "general:start_day_of_week", "general:location", "users:photo_width", "users:photo_height", "users:login", "users:login_session_length", "users:login_social", "users:login_recaptcha", "users:register", "users:require_dob", "users:minimum_age", "users:minimum_age_by_date", "users:allow_availability_form_field", "event:advanced_scheduling", "event:shift_max_time", "event:gap_between_shifts", "event:min_shift_length", "event:max_shift_length", "event:min_shift_apps_per_user", "event:max_shift_apps_per_user", "event:shift_status_default", "event:shift_confirmed_status_default", "event:shift_rejected_status_default", "event:shift_can_withdraw_default", "event:shift_can_withdraw_limit", "event:shift_can_confirm_limit", "event:shift_checked_in_status_default", "event:shift_application_form_id_default", "event:shift_checkin_form_id_default", "event:shift_attended_form_id_default", "event:shift_checkout_form_id_default", "event:shift_feedback_form_id_default", "event:self_checkin", "event:self_checkin_open", "event:self_checkin_close", "event:self_checkout_close", "event:checkin_visible_attributes", "event:shift_show_demand", "training:id", "email:from_name", "email:reply_to", "email:forgot_password_template_id", "email:email_verification_template_id", "email:user_lockout_template_id", "email:user_invitation_email_template_id", "email:contact_us_email_template_id", "email:admin_invitation_email_template_id", "email:banner", "branding:name", "branding:subtitle", "branding:address", "branding:logo", "branding:logo_mono", "branding:background_image", "branding:banner_image", "branding:favicon", "branding:primary_color", "branding:secondary_color", "branding:custom_css", "advanced:default_dashboard", "portal:visible_stats" ] }, "meta": [], "visibility_rules": [], "status": "approved", "status_reason": null, "sort_order": 0, "start_timestamp": null, "end_timestamp": null, "notes": null, "contact_firstname": null, "contact_lastname": null, "contact_email": null, "contact_phone": null, "support_manager_email": "support_manager@rosterfy.com", "allow_deletion_request": 1, "organization_type": null, "contract_start_date": "2026-06-09", "contract_end_date": "2027-06-09", "billing_contact_email": "billing_contact@rosterfy.com", "billing_support_email": "billing_support@rosterfy.com", "is_enabled": 1, "additional_billing_support_email": "additional_billing_contact@rosterfy.com", "delete_requested_at": null, "is_archived": 0, "trial_ends_at": null, "can_erase": 0, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:33:32.000000Z", "updated_at": "2026-06-09T07:08:01.000000Z" }, "nice": { "rrn": "rrn:local:1:account:20101", "address": "No Address", "address_oneline": "No Address", "account_type_id": "Enterprise", "account_type_id:value": 3, "account_type_id:array": "Enterprise", "allow_deletion_request": "Yes", "contact_firstname": "", "contact_lastname": "", "contact_phone:qr_code_value": "", "contact_phone": "", "contact_phone:raw": "", "contract_end_date": "Jun 9, 2027", "contract_end_date__dayofweek": "Wednesday", "contract_start_date": "Jun 9, 2026", "contract_start_date__dayofweek": "Tuesday", "name": "Rosterfy Subaccount", "notes": "", "organization_type": null, "organization_type:value": null, "organization_type:array": null, "status": "Approved", "status:value": "approved", "status:array": "approved", "status_reason": "", "created_at": "2026-06-09 05:33:32", "url": "https://sub.rosterfy2.localhost.com/", "branding_name": "Rosterfy", "branding_subtitle": null, "branding_logo": null, "branding_logo_mono": null, "branding_logo_stacked": null, "branding_banner": null, "branding_description": null, "branding_primary_color": "#3131c7", "branding_complimentary_color": null, "branding_secondary_color": "#38b6ff", "register": false, "organisation_contact": " ", "has_subaccount_approved_email_template": false, "has_subaccount_rejected_email_template": false, "parent_account_name": "Rosterfy2" }, "permissions": { "read": true, "update": false, "delete": false } }, "certificate": null }, "permissions": { "read": true, "update": true, "delete": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/training?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/training?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/training" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 1, "name": "Paper Goods Machine Operator_EBMsffvoa9Ht", "short_description": null, "thumbnail_url": null, "account_id": 20101, "deleted_at": null, "created_at": "2026-06-09T05:36:31.000000Z", "updated_at": "2026-06-09T05:36:31.000000Z", "success_message": "Quia quo est et consequatur qui quis quibusdam.", "is_archived": 0, "is_elective": 0, "estimated_complete_time": 11, "ttl": 0, "pass_score": 0, "is_library": 0, "publish": 1, "service": "online", "external_id": null, "meta": [], "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "sort_order": 0, "certificate_id": null, "form_id": null, "type_id": null, "is_inheritable": 0 }, "nice": { "publish": "Yes", "account_id": 20101, "account_url": "https://sub.rosterfy2.localhost.com/", "external": false, "has_certificate": false, "account_name_path": "Rosterfy Subaccount", "is_foreign_account": false, "acts_as_native": false, "number_of_steps": 3, "number_of_questions": 0 }, "relations": { "account": { "object": { "id": 20101, "parent_id": 1, "account_type_id": 3, "path": "1/20101", "name": "Rosterfy Subaccount", "config": { "active_settings": [ "general:available_locales", "general:locale", "general:timezone", "general:country", "general:distance_unit", "general:approved_countries", "general:start_day_of_week", "general:location", "users:photo_width", "users:photo_height", "users:login", "users:login_session_length", "users:login_social", "users:login_recaptcha", "users:register", "users:require_dob", "users:minimum_age", "users:minimum_age_by_date", "users:allow_availability_form_field", "event:advanced_scheduling", "event:shift_max_time", "event:gap_between_shifts", "event:min_shift_length", "event:max_shift_length", "event:min_shift_apps_per_user", "event:max_shift_apps_per_user", "event:shift_status_default", "event:shift_confirmed_status_default", "event:shift_rejected_status_default", "event:shift_can_withdraw_default", "event:shift_can_withdraw_limit", "event:shift_can_confirm_limit", "event:shift_checked_in_status_default", "event:shift_application_form_id_default", "event:shift_checkin_form_id_default", "event:shift_attended_form_id_default", "event:shift_checkout_form_id_default", "event:shift_feedback_form_id_default", "event:self_checkin", "event:self_checkin_open", "event:self_checkin_close", "event:self_checkout_close", "event:checkin_visible_attributes", "event:shift_show_demand", "training:id", "email:from_name", "email:reply_to", "email:forgot_password_template_id", "email:email_verification_template_id", "email:user_lockout_template_id", "email:user_invitation_email_template_id", "email:contact_us_email_template_id", "email:admin_invitation_email_template_id", "email:banner", "branding:name", "branding:subtitle", "branding:address", "branding:logo", "branding:logo_mono", "branding:background_image", "branding:banner_image", "branding:favicon", "branding:primary_color", "branding:secondary_color", "branding:custom_css", "advanced:default_dashboard", "portal:visible_stats" ] }, "meta": [], "visibility_rules": [], "status": "approved", "status_reason": null, "sort_order": 0, "start_timestamp": null, "end_timestamp": null, "notes": null, "contact_firstname": null, "contact_lastname": null, "contact_email": null, "contact_phone": null, "support_manager_email": "support_manager@rosterfy.com", "allow_deletion_request": 1, "organization_type": null, "contract_start_date": "2026-06-09", "contract_end_date": "2027-06-09", "billing_contact_email": "billing_contact@rosterfy.com", "billing_support_email": "billing_support@rosterfy.com", "is_enabled": 1, "additional_billing_support_email": "additional_billing_contact@rosterfy.com", "delete_requested_at": null, "is_archived": 0, "trial_ends_at": null, "can_erase": 0, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:33:32.000000Z", "updated_at": "2026-06-09T07:08:01.000000Z" }, "nice": { "rrn": "rrn:local:1:account:20101", "address": "No Address", "address_oneline": "No Address", "account_type_id": "Enterprise", "account_type_id:value": 3, "account_type_id:array": "Enterprise", "allow_deletion_request": "Yes", "contact_firstname": "", "contact_lastname": "", "contact_phone:qr_code_value": "", "contact_phone": "", "contact_phone:raw": "", "contract_end_date": "Jun 9, 2027", "contract_end_date__dayofweek": "Wednesday", "contract_start_date": "Jun 9, 2026", "contract_start_date__dayofweek": "Tuesday", "name": "Rosterfy Subaccount", "notes": "", "organization_type": null, "organization_type:value": null, "organization_type:array": null, "status": "Approved", "status:value": "approved", "status:array": "approved", "status_reason": "", "created_at": "2026-06-09 05:33:32", "url": "https://sub.rosterfy2.localhost.com/", "branding_name": "Rosterfy", "branding_subtitle": null, "branding_logo": null, "branding_logo_mono": null, "branding_logo_stacked": null, "branding_banner": null, "branding_description": null, "branding_primary_color": "#3131c7", "branding_complimentary_color": null, "branding_secondary_color": "#38b6ff", "register": false, "organisation_contact": " ", "has_subaccount_approved_email_template": false, "has_subaccount_rejected_email_template": false, "parent_account_name": "Rosterfy2" }, "permissions": { "read": true, "update": false, "delete": false } }, "certificate": null }, "permissions": { "read": true, "update": true, "delete": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/training?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/training?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/training", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Training Module" ] }, "post": { "summary": "Create a training module", "operationId": "createATrainingModule", "description": "Creates a training module in the current account. account_id is always the\ncalling account and cannot be set from the request, and the module's token\nis generated on create. The response is the same shape as reading the\nmodule, so a follow-up read is not needed.\n\nA created module has no steps. Add them through the training step endpoints.\n\nInvalid input returns a 422 identifying the fields at fault. The field notes\nbelow say which rules apply to each.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Paper Goods Machine Operator_EBMsffvoa9Ht" ] }, "short_description": { "type": [ "string", "null" ], "examples": [ null ] }, "thumbnail_url": { "type": [ "string", "null" ], "examples": [ null ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:31.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:31.000000Z" ] }, "success_message": { "type": "string", "examples": [ "Quia quo est et consequatur qui quis quibusdam." ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "is_elective": { "type": "integer", "examples": [ 0 ] }, "estimated_complete_time": { "type": "integer", "examples": [ 11 ] }, "ttl": { "type": "integer", "examples": [ 0 ] }, "pass_score": { "type": "integer", "examples": [ 0 ] }, "is_library": { "type": "integer", "examples": [ 0 ] }, "publish": { "type": "integer", "examples": [ 1 ] }, "service": { "type": "string", "examples": [ "online" ] }, "external_id": { "type": [ "string", "null" ], "examples": [ null ] }, "meta": { "type": "array", "examples": [ [] ] }, "token": { "type": "string", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "certificate_id": { "type": [ "string", "null" ], "examples": [ null ] }, "form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "type_id": { "type": [ "string", "null" ], "examples": [ null ] }, "is_inheritable": { "type": "integer", "examples": [ 0 ] } } }, "nice": { "type": "object", "properties": { "publish": { "type": "string", "examples": [ "Yes" ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "account_url": { "type": "string", "examples": [ "https://sub.rosterfy2.localhost.com/" ] }, "external": { "type": "boolean", "examples": [ false ] }, "has_certificate": { "type": "boolean", "examples": [ false ] }, "account_name_path": { "type": "string", "examples": [ "Rosterfy Subaccount" ] }, "is_foreign_account": { "type": "boolean", "examples": [ false ] }, "acts_as_native": { "type": "boolean", "examples": [ false ] }, "number_of_steps": { "type": "integer", "examples": [ 3 ] }, "number_of_questions": { "type": "integer", "examples": [ 0 ] } } }, "relations": { "type": "object", "properties": { "account": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 20101 ] }, "parent_id": { "type": "integer", "examples": [ 1 ] }, "account_type_id": { "type": "integer", "examples": [ 3 ] }, "path": { "type": "string", "examples": [ "1/20101" ] }, "name": { "type": "string", "examples": [ "Rosterfy Subaccount" ] }, "config": { "type": "object", "properties": { "active_settings": { "type": "array", "items": { "type": "string" }, "examples": [ [ "general:available_locales", "general:locale", "general:timezone", "general:country", "general:distance_unit", "general:approved_countries", "general:start_day_of_week", "general:location", "users:photo_width", "users:photo_height", "users:login", "users:login_session_length", "users:login_social", "users:login_recaptcha", "users:register", "users:require_dob", "users:minimum_age", "users:minimum_age_by_date", "users:allow_availability_form_field", "event:advanced_scheduling", "event:shift_max_time", "event:gap_between_shifts", "event:min_shift_length", "event:max_shift_length", "event:min_shift_apps_per_user", "event:max_shift_apps_per_user", "event:shift_status_default", "event:shift_confirmed_status_default", "event:shift_rejected_status_default", "event:shift_can_withdraw_default", "event:shift_can_withdraw_limit", "event:shift_can_confirm_limit", "event:shift_checked_in_status_default", "event:shift_application_form_id_default", "event:shift_checkin_form_id_default", "event:shift_attended_form_id_default", "event:shift_checkout_form_id_default", "event:shift_feedback_form_id_default", "event:self_checkin", "event:self_checkin_open", "event:self_checkin_close", "event:self_checkout_close", "event:checkin_visible_attributes", "event:shift_show_demand", "training:id", "email:from_name", "email:reply_to", "email:forgot_password_template_id", "email:email_verification_template_id", "email:user_lockout_template_id", "email:user_invitation_email_template_id", "email:contact_us_email_template_id", "email:admin_invitation_email_template_id", "email:banner", "branding:name", "branding:subtitle", "branding:address", "branding:logo", "branding:logo_mono", "branding:background_image", "branding:banner_image", "branding:favicon", "branding:primary_color", "branding:secondary_color", "branding:custom_css", "advanced:default_dashboard", "portal:visible_stats" ] ] } } }, "meta": { "type": "array", "examples": [ [] ] }, "visibility_rules": { "type": "array", "examples": [ [] ] }, "status": { "type": "string", "examples": [ "approved" ] }, "status_reason": { "type": [ "string", "null" ], "examples": [ null ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "start_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "end_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "notes": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_firstname": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_lastname": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_email": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_phone": { "type": [ "string", "null" ], "examples": [ null ] }, "support_manager_email": { "type": "string", "examples": [ "support_manager@rosterfy.com" ] }, "allow_deletion_request": { "type": "integer", "examples": [ 1 ] }, "organization_type": { "type": [ "string", "null" ], "examples": [ null ] }, "contract_start_date": { "type": "string", "examples": [ "2026-06-09" ] }, "contract_end_date": { "type": "string", "examples": [ "2027-06-09" ] }, "billing_contact_email": { "type": "string", "examples": [ "billing_contact@rosterfy.com" ] }, "billing_support_email": { "type": "string", "examples": [ "billing_support@rosterfy.com" ] }, "is_enabled": { "type": "integer", "examples": [ 1 ] }, "additional_billing_support_email": { "type": "string", "examples": [ "additional_billing_contact@rosterfy.com" ] }, "delete_requested_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "trial_ends_at": { "type": [ "string", "null" ], "examples": [ null ] }, "can_erase": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:33:32.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T07:08:01.000000Z" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:1:account:20101" ] }, "address": { "type": "string", "examples": [ "No Address" ] }, "address_oneline": { "type": "string", "examples": [ "No Address" ] }, "account_type_id": { "type": "string", "examples": [ "Enterprise" ] }, "account_type_id:value": { "type": "integer", "examples": [ 3 ] }, "account_type_id:array": { "type": "string", "examples": [ "Enterprise" ] }, "allow_deletion_request": { "type": "string", "examples": [ "Yes" ] }, "contact_firstname": { "type": "string", "examples": [ "" ] }, "contact_lastname": { "type": "string", "examples": [ "" ] }, "contact_phone:qr_code_value": { "type": "string", "examples": [ "" ] }, "contact_phone": { "type": "string", "examples": [ "" ] }, "contact_phone:raw": { "type": "string", "examples": [ "" ] }, "contract_end_date": { "type": "string", "examples": [ "Jun 9, 2027" ] }, "contract_end_date__dayofweek": { "type": "string", "examples": [ "Wednesday" ] }, "contract_start_date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "contract_start_date__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "name": { "type": "string", "examples": [ "Rosterfy Subaccount" ] }, "notes": { "type": "string", "examples": [ "" ] }, "organization_type": { "type": [ "string", "null" ], "examples": [ null ] }, "organization_type:value": { "type": [ "string", "null" ], "examples": [ null ] }, "organization_type:array": { "type": [ "string", "null" ], "examples": [ null ] }, "status": { "type": "string", "examples": [ "Approved" ] }, "status:value": { "type": "string", "examples": [ "approved" ] }, "status:array": { "type": "string", "examples": [ "approved" ] }, "status_reason": { "type": "string", "examples": [ "" ] }, "created_at": { "type": "string", "examples": [ "2026-06-09 05:33:32" ] }, "url": { "type": "string", "examples": [ "https://sub.rosterfy2.localhost.com/" ] }, "branding_name": { "type": "string", "examples": [ "Rosterfy" ] }, "branding_subtitle": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo_mono": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo_stacked": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_banner": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_description": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_primary_color": { "type": "string", "examples": [ "#3131c7" ] }, "branding_complimentary_color": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_secondary_color": { "type": "string", "examples": [ "#38b6ff" ] }, "register": { "type": "boolean", "examples": [ false ] }, "organisation_contact": { "type": "string", "examples": [ " " ] }, "has_subaccount_approved_email_template": { "type": "boolean", "examples": [ false ] }, "has_subaccount_rejected_email_template": { "type": "boolean", "examples": [ false ] }, "parent_account_name": { "type": "string", "examples": [ "Rosterfy2" ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ false ] }, "delete": { "type": "boolean", "examples": [ false ] } } } } }, "certificate": { "type": [ "string", "null" ], "examples": [ null ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "name": "Paper Goods Machine Operator_EBMsffvoa9Ht", "short_description": null, "thumbnail_url": null, "account_id": 20101, "deleted_at": null, "created_at": "2026-06-09T05:36:31.000000Z", "updated_at": "2026-06-09T05:36:31.000000Z", "success_message": "Quia quo est et consequatur qui quis quibusdam.", "is_archived": 0, "is_elective": 0, "estimated_complete_time": 11, "ttl": 0, "pass_score": 0, "is_library": 0, "publish": 1, "service": "online", "external_id": null, "meta": [], "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "sort_order": 0, "certificate_id": null, "form_id": null, "type_id": null, "is_inheritable": 0 }, "nice": { "publish": "Yes", "account_id": 20101, "account_url": "https://sub.rosterfy2.localhost.com/", "external": false, "has_certificate": false, "account_name_path": "Rosterfy Subaccount", "is_foreign_account": false, "acts_as_native": false, "number_of_steps": 3, "number_of_questions": 0 }, "relations": { "account": { "object": { "id": 20101, "parent_id": 1, "account_type_id": 3, "path": "1/20101", "name": "Rosterfy Subaccount", "config": { "active_settings": [ "general:available_locales", "general:locale", "general:timezone", "general:country", "general:distance_unit", "general:approved_countries", "general:start_day_of_week", "general:location", "users:photo_width", "users:photo_height", "users:login", "users:login_session_length", "users:login_social", "users:login_recaptcha", "users:register", "users:require_dob", "users:minimum_age", "users:minimum_age_by_date", "users:allow_availability_form_field", "event:advanced_scheduling", "event:shift_max_time", "event:gap_between_shifts", "event:min_shift_length", "event:max_shift_length", "event:min_shift_apps_per_user", "event:max_shift_apps_per_user", "event:shift_status_default", "event:shift_confirmed_status_default", "event:shift_rejected_status_default", "event:shift_can_withdraw_default", "event:shift_can_withdraw_limit", "event:shift_can_confirm_limit", "event:shift_checked_in_status_default", "event:shift_application_form_id_default", "event:shift_checkin_form_id_default", "event:shift_attended_form_id_default", "event:shift_checkout_form_id_default", "event:shift_feedback_form_id_default", "event:self_checkin", "event:self_checkin_open", "event:self_checkin_close", "event:self_checkout_close", "event:checkin_visible_attributes", "event:shift_show_demand", "training:id", "email:from_name", "email:reply_to", "email:forgot_password_template_id", "email:email_verification_template_id", "email:user_lockout_template_id", "email:user_invitation_email_template_id", "email:contact_us_email_template_id", "email:admin_invitation_email_template_id", "email:banner", "branding:name", "branding:subtitle", "branding:address", "branding:logo", "branding:logo_mono", "branding:background_image", "branding:banner_image", "branding:favicon", "branding:primary_color", "branding:secondary_color", "branding:custom_css", "advanced:default_dashboard", "portal:visible_stats" ] }, "meta": [], "visibility_rules": [], "status": "approved", "status_reason": null, "sort_order": 0, "start_timestamp": null, "end_timestamp": null, "notes": null, "contact_firstname": null, "contact_lastname": null, "contact_email": null, "contact_phone": null, "support_manager_email": "support_manager@rosterfy.com", "allow_deletion_request": 1, "organization_type": null, "contract_start_date": "2026-06-09", "contract_end_date": "2027-06-09", "billing_contact_email": "billing_contact@rosterfy.com", "billing_support_email": "billing_support@rosterfy.com", "is_enabled": 1, "additional_billing_support_email": "additional_billing_contact@rosterfy.com", "delete_requested_at": null, "is_archived": 0, "trial_ends_at": null, "can_erase": 0, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:33:32.000000Z", "updated_at": "2026-06-09T07:08:01.000000Z" }, "nice": { "rrn": "rrn:local:1:account:20101", "address": "No Address", "address_oneline": "No Address", "account_type_id": "Enterprise", "account_type_id:value": 3, "account_type_id:array": "Enterprise", "allow_deletion_request": "Yes", "contact_firstname": "", "contact_lastname": "", "contact_phone:qr_code_value": "", "contact_phone": "", "contact_phone:raw": "", "contract_end_date": "Jun 9, 2027", "contract_end_date__dayofweek": "Wednesday", "contract_start_date": "Jun 9, 2026", "contract_start_date__dayofweek": "Tuesday", "name": "Rosterfy Subaccount", "notes": "", "organization_type": null, "organization_type:value": null, "organization_type:array": null, "status": "Approved", "status:value": "approved", "status:array": "approved", "status_reason": "", "created_at": "2026-06-09 05:33:32", "url": "https://sub.rosterfy2.localhost.com/", "branding_name": "Rosterfy", "branding_subtitle": null, "branding_logo": null, "branding_logo_mono": null, "branding_logo_stacked": null, "branding_banner": null, "branding_description": null, "branding_primary_color": "#3131c7", "branding_complimentary_color": null, "branding_secondary_color": "#38b6ff", "register": false, "organisation_contact": " ", "has_subaccount_approved_email_template": false, "has_subaccount_rejected_email_template": false, "parent_account_name": "Rosterfy2" }, "permissions": { "read": true, "update": false, "delete": false } }, "certificate": null }, "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Training Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "success_message": { "type": "string", "description": "The end of course message, shown when a user finishes the module. HTML, maximum 64,000 characters.", "examples": [ "Quia quo est et consequatur qui quis quibusdam." ] }, "name": { "type": "string", "description": "The name of the module. Maximum 255 characters. Translatable: send a plain string to set it for the request locale, or an object keyed by locale such as {\"en-US\": \"Induction\"}.", "examples": [ "Paper Goods Machine Operator_EBMsffvoa9Ht" ] }, "estimated_complete_time": { "type": "integer", "description": "How long the module is expected to take, in minutes.", "examples": [ 11 ] }, "publish": { "type": "boolean", "description": "Whether the module is published. Until it is, the module is not visible in the portal.", "examples": [ 1 ] }, "is_archived": { "type": "boolean", "description": "Whether the module is archived. The mass-archive endpoint sets this field in bulk.", "examples": [ 0 ] }, "is_elective": { "type": "boolean", "description": "Whether any user who can access training may complete this module.", "examples": [ 0 ] }, "is_inheritable": { "type": "boolean", "description": "Whether accounts below the owning account may use this module. Reflected in the response as nice.acts_as_native.", "examples": [ 0 ] }, "type_id": { "type": "integer", "description": "The ID of the training type to categorise this module under. Used for reporting and filtering, and optional.", "examples": [ 1 ] }, "service": { "type": "string", "description": "The training provider. One of online, scorm, scorm_upload or bespoke for modules Rosterfy hosts, or the code of an external provider. A module whose service is not one of the four local values reads as external, and the update endpoint ignores this field for those modules.", "examples": [ "online" ] }, "external_id": { "type": "string", "description": "The ID of the module in the external training provider. Recorded when the module is synced from that provider, and sent back to it on assignment and completion.", "examples": [ null ] }, "meta": { "type": "object", "description": "Provider and behaviour options for the module. The documented subkeys follow. On create this object is stored as sent; on update it is merged into the stored object, so omitted subkeys keep their current values.", "properties": { "onetime": { "type": "boolean", "description": "Whether a user is blocked from repeating the module if they do not pass on the first attempt.", "examples": [ true ] }, "score": { "type": "boolean", "description": "Whether a score is recorded. The user always moves to the next step when there is a question, and the total correct answers make up the score.", "examples": [ true ] }, "inform_answer": { "type": "boolean", "description": "Whether the user is told if their answer was correct.", "examples": [ true ] }, "show_correct": { "type": "boolean", "description": "Whether the user is shown the correct answers.", "examples": [ true ] }, "inform_score": { "type": "boolean", "description": "Whether the user is shown the percentage required to pass and their own score at the end.", "examples": [ true ] }, "template_id": { "type": "integer", "description": "The ID of the email template to send when a user finishes the module.", "examples": [ 1 ] }, "code": { "type": "string", "description": "The course code the module has in the external provider. Set when the module is synced from that provider.", "examples": [ null ] }, "original_id": { "type": "string", "description": "The original module ID in the external provider. Set when the module is synced from that provider.", "examples": [ null ] }, "source": { "type": "string", "description": "The name of the external provider the module was synced from.", "examples": [ null ] }, "height": { "type": "integer", "description": "The height of the SCORM frame in the portal, in pixels. Must be under 5000. Defaults to 600.", "examples": [ 1 ] }, "suspend": { "type": "boolean", "description": "Whether the user is forced to restart the SCORM module if they return after starting it.", "examples": [ true ] }, "redirect_url": { "type": "string", "description": "The URL the user is redirected to from the portal to take the training. Required when service is bespoke.", "examples": [ null ] }, "entrypoint": { "type": "string", "description": "The file the SCORM package starts at, usually index.html or story.html. Required when service is scorm or scorm_upload.", "examples": [ null ] }, "complete": { "type": "string", "description": "The status the SCORM file emits to tell Rosterfy the training is complete, usually complete or passed. Your SCORM provider will tell you this status. Required when service is scorm or scorm_upload.", "examples": [ null ] } }, "examples": [ [] ] }, "ttl": { "type": "integer", "description": "How long a completion stays valid, in seconds. A user is required to retake the module once it lapses, and re-completing resets the expiry. Only applied when greater than 0, and forced to 0 when can_expire is sent as false.", "examples": [ 0 ] }, "is_library": { "type": "boolean", "description": "Stored, but read by nothing in the platform.", "examples": [ 0 ] }, "form_id": { "type": "integer", "description": "The ID of the form a user completes before starting the module without a Rosterfy account. Setting it is also what makes the module readable unauthenticated - see the read endpoint. Cleared when anonymous_enable is sent as false.", "examples": [ 1 ] }, "certificate_id": { "type": "integer", "description": "The ID of the certificate to award when the module is completed successfully.", "examples": [ 1 ] }, "pass_score": { "type": "integer", "description": "The percentage a user must reach to be marked as passed, from 0 to 100. Applies when meta.score is true.", "examples": [ 0 ] }, "sort_order": { "type": "integer", "description": "The position of the module where listings are ordered by sort order.", "examples": [ 0 ] }, "scorm_upload": { "type": "string", "description": "URL of an uploaded SCORM zip, up to 100MB, which Rosterfy unzips and stores. Only acted on by the update endpoint; on create the field is accepted and ignored.", "examples": [ null ] }, "short_description": { "type": "string", "description": "A short summary of the module. Not validated by the server; anything the column accepts is stored.", "examples": [ null ] }, "thumbnail_url": { "type": "string", "description": "URL of, or an upload for, the module thumbnail. Recommended 245x150 pixels. Not validated by the server.", "examples": [ null ] }, "can_expire": { "type": "boolean", "description": "Whether completions of this module expire. Not stored; sending it as false is what sets ttl to 0.", "examples": [ true ] }, "anonymous_enable": { "type": "boolean", "description": "Whether the module may be completed by someone without a Rosterfy account. Not stored; sending it as false is what clears form_id and meta.template_id.", "examples": [ true ] } }, "required": [ "success_message", "name" ] } } } } } }, "/api/v2/training/{id}": { "get": { "summary": "Read a training module", "operationId": "readATrainingModule", "description": "Returns a single training module.\n\nThis is the one training endpoint that does not require authentication, so\nthat a module set up for anonymous submissions can be read from a public\nlink. What an unauthenticated caller gets back depends on the module: the\nfull body if it has a form_id, because a module with a form attached counts\nas public, and an empty object otherwise. An authenticated caller who may\nnot read the module also gets an empty object.\n\nThe permissions block is only present for an authenticated caller.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Paper Goods Machine Operator_EBMsffvoa9Ht" ] }, "short_description": { "type": [ "string", "null" ], "examples": [ null ] }, "thumbnail_url": { "type": [ "string", "null" ], "examples": [ null ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:31.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:31.000000Z" ] }, "success_message": { "type": "string", "examples": [ "Quia quo est et consequatur qui quis quibusdam." ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "is_elective": { "type": "integer", "examples": [ 0 ] }, "estimated_complete_time": { "type": "integer", "examples": [ 11 ] }, "ttl": { "type": "integer", "examples": [ 0 ] }, "pass_score": { "type": "integer", "examples": [ 0 ] }, "is_library": { "type": "integer", "examples": [ 0 ] }, "publish": { "type": "integer", "examples": [ 1 ] }, "service": { "type": "string", "examples": [ "online" ] }, "external_id": { "type": [ "string", "null" ], "examples": [ null ] }, "meta": { "type": "array", "examples": [ [] ] }, "token": { "type": "string", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "certificate_id": { "type": [ "string", "null" ], "examples": [ null ] }, "form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "type_id": { "type": [ "string", "null" ], "examples": [ null ] }, "is_inheritable": { "type": "integer", "examples": [ 0 ] } } }, "nice": { "type": "object", "properties": { "publish": { "type": "string", "examples": [ "Yes" ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "account_url": { "type": "string", "examples": [ "https://sub.rosterfy2.localhost.com/" ] }, "external": { "type": "boolean", "examples": [ false ] }, "has_certificate": { "type": "boolean", "examples": [ false ] }, "account_name_path": { "type": "string", "examples": [ "Rosterfy Subaccount" ] }, "is_foreign_account": { "type": "boolean", "examples": [ false ] }, "acts_as_native": { "type": "boolean", "examples": [ false ] }, "number_of_steps": { "type": "integer", "examples": [ 3 ] }, "number_of_questions": { "type": "integer", "examples": [ 0 ] } } }, "relations": { "type": "object", "properties": { "account": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 20101 ] }, "parent_id": { "type": "integer", "examples": [ 1 ] }, "account_type_id": { "type": "integer", "examples": [ 3 ] }, "path": { "type": "string", "examples": [ "1/20101" ] }, "name": { "type": "string", "examples": [ "Rosterfy Subaccount" ] }, "config": { "type": "object", "properties": { "active_settings": { "type": "array", "items": { "type": "string" }, "examples": [ [ "general:available_locales", "general:locale", "general:timezone", "general:country", "general:distance_unit", "general:approved_countries", "general:start_day_of_week", "general:location", "users:photo_width", "users:photo_height", "users:login", "users:login_session_length", "users:login_social", "users:login_recaptcha", "users:register", "users:require_dob", "users:minimum_age", "users:minimum_age_by_date", "users:allow_availability_form_field", "event:advanced_scheduling", "event:shift_max_time", "event:gap_between_shifts", "event:min_shift_length", "event:max_shift_length", "event:min_shift_apps_per_user", "event:max_shift_apps_per_user", "event:shift_status_default", "event:shift_confirmed_status_default", "event:shift_rejected_status_default", "event:shift_can_withdraw_default", "event:shift_can_withdraw_limit", "event:shift_can_confirm_limit", "event:shift_checked_in_status_default", "event:shift_application_form_id_default", "event:shift_checkin_form_id_default", "event:shift_attended_form_id_default", "event:shift_checkout_form_id_default", "event:shift_feedback_form_id_default", "event:self_checkin", "event:self_checkin_open", "event:self_checkin_close", "event:self_checkout_close", "event:checkin_visible_attributes", "event:shift_show_demand", "training:id", "email:from_name", "email:reply_to", "email:forgot_password_template_id", "email:email_verification_template_id", "email:user_lockout_template_id", "email:user_invitation_email_template_id", "email:contact_us_email_template_id", "email:admin_invitation_email_template_id", "email:banner", "branding:name", "branding:subtitle", "branding:address", "branding:logo", "branding:logo_mono", "branding:background_image", "branding:banner_image", "branding:favicon", "branding:primary_color", "branding:secondary_color", "branding:custom_css", "advanced:default_dashboard", "portal:visible_stats" ] ] } } }, "meta": { "type": "array", "examples": [ [] ] }, "visibility_rules": { "type": "array", "examples": [ [] ] }, "status": { "type": "string", "examples": [ "approved" ] }, "status_reason": { "type": [ "string", "null" ], "examples": [ null ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "start_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "end_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "notes": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_firstname": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_lastname": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_email": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_phone": { "type": [ "string", "null" ], "examples": [ null ] }, "support_manager_email": { "type": "string", "examples": [ "support_manager@rosterfy.com" ] }, "allow_deletion_request": { "type": "integer", "examples": [ 1 ] }, "organization_type": { "type": [ "string", "null" ], "examples": [ null ] }, "contract_start_date": { "type": "string", "examples": [ "2026-06-09" ] }, "contract_end_date": { "type": "string", "examples": [ "2027-06-09" ] }, "billing_contact_email": { "type": "string", "examples": [ "billing_contact@rosterfy.com" ] }, "billing_support_email": { "type": "string", "examples": [ "billing_support@rosterfy.com" ] }, "is_enabled": { "type": "integer", "examples": [ 1 ] }, "additional_billing_support_email": { "type": "string", "examples": [ "additional_billing_contact@rosterfy.com" ] }, "delete_requested_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "trial_ends_at": { "type": [ "string", "null" ], "examples": [ null ] }, "can_erase": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:33:32.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T07:08:01.000000Z" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:1:account:20101" ] }, "address": { "type": "string", "examples": [ "No Address" ] }, "address_oneline": { "type": "string", "examples": [ "No Address" ] }, "account_type_id": { "type": "string", "examples": [ "Enterprise" ] }, "account_type_id:value": { "type": "integer", "examples": [ 3 ] }, "account_type_id:array": { "type": "string", "examples": [ "Enterprise" ] }, "allow_deletion_request": { "type": "string", "examples": [ "Yes" ] }, "contact_firstname": { "type": "string", "examples": [ "" ] }, "contact_lastname": { "type": "string", "examples": [ "" ] }, "contact_phone:qr_code_value": { "type": "string", "examples": [ "" ] }, "contact_phone": { "type": "string", "examples": [ "" ] }, "contact_phone:raw": { "type": "string", "examples": [ "" ] }, "contract_end_date": { "type": "string", "examples": [ "Jun 9, 2027" ] }, "contract_end_date__dayofweek": { "type": "string", "examples": [ "Wednesday" ] }, "contract_start_date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "contract_start_date__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "name": { "type": "string", "examples": [ "Rosterfy Subaccount" ] }, "notes": { "type": "string", "examples": [ "" ] }, "organization_type": { "type": [ "string", "null" ], "examples": [ null ] }, "organization_type:value": { "type": [ "string", "null" ], "examples": [ null ] }, "organization_type:array": { "type": [ "string", "null" ], "examples": [ null ] }, "status": { "type": "string", "examples": [ "Approved" ] }, "status:value": { "type": "string", "examples": [ "approved" ] }, "status:array": { "type": "string", "examples": [ "approved" ] }, "status_reason": { "type": "string", "examples": [ "" ] }, "created_at": { "type": "string", "examples": [ "2026-06-09 05:33:32" ] }, "url": { "type": "string", "examples": [ "https://sub.rosterfy2.localhost.com/" ] }, "branding_name": { "type": "string", "examples": [ "Rosterfy" ] }, "branding_subtitle": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo_mono": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo_stacked": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_banner": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_description": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_primary_color": { "type": "string", "examples": [ "#3131c7" ] }, "branding_complimentary_color": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_secondary_color": { "type": "string", "examples": [ "#38b6ff" ] }, "register": { "type": "boolean", "examples": [ false ] }, "organisation_contact": { "type": "string", "examples": [ " " ] }, "has_subaccount_approved_email_template": { "type": "boolean", "examples": [ false ] }, "has_subaccount_rejected_email_template": { "type": "boolean", "examples": [ false ] }, "parent_account_name": { "type": "string", "examples": [ "Rosterfy2" ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ false ] }, "delete": { "type": "boolean", "examples": [ false ] } } } } }, "certificate": { "type": [ "string", "null" ], "examples": [ null ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "name": "Paper Goods Machine Operator_EBMsffvoa9Ht", "short_description": null, "thumbnail_url": null, "account_id": 20101, "deleted_at": null, "created_at": "2026-06-09T05:36:31.000000Z", "updated_at": "2026-06-09T05:36:31.000000Z", "success_message": "Quia quo est et consequatur qui quis quibusdam.", "is_archived": 0, "is_elective": 0, "estimated_complete_time": 11, "ttl": 0, "pass_score": 0, "is_library": 0, "publish": 1, "service": "online", "external_id": null, "meta": [], "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "sort_order": 0, "certificate_id": null, "form_id": null, "type_id": null, "is_inheritable": 0 }, "nice": { "publish": "Yes", "account_id": 20101, "account_url": "https://sub.rosterfy2.localhost.com/", "external": false, "has_certificate": false, "account_name_path": "Rosterfy Subaccount", "is_foreign_account": false, "acts_as_native": false, "number_of_steps": 3, "number_of_questions": 0 }, "relations": { "account": { "object": { "id": 20101, "parent_id": 1, "account_type_id": 3, "path": "1/20101", "name": "Rosterfy Subaccount", "config": { "active_settings": [ "general:available_locales", "general:locale", "general:timezone", "general:country", "general:distance_unit", "general:approved_countries", "general:start_day_of_week", "general:location", "users:photo_width", "users:photo_height", "users:login", "users:login_session_length", "users:login_social", "users:login_recaptcha", "users:register", "users:require_dob", "users:minimum_age", "users:minimum_age_by_date", "users:allow_availability_form_field", "event:advanced_scheduling", "event:shift_max_time", "event:gap_between_shifts", "event:min_shift_length", "event:max_shift_length", "event:min_shift_apps_per_user", "event:max_shift_apps_per_user", "event:shift_status_default", "event:shift_confirmed_status_default", "event:shift_rejected_status_default", "event:shift_can_withdraw_default", "event:shift_can_withdraw_limit", "event:shift_can_confirm_limit", "event:shift_checked_in_status_default", "event:shift_application_form_id_default", "event:shift_checkin_form_id_default", "event:shift_attended_form_id_default", "event:shift_checkout_form_id_default", "event:shift_feedback_form_id_default", "event:self_checkin", "event:self_checkin_open", "event:self_checkin_close", "event:self_checkout_close", "event:checkin_visible_attributes", "event:shift_show_demand", "training:id", "email:from_name", "email:reply_to", "email:forgot_password_template_id", "email:email_verification_template_id", "email:user_lockout_template_id", "email:user_invitation_email_template_id", "email:contact_us_email_template_id", "email:admin_invitation_email_template_id", "email:banner", "branding:name", "branding:subtitle", "branding:address", "branding:logo", "branding:logo_mono", "branding:background_image", "branding:banner_image", "branding:favicon", "branding:primary_color", "branding:secondary_color", "branding:custom_css", "advanced:default_dashboard", "portal:visible_stats" ] }, "meta": [], "visibility_rules": [], "status": "approved", "status_reason": null, "sort_order": 0, "start_timestamp": null, "end_timestamp": null, "notes": null, "contact_firstname": null, "contact_lastname": null, "contact_email": null, "contact_phone": null, "support_manager_email": "support_manager@rosterfy.com", "allow_deletion_request": 1, "organization_type": null, "contract_start_date": "2026-06-09", "contract_end_date": "2027-06-09", "billing_contact_email": "billing_contact@rosterfy.com", "billing_support_email": "billing_support@rosterfy.com", "is_enabled": 1, "additional_billing_support_email": "additional_billing_contact@rosterfy.com", "delete_requested_at": null, "is_archived": 0, "trial_ends_at": null, "can_erase": 0, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:33:32.000000Z", "updated_at": "2026-06-09T07:08:01.000000Z" }, "nice": { "rrn": "rrn:local:1:account:20101", "address": "No Address", "address_oneline": "No Address", "account_type_id": "Enterprise", "account_type_id:value": 3, "account_type_id:array": "Enterprise", "allow_deletion_request": "Yes", "contact_firstname": "", "contact_lastname": "", "contact_phone:qr_code_value": "", "contact_phone": "", "contact_phone:raw": "", "contract_end_date": "Jun 9, 2027", "contract_end_date__dayofweek": "Wednesday", "contract_start_date": "Jun 9, 2026", "contract_start_date__dayofweek": "Tuesday", "name": "Rosterfy Subaccount", "notes": "", "organization_type": null, "organization_type:value": null, "organization_type:array": null, "status": "Approved", "status:value": "approved", "status:array": "approved", "status_reason": "", "created_at": "2026-06-09 05:33:32", "url": "https://sub.rosterfy2.localhost.com/", "branding_name": "Rosterfy", "branding_subtitle": null, "branding_logo": null, "branding_logo_mono": null, "branding_logo_stacked": null, "branding_banner": null, "branding_description": null, "branding_primary_color": "#3131c7", "branding_complimentary_color": null, "branding_secondary_color": "#38b6ff", "register": false, "organisation_contact": " ", "has_subaccount_approved_email_template": false, "has_subaccount_rejected_email_template": false, "parent_account_name": "Rosterfy2" }, "permissions": { "read": true, "update": false, "delete": false } }, "certificate": null }, "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Training Module" ] }, "put": { "summary": "Update a training module", "operationId": "updateATrainingModule", "description": "Updates the fields supplied and leaves the rest untouched, then returns the\nmodule in the same shape as reading it. Every field is optional.\n\nmeta is merged rather than replaced: subkeys already stored keep their values\nunless the request sends them. This is the one field where update behaves\ndifferently to create, which stores the object as sent.\n\nservice is ignored for an external module - one whose service is not one of\nthe four values Rosterfy hosts. The request succeeds and the rest of the\nupdate is applied; only that field is dropped. Sending scorm_upload here\nhands the zip to the unzip process, which runs in the background, so a\nsuccessful response does not mean the package has been unpacked yet.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Paper Goods Machine Operator_EBMsffvoa9Ht" ] }, "short_description": { "type": [ "string", "null" ], "examples": [ null ] }, "thumbnail_url": { "type": [ "string", "null" ], "examples": [ null ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:31.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:31.000000Z" ] }, "success_message": { "type": "string", "examples": [ "Quia quo est et consequatur qui quis quibusdam." ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "is_elective": { "type": "integer", "examples": [ 0 ] }, "estimated_complete_time": { "type": "integer", "examples": [ 11 ] }, "ttl": { "type": "integer", "examples": [ 0 ] }, "pass_score": { "type": "integer", "examples": [ 0 ] }, "is_library": { "type": "integer", "examples": [ 0 ] }, "publish": { "type": "integer", "examples": [ 1 ] }, "service": { "type": "string", "examples": [ "online" ] }, "external_id": { "type": [ "string", "null" ], "examples": [ null ] }, "meta": { "type": "array", "examples": [ [] ] }, "token": { "type": "string", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "certificate_id": { "type": [ "string", "null" ], "examples": [ null ] }, "form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "type_id": { "type": [ "string", "null" ], "examples": [ null ] }, "is_inheritable": { "type": "integer", "examples": [ 0 ] } } }, "nice": { "type": "object", "properties": { "publish": { "type": "string", "examples": [ "Yes" ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "account_url": { "type": "string", "examples": [ "https://sub.rosterfy2.localhost.com/" ] }, "external": { "type": "boolean", "examples": [ false ] }, "has_certificate": { "type": "boolean", "examples": [ false ] }, "account_name_path": { "type": "string", "examples": [ "Rosterfy Subaccount" ] }, "is_foreign_account": { "type": "boolean", "examples": [ false ] }, "acts_as_native": { "type": "boolean", "examples": [ false ] }, "number_of_steps": { "type": "integer", "examples": [ 3 ] }, "number_of_questions": { "type": "integer", "examples": [ 0 ] } } }, "relations": { "type": "object", "properties": { "account": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 20101 ] }, "parent_id": { "type": "integer", "examples": [ 1 ] }, "account_type_id": { "type": "integer", "examples": [ 3 ] }, "path": { "type": "string", "examples": [ "1/20101" ] }, "name": { "type": "string", "examples": [ "Rosterfy Subaccount" ] }, "config": { "type": "object", "properties": { "active_settings": { "type": "array", "items": { "type": "string" }, "examples": [ [ "general:available_locales", "general:locale", "general:timezone", "general:country", "general:distance_unit", "general:approved_countries", "general:start_day_of_week", "general:location", "users:photo_width", "users:photo_height", "users:login", "users:login_session_length", "users:login_social", "users:login_recaptcha", "users:register", "users:require_dob", "users:minimum_age", "users:minimum_age_by_date", "users:allow_availability_form_field", "event:advanced_scheduling", "event:shift_max_time", "event:gap_between_shifts", "event:min_shift_length", "event:max_shift_length", "event:min_shift_apps_per_user", "event:max_shift_apps_per_user", "event:shift_status_default", "event:shift_confirmed_status_default", "event:shift_rejected_status_default", "event:shift_can_withdraw_default", "event:shift_can_withdraw_limit", "event:shift_can_confirm_limit", "event:shift_checked_in_status_default", "event:shift_application_form_id_default", "event:shift_checkin_form_id_default", "event:shift_attended_form_id_default", "event:shift_checkout_form_id_default", "event:shift_feedback_form_id_default", "event:self_checkin", "event:self_checkin_open", "event:self_checkin_close", "event:self_checkout_close", "event:checkin_visible_attributes", "event:shift_show_demand", "training:id", "email:from_name", "email:reply_to", "email:forgot_password_template_id", "email:email_verification_template_id", "email:user_lockout_template_id", "email:user_invitation_email_template_id", "email:contact_us_email_template_id", "email:admin_invitation_email_template_id", "email:banner", "branding:name", "branding:subtitle", "branding:address", "branding:logo", "branding:logo_mono", "branding:background_image", "branding:banner_image", "branding:favicon", "branding:primary_color", "branding:secondary_color", "branding:custom_css", "advanced:default_dashboard", "portal:visible_stats" ] ] } } }, "meta": { "type": "array", "examples": [ [] ] }, "visibility_rules": { "type": "array", "examples": [ [] ] }, "status": { "type": "string", "examples": [ "approved" ] }, "status_reason": { "type": [ "string", "null" ], "examples": [ null ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "start_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "end_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "notes": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_firstname": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_lastname": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_email": { "type": [ "string", "null" ], "examples": [ null ] }, "contact_phone": { "type": [ "string", "null" ], "examples": [ null ] }, "support_manager_email": { "type": "string", "examples": [ "support_manager@rosterfy.com" ] }, "allow_deletion_request": { "type": "integer", "examples": [ 1 ] }, "organization_type": { "type": [ "string", "null" ], "examples": [ null ] }, "contract_start_date": { "type": "string", "examples": [ "2026-06-09" ] }, "contract_end_date": { "type": "string", "examples": [ "2027-06-09" ] }, "billing_contact_email": { "type": "string", "examples": [ "billing_contact@rosterfy.com" ] }, "billing_support_email": { "type": "string", "examples": [ "billing_support@rosterfy.com" ] }, "is_enabled": { "type": "integer", "examples": [ 1 ] }, "additional_billing_support_email": { "type": "string", "examples": [ "additional_billing_contact@rosterfy.com" ] }, "delete_requested_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "trial_ends_at": { "type": [ "string", "null" ], "examples": [ null ] }, "can_erase": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:33:32.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T07:08:01.000000Z" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:1:account:20101" ] }, "address": { "type": "string", "examples": [ "No Address" ] }, "address_oneline": { "type": "string", "examples": [ "No Address" ] }, "account_type_id": { "type": "string", "examples": [ "Enterprise" ] }, "account_type_id:value": { "type": "integer", "examples": [ 3 ] }, "account_type_id:array": { "type": "string", "examples": [ "Enterprise" ] }, "allow_deletion_request": { "type": "string", "examples": [ "Yes" ] }, "contact_firstname": { "type": "string", "examples": [ "" ] }, "contact_lastname": { "type": "string", "examples": [ "" ] }, "contact_phone:qr_code_value": { "type": "string", "examples": [ "" ] }, "contact_phone": { "type": "string", "examples": [ "" ] }, "contact_phone:raw": { "type": "string", "examples": [ "" ] }, "contract_end_date": { "type": "string", "examples": [ "Jun 9, 2027" ] }, "contract_end_date__dayofweek": { "type": "string", "examples": [ "Wednesday" ] }, "contract_start_date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "contract_start_date__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "name": { "type": "string", "examples": [ "Rosterfy Subaccount" ] }, "notes": { "type": "string", "examples": [ "" ] }, "organization_type": { "type": [ "string", "null" ], "examples": [ null ] }, "organization_type:value": { "type": [ "string", "null" ], "examples": [ null ] }, "organization_type:array": { "type": [ "string", "null" ], "examples": [ null ] }, "status": { "type": "string", "examples": [ "Approved" ] }, "status:value": { "type": "string", "examples": [ "approved" ] }, "status:array": { "type": "string", "examples": [ "approved" ] }, "status_reason": { "type": "string", "examples": [ "" ] }, "created_at": { "type": "string", "examples": [ "2026-06-09 05:33:32" ] }, "url": { "type": "string", "examples": [ "https://sub.rosterfy2.localhost.com/" ] }, "branding_name": { "type": "string", "examples": [ "Rosterfy" ] }, "branding_subtitle": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo_mono": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_logo_stacked": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_banner": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_description": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_primary_color": { "type": "string", "examples": [ "#3131c7" ] }, "branding_complimentary_color": { "type": [ "string", "null" ], "examples": [ null ] }, "branding_secondary_color": { "type": "string", "examples": [ "#38b6ff" ] }, "register": { "type": "boolean", "examples": [ false ] }, "organisation_contact": { "type": "string", "examples": [ " " ] }, "has_subaccount_approved_email_template": { "type": "boolean", "examples": [ false ] }, "has_subaccount_rejected_email_template": { "type": "boolean", "examples": [ false ] }, "parent_account_name": { "type": "string", "examples": [ "Rosterfy2" ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ false ] }, "delete": { "type": "boolean", "examples": [ false ] } } } } }, "certificate": { "type": [ "string", "null" ], "examples": [ null ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "name": "Paper Goods Machine Operator_EBMsffvoa9Ht", "short_description": null, "thumbnail_url": null, "account_id": 20101, "deleted_at": null, "created_at": "2026-06-09T05:36:31.000000Z", "updated_at": "2026-06-09T05:36:31.000000Z", "success_message": "Quia quo est et consequatur qui quis quibusdam.", "is_archived": 0, "is_elective": 0, "estimated_complete_time": 11, "ttl": 0, "pass_score": 0, "is_library": 0, "publish": 1, "service": "online", "external_id": null, "meta": [], "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "sort_order": 0, "certificate_id": null, "form_id": null, "type_id": null, "is_inheritable": 0 }, "nice": { "publish": "Yes", "account_id": 20101, "account_url": "https://sub.rosterfy2.localhost.com/", "external": false, "has_certificate": false, "account_name_path": "Rosterfy Subaccount", "is_foreign_account": false, "acts_as_native": false, "number_of_steps": 3, "number_of_questions": 0 }, "relations": { "account": { "object": { "id": 20101, "parent_id": 1, "account_type_id": 3, "path": "1/20101", "name": "Rosterfy Subaccount", "config": { "active_settings": [ "general:available_locales", "general:locale", "general:timezone", "general:country", "general:distance_unit", "general:approved_countries", "general:start_day_of_week", "general:location", "users:photo_width", "users:photo_height", "users:login", "users:login_session_length", "users:login_social", "users:login_recaptcha", "users:register", "users:require_dob", "users:minimum_age", "users:minimum_age_by_date", "users:allow_availability_form_field", "event:advanced_scheduling", "event:shift_max_time", "event:gap_between_shifts", "event:min_shift_length", "event:max_shift_length", "event:min_shift_apps_per_user", "event:max_shift_apps_per_user", "event:shift_status_default", "event:shift_confirmed_status_default", "event:shift_rejected_status_default", "event:shift_can_withdraw_default", "event:shift_can_withdraw_limit", "event:shift_can_confirm_limit", "event:shift_checked_in_status_default", "event:shift_application_form_id_default", "event:shift_checkin_form_id_default", "event:shift_attended_form_id_default", "event:shift_checkout_form_id_default", "event:shift_feedback_form_id_default", "event:self_checkin", "event:self_checkin_open", "event:self_checkin_close", "event:self_checkout_close", "event:checkin_visible_attributes", "event:shift_show_demand", "training:id", "email:from_name", "email:reply_to", "email:forgot_password_template_id", "email:email_verification_template_id", "email:user_lockout_template_id", "email:user_invitation_email_template_id", "email:contact_us_email_template_id", "email:admin_invitation_email_template_id", "email:banner", "branding:name", "branding:subtitle", "branding:address", "branding:logo", "branding:logo_mono", "branding:background_image", "branding:banner_image", "branding:favicon", "branding:primary_color", "branding:secondary_color", "branding:custom_css", "advanced:default_dashboard", "portal:visible_stats" ] }, "meta": [], "visibility_rules": [], "status": "approved", "status_reason": null, "sort_order": 0, "start_timestamp": null, "end_timestamp": null, "notes": null, "contact_firstname": null, "contact_lastname": null, "contact_email": null, "contact_phone": null, "support_manager_email": "support_manager@rosterfy.com", "allow_deletion_request": 1, "organization_type": null, "contract_start_date": "2026-06-09", "contract_end_date": "2027-06-09", "billing_contact_email": "billing_contact@rosterfy.com", "billing_support_email": "billing_support@rosterfy.com", "is_enabled": 1, "additional_billing_support_email": "additional_billing_contact@rosterfy.com", "delete_requested_at": null, "is_archived": 0, "trial_ends_at": null, "can_erase": 0, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:33:32.000000Z", "updated_at": "2026-06-09T07:08:01.000000Z" }, "nice": { "rrn": "rrn:local:1:account:20101", "address": "No Address", "address_oneline": "No Address", "account_type_id": "Enterprise", "account_type_id:value": 3, "account_type_id:array": "Enterprise", "allow_deletion_request": "Yes", "contact_firstname": "", "contact_lastname": "", "contact_phone:qr_code_value": "", "contact_phone": "", "contact_phone:raw": "", "contract_end_date": "Jun 9, 2027", "contract_end_date__dayofweek": "Wednesday", "contract_start_date": "Jun 9, 2026", "contract_start_date__dayofweek": "Tuesday", "name": "Rosterfy Subaccount", "notes": "", "organization_type": null, "organization_type:value": null, "organization_type:array": null, "status": "Approved", "status:value": "approved", "status:array": "approved", "status_reason": "", "created_at": "2026-06-09 05:33:32", "url": "https://sub.rosterfy2.localhost.com/", "branding_name": "Rosterfy", "branding_subtitle": null, "branding_logo": null, "branding_logo_mono": null, "branding_logo_stacked": null, "branding_banner": null, "branding_description": null, "branding_primary_color": "#3131c7", "branding_complimentary_color": null, "branding_secondary_color": "#38b6ff", "register": false, "organisation_contact": " ", "has_subaccount_approved_email_template": false, "has_subaccount_rejected_email_template": false, "parent_account_name": "Rosterfy2" }, "permissions": { "read": true, "update": false, "delete": false } }, "certificate": null }, "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Training Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "success_message": { "type": "string", "description": "The end of course message, shown when a user finishes the module. HTML, maximum 64,000 characters.", "examples": [ "Quia quo est et consequatur qui quis quibusdam." ] }, "name": { "type": "string", "description": "The name of the module. Maximum 255 characters. Translatable: send a plain string to set it for the request locale, or an object keyed by locale such as {\"en-US\": \"Induction\"}.", "examples": [ "Paper Goods Machine Operator_EBMsffvoa9Ht" ] }, "estimated_complete_time": { "type": "integer", "description": "How long the module is expected to take, in minutes.", "examples": [ 11 ] }, "publish": { "type": "boolean", "description": "Whether the module is published. Until it is, the module is not visible in the portal.", "examples": [ 1 ] }, "is_archived": { "type": "boolean", "description": "Whether the module is archived. The mass-archive endpoint sets this field in bulk.", "examples": [ 0 ] }, "is_elective": { "type": "boolean", "description": "Whether any user who can access training may complete this module.", "examples": [ 0 ] }, "is_inheritable": { "type": "boolean", "description": "Whether accounts below the owning account may use this module. Reflected in the response as nice.acts_as_native.", "examples": [ 0 ] }, "type_id": { "type": "integer", "description": "The ID of the training type to categorise this module under. Used for reporting and filtering, and optional.", "examples": [ 1 ] }, "service": { "type": "string", "description": "The training provider. One of online, scorm, scorm_upload or bespoke for modules Rosterfy hosts, or the code of an external provider. A module whose service is not one of the four local values reads as external, and the update endpoint ignores this field for those modules.", "examples": [ "online" ] }, "external_id": { "type": "string", "description": "The ID of the module in the external training provider. Recorded when the module is synced from that provider, and sent back to it on assignment and completion.", "examples": [ null ] }, "meta": { "type": "object", "description": "Provider and behaviour options for the module. The documented subkeys follow. On create this object is stored as sent; on update it is merged into the stored object, so omitted subkeys keep their current values.", "properties": { "onetime": { "type": "boolean", "description": "Whether a user is blocked from repeating the module if they do not pass on the first attempt.", "examples": [ true ] }, "score": { "type": "boolean", "description": "Whether a score is recorded. The user always moves to the next step when there is a question, and the total correct answers make up the score.", "examples": [ true ] }, "inform_answer": { "type": "boolean", "description": "Whether the user is told if their answer was correct.", "examples": [ true ] }, "show_correct": { "type": "boolean", "description": "Whether the user is shown the correct answers.", "examples": [ true ] }, "inform_score": { "type": "boolean", "description": "Whether the user is shown the percentage required to pass and their own score at the end.", "examples": [ true ] }, "template_id": { "type": "integer", "description": "The ID of the email template to send when a user finishes the module.", "examples": [ 1 ] }, "code": { "type": "string", "description": "The course code the module has in the external provider. Set when the module is synced from that provider.", "examples": [ null ] }, "original_id": { "type": "string", "description": "The original module ID in the external provider. Set when the module is synced from that provider.", "examples": [ null ] }, "source": { "type": "string", "description": "The name of the external provider the module was synced from.", "examples": [ null ] }, "height": { "type": "integer", "description": "The height of the SCORM frame in the portal, in pixels. Must be under 5000. Defaults to 600.", "examples": [ 1 ] }, "suspend": { "type": "boolean", "description": "Whether the user is forced to restart the SCORM module if they return after starting it.", "examples": [ true ] }, "redirect_url": { "type": "string", "description": "The URL the user is redirected to from the portal to take the training. Required when service is bespoke.", "examples": [ null ] }, "entrypoint": { "type": "string", "description": "The file the SCORM package starts at, usually index.html or story.html. Required when service is scorm or scorm_upload.", "examples": [ null ] }, "complete": { "type": "string", "description": "The status the SCORM file emits to tell Rosterfy the training is complete, usually complete or passed. Your SCORM provider will tell you this status. Required when service is scorm or scorm_upload.", "examples": [ null ] } }, "examples": [ [] ] }, "ttl": { "type": "integer", "description": "How long a completion stays valid, in seconds. A user is required to retake the module once it lapses, and re-completing resets the expiry. Only applied when greater than 0, and forced to 0 when can_expire is sent as false.", "examples": [ 0 ] }, "is_library": { "type": "boolean", "description": "Stored, but read by nothing in the platform.", "examples": [ 0 ] }, "form_id": { "type": "integer", "description": "The ID of the form a user completes before starting the module without a Rosterfy account. Setting it is also what makes the module readable unauthenticated - see the read endpoint. Cleared when anonymous_enable is sent as false.", "examples": [ 1 ] }, "certificate_id": { "type": "integer", "description": "The ID of the certificate to award when the module is completed successfully.", "examples": [ 1 ] }, "pass_score": { "type": "integer", "description": "The percentage a user must reach to be marked as passed, from 0 to 100. Applies when meta.score is true.", "examples": [ 0 ] }, "sort_order": { "type": "integer", "description": "The position of the module where listings are ordered by sort order.", "examples": [ 0 ] }, "scorm_upload": { "type": "string", "description": "URL of an uploaded SCORM zip, up to 100MB, which Rosterfy unzips and stores. Only acted on by the update endpoint; on create the field is accepted and ignored.", "examples": [ null ] }, "short_description": { "type": "string", "description": "A short summary of the module. Not validated by the server; anything the column accepts is stored.", "examples": [ null ] }, "thumbnail_url": { "type": "string", "description": "URL of, or an upload for, the module thumbnail. Recommended 245x150 pixels. Not validated by the server.", "examples": [ null ] }, "can_expire": { "type": "boolean", "description": "Whether completions of this module expire. Not stored; sending it as false is what sets ttl to 0.", "examples": [ true ] }, "anonymous_enable": { "type": "boolean", "description": "Whether the module may be completed by someone without a Rosterfy account. Not stored; sending it as false is what clears form_id and meta.template_id.", "examples": [ true ] } } } } } } }, "delete": { "summary": "Delete a training module", "operationId": "deleteATrainingModule", "description": "Deletes the module and, with it, every user's assignment to and progress on it.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "204": { "description": "No content, successful deletion", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Training Module" ] }, "parameters": [ { "in": "path", "name": "id", "description": "The ID of the training module.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/training/{training_id}/user": { "get": { "summary": "List a module's assigned users", "operationId": "listAModulesAssignedUsers", "description": "Returns the users assigned to a training module, one row per assignment,\nwith the status and progress of each.\n\nAn assignment whose user has since been deleted is left out, so this list can\nbe shorter than the number of assignments the module has ever had.\n\nThe response is only wrapped in a paginated envelope when a page parameter is\nsent. Without one, every match comes back as a flat array.\n\nRelated records are not included unless asked for. Requesting the user\nrelation returns that user's full profile, so ask for it only when the\nprofile is what you need - the assignment itself already carries user_id.", "parameters": [ { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "query", "name": "extras", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "required": false, "schema": { "type": "array", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "items": { "type": "string", "enum": [ "statuslog" ] }, "examples": [ [ "statuslog" ] ] } }, { "in": "query", "name": "with", "description": "A list of relations to include in the response. May be single records or collections.\nIt is often more efficient to retrieve this way, to avoid follow-up API calls.", "required": false, "schema": { "type": "array", "description": "A list of relations to include in the response. May be single records or collections.\nIt is often more efficient to retrieve this way, to avoid follow-up API calls.", "items": { "type": "string", "enum": [ "account" ] }, "examples": [ [ "account" ] ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "training_id": { "type": "integer", "examples": [ 1 ] }, "user_id": { "type": "integer", "examples": [ 1234 ] }, "steps_completed": { "type": "integer", "examples": [ 2 ] }, "status": { "type": "string", "examples": [ "INCOMPLETE" ] }, "score": { "type": "integer", "examples": [ 0 ] }, "expires_at": { "type": [ "string", "null" ], "examples": [ null ] }, "meta": { "type": [ "string", "null" ], "examples": [ null ] }, "external_id": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:32.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:32.000000Z" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:training_user:1" ] }, "training_name": { "type": "string", "examples": [ "Site Safety Induction" ] }, "training_service": { "type": "string", "examples": [ "online" ] }, "training_meta": { "type": "object", "properties": { "middleware": { "type": "string", "examples": [ "https://example.rosterfy.com/scorm/index.html" ] } } }, "has_history": { "type": "boolean", "examples": [ false ] }, "training_success_message": { "type": "string", "examples": [ "Thanks for completing this module." ] }, "is_expired": { "type": "boolean", "examples": [ false ] }, "status": { "type": "string", "examples": [ "Incomplete" ] }, "binary_status": { "type": "boolean", "examples": [ false ] }, "finished_status": { "type": "boolean", "examples": [ false ] }, "score_percentage": { "type": "integer", "examples": [ 0 ] }, "steps_percentage": { "type": "number", "examples": [ 66.67 ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } }, "examples": [ [ { "object": { "id": 1, "training_id": 1, "user_id": 1234, "steps_completed": 2, "status": "INCOMPLETE", "score": 0, "expires_at": null, "meta": null, "external_id": null, "deleted_at": null, "created_at": "2026-06-09T05:36:32.000000Z", "updated_at": "2026-06-09T05:36:32.000000Z" }, "nice": { "rrn": "rrn:local:20101:training_user:1", "training_name": "Site Safety Induction", "training_service": "online", "training_meta": { "middleware": "https://example.rosterfy.com/scorm/index.html" }, "has_history": false, "training_success_message": "Thanks for completing this module.", "is_expired": false, "status": "Incomplete", "binary_status": false, "finished_status": false, "score_percentage": 0, "steps_percentage": 66.67 }, "relations": [], "permissions": { "read": true, "update": true, "delete": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/training/{training}/user?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/training/{training}/user?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/training/{training}/user" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 1, "training_id": 1, "user_id": 1234, "steps_completed": 2, "status": "INCOMPLETE", "score": 0, "expires_at": null, "meta": null, "external_id": null, "deleted_at": null, "created_at": "2026-06-09T05:36:32.000000Z", "updated_at": "2026-06-09T05:36:32.000000Z" }, "nice": { "rrn": "rrn:local:20101:training_user:1", "training_name": "Site Safety Induction", "training_service": "online", "training_meta": { "middleware": "https://example.rosterfy.com/scorm/index.html" }, "has_history": false, "training_success_message": "Thanks for completing this module.", "is_expired": false, "status": "Incomplete", "binary_status": false, "finished_status": false, "score_percentage": 0, "steps_percentage": 66.67 }, "relations": [], "permissions": { "read": true, "update": true, "delete": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/training/{training}/user?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/training/{training}/user?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/training/{training}/user", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Training Module" ] }, "post": { "summary": "Assign a module to a user", "operationId": "assignAModuleToAUser", "description": "Assigns the training module in the URL to one user and returns the new\nassignment in the same shape as reading it, so a follow-up read is not\nneeded.\n\nA user can hold only one live assignment per module. Asking for one that\nalready exists returns a **403**, not a conflict or a duplicate - so check\nfor an existing assignment first if you cannot be sure. Deleting an\nassignment frees the user to be assigned again.\n\nAn unknown user, or a request with no user_id at all, returns a **404**.\n\nOnly user_id and status are read. Every other writable field is ignored here,\nso a new assignment always starts with no score, no external reference and no\nsteps completed; set those with a follow-up update. status is checked against\nthe five permitted values and a 422 names it if it is not one of them.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "training_id": { "type": "integer", "examples": [ 1 ] }, "user_id": { "type": "integer", "examples": [ 1234 ] }, "steps_completed": { "type": "integer", "examples": [ 2 ] }, "status": { "type": "string", "examples": [ "INCOMPLETE" ] }, "score": { "type": "integer", "examples": [ 0 ] }, "expires_at": { "type": [ "string", "null" ], "examples": [ null ] }, "meta": { "type": [ "string", "null" ], "examples": [ null ] }, "external_id": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:32.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:32.000000Z" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:training_user:1" ] }, "training_name": { "type": "string", "examples": [ "Site Safety Induction" ] }, "training_service": { "type": "string", "examples": [ "online" ] }, "training_meta": { "type": "object", "properties": { "middleware": { "type": "string", "examples": [ "https://example.rosterfy.com/scorm/index.html" ] } } }, "has_history": { "type": "boolean", "examples": [ false ] }, "training_success_message": { "type": "string", "examples": [ "Thanks for completing this module." ] }, "is_expired": { "type": "boolean", "examples": [ false ] }, "status": { "type": "string", "examples": [ "Incomplete" ] }, "binary_status": { "type": "boolean", "examples": [ false ] }, "finished_status": { "type": "boolean", "examples": [ false ] }, "score_percentage": { "type": "integer", "examples": [ 0 ] }, "steps_percentage": { "type": "number", "examples": [ 66.67 ] } } }, "relations": { "type": "object", "properties": {} }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "training_id": 1, "user_id": 1234, "steps_completed": 2, "status": "INCOMPLETE", "score": 0, "expires_at": null, "meta": null, "external_id": null, "deleted_at": null, "created_at": "2026-06-09T05:36:32.000000Z", "updated_at": "2026-06-09T05:36:32.000000Z" }, "nice": { "rrn": "rrn:local:20101:training_user:1", "training_name": "Site Safety Induction", "training_service": "online", "training_meta": { "middleware": "https://example.rosterfy.com/scorm/index.html" }, "has_history": false, "training_success_message": "Thanks for completing this module.", "is_expired": false, "status": "Incomplete", "binary_status": false, "finished_status": false, "score_percentage": 0, "steps_percentage": 66.67 }, "relations": {}, "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "This Training has already been assigned to this User" ] } }, "examples": [ { "message": "This Training has already been assigned to this User" } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Training Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "The user the module is assigned to. Required on create. Sending it on update hands the assignment, and the progress recorded against it, to a different user - so omit it unless that is what you want.", "examples": [ 1234 ] }, "status": { "type": "string", "description": "Where the user has got to. One of COMPLETE, INCOMPLETE, PASSED, FAILED or EXEMPT. Defaults to INCOMPLETE on create. Setting it to COMPLETE also sets steps_completed to the module's full step count; setting it back to INCOMPLETE from COMPLETE resets steps_completed to 0.", "examples": [ "INCOMPLETE" ] } }, "required": [ "user_id" ] } } } } }, "put": { "summary": "Assign a module to many users", "operationId": "assignAModuleToManyUsers", "description": "Assigns the training module in the URL to a set of users at once.\n\n**This write is queued.** The response does not contain the assignments and\ndoes not mean they exist yet - it means the request was accepted and the work\nis running in the background. The payload is a single queue field holding an\nidentifier for that work. There is no endpoint that resolves the identifier,\nso confirm the outcome by listing the module's assigned users.\n\nChoose the users either way round:\n\n- Send `applyTo` as `selected` with `selected` holding the user IDs to add.\n- Send any other `applyTo` value to add every user the caller can see, narrowed\n by an optional `filter`, in the same form the user listing accepts.\n\nUsers already assigned to the module are skipped, so the same request can be\nrepeated safely. A request naming no users still succeeds and assigns nobody.\n\nInvalid input returns a 422 before anything is queued.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "queue": { "type": "string", "examples": [ "mTsVQ1NCLS3vg7WwP5kG1Vbt" ] } }, "examples": [ { "queue": "mTsVQ1NCLS3vg7WwP5kG1Vbt" } ] } } } } }, "tags": [ "Training Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "applyTo": { "type": "string", "description": "Send `selected` to assign the module to the users named in selected. Any other value assigns it to every user the caller can see, narrowed by filter if one is sent.", "examples": [ null ] }, "selected": { "type": "array", "description": "The IDs of the users to assign. Required when applyTo is `selected`, and ignored otherwise.", "items": { "type": "integer" }, "examples": [ [] ] } }, "required": [ "applyTo" ] } } } } }, "parameters": [ { "in": "path", "name": "training_id", "description": "The ID of the training module.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/training/{training_id}/user/{id}": { "get": { "summary": "Read an assignment", "operationId": "readAnAssignment", "description": "Returns one user's assignment to a training module: the status they are at,\nhow many steps they have finished, their score, and when the completion\nexpires.\n\nnice carries the readable form of the same record - the module's name, the\nstatus as a label, and steps_percentage and score_percentage worked out\nagainst the module's totals. steps_percentage is the more useful progress\nfigure, since steps_completed on its own means nothing without the module's\nstep count.\n\nThe assignment must belong to the module in the URL; a mismatched pair\nreturns a 404.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "training_id": { "type": "integer", "examples": [ 1 ] }, "user_id": { "type": "integer", "examples": [ 1234 ] }, "steps_completed": { "type": "integer", "examples": [ 2 ] }, "status": { "type": "string", "examples": [ "INCOMPLETE" ] }, "score": { "type": "integer", "examples": [ 0 ] }, "expires_at": { "type": [ "string", "null" ], "examples": [ null ] }, "meta": { "type": [ "string", "null" ], "examples": [ null ] }, "external_id": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:32.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:32.000000Z" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:training_user:1" ] }, "training_name": { "type": "string", "examples": [ "Site Safety Induction" ] }, "training_service": { "type": "string", "examples": [ "online" ] }, "training_meta": { "type": "object", "properties": { "middleware": { "type": "string", "examples": [ "https://example.rosterfy.com/scorm/index.html" ] } } }, "has_history": { "type": "boolean", "examples": [ false ] }, "training_success_message": { "type": "string", "examples": [ "Thanks for completing this module." ] }, "is_expired": { "type": "boolean", "examples": [ false ] }, "status": { "type": "string", "examples": [ "Incomplete" ] }, "binary_status": { "type": "boolean", "examples": [ false ] }, "finished_status": { "type": "boolean", "examples": [ false ] }, "score_percentage": { "type": "integer", "examples": [ 0 ] }, "steps_percentage": { "type": "number", "examples": [ 66.67 ] } } }, "relations": { "type": "object", "properties": {} }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "training_id": 1, "user_id": 1234, "steps_completed": 2, "status": "INCOMPLETE", "score": 0, "expires_at": null, "meta": null, "external_id": null, "deleted_at": null, "created_at": "2026-06-09T05:36:32.000000Z", "updated_at": "2026-06-09T05:36:32.000000Z" }, "nice": { "rrn": "rrn:local:20101:training_user:1", "training_name": "Site Safety Induction", "training_service": "online", "training_meta": { "middleware": "https://example.rosterfy.com/scorm/index.html" }, "has_history": false, "training_success_message": "Thanks for completing this module.", "is_expired": false, "status": "Incomplete", "binary_status": false, "finished_status": false, "score_percentage": 0, "steps_percentage": 66.67 }, "relations": {}, "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Training Module" ] }, "put": { "summary": "Update an assignment", "operationId": "updateAnAssignment", "description": "Updates the fields supplied and leaves the rest untouched, then returns the\nassignment in the same shape as reading it. Every field is optional and an\nempty body is a valid request that changes nothing.\n\n**status and steps_completed are kept consistent with each other**, so\nsending one can change the other:\n\n- Setting status to COMPLETE sets steps_completed to the module's full step\n count.\n- Setting status to INCOMPLETE on an assignment that was COMPLETE resets\n steps_completed to 0.\n- Sending a steps_completed equal to the module's full step count sets status\n to COMPLETE, whether or not status was sent.\n\nSo a request that sends only one of the two can come back with both changed.\nRead the returned record rather than assuming the values you sent.\n\nMoving an assignment to a status that counts as finished - COMPLETE, PASSED or\nEXEMPT - is what marks the module done for that user, and runs whatever the\nmodule has set up to follow completion, such as issuing a certificate. If the\nmodule has a retake period, expires_at is set from it at the same time.\n\nThe assignment must belong to the module in the URL; a mismatched pair returns\na 404. Invalid input returns a 422 identifying the fields at fault.\n\nSend neither training_id nor user_id unless you mean to hand the assignment to\na different module or a different user. Changing training_id is applied and\n*then* returns a 404, because the updated record no longer belongs to the\nmodule in the URL - so a 404 here does not mean the change was rejected.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "training_id": { "type": "integer", "examples": [ 1 ] }, "user_id": { "type": "integer", "examples": [ 1234 ] }, "steps_completed": { "type": "integer", "examples": [ 2 ] }, "status": { "type": "string", "examples": [ "INCOMPLETE" ] }, "score": { "type": "integer", "examples": [ 0 ] }, "expires_at": { "type": [ "string", "null" ], "examples": [ null ] }, "meta": { "type": [ "string", "null" ], "examples": [ null ] }, "external_id": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:32.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:32.000000Z" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:training_user:1" ] }, "training_name": { "type": "string", "examples": [ "Site Safety Induction" ] }, "training_service": { "type": "string", "examples": [ "online" ] }, "training_meta": { "type": "object", "properties": { "middleware": { "type": "string", "examples": [ "https://example.rosterfy.com/scorm/index.html" ] } } }, "has_history": { "type": "boolean", "examples": [ false ] }, "training_success_message": { "type": "string", "examples": [ "Thanks for completing this module." ] }, "is_expired": { "type": "boolean", "examples": [ false ] }, "status": { "type": "string", "examples": [ "Incomplete" ] }, "binary_status": { "type": "boolean", "examples": [ false ] }, "finished_status": { "type": "boolean", "examples": [ false ] }, "score_percentage": { "type": "integer", "examples": [ 0 ] }, "steps_percentage": { "type": "number", "examples": [ 66.67 ] } } }, "relations": { "type": "object", "properties": {} }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "training_id": 1, "user_id": 1234, "steps_completed": 2, "status": "INCOMPLETE", "score": 0, "expires_at": null, "meta": null, "external_id": null, "deleted_at": null, "created_at": "2026-06-09T05:36:32.000000Z", "updated_at": "2026-06-09T05:36:32.000000Z" }, "nice": { "rrn": "rrn:local:20101:training_user:1", "training_name": "Site Safety Induction", "training_service": "online", "training_meta": { "middleware": "https://example.rosterfy.com/scorm/index.html" }, "has_history": false, "training_success_message": "Thanks for completing this module.", "is_expired": false, "status": "Incomplete", "binary_status": false, "finished_status": false, "score_percentage": 0, "steps_percentage": 66.67 }, "relations": {}, "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Training Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "training_id": { "type": "integer", "description": "The module the assignment belongs to. Taken from the URL on create, so there is no need to send it. Sending a different one on update moves the assignment to that module, and because the response is then read back against the module in the URL, the request returns 404 even though the move has been applied. Omit it.", "examples": [ 1 ] }, "user_id": { "type": "integer", "description": "The user the module is assigned to. Required on create. Sending it on update hands the assignment, and the progress recorded against it, to a different user - so omit it unless that is what you want.", "examples": [ 1234 ] }, "status": { "type": "string", "description": "Where the user has got to. One of COMPLETE, INCOMPLETE, PASSED, FAILED or EXEMPT. Defaults to INCOMPLETE on create. Setting it to COMPLETE also sets steps_completed to the module's full step count; setting it back to INCOMPLETE from COMPLETE resets steps_completed to 0.", "examples": [ "INCOMPLETE" ] }, "steps_completed": { "type": "integer", "description": "How many of the module's steps the user has finished. Sending a value equal to the module's total step count marks the assignment COMPLETE.", "examples": [ 2 ] }, "expires_at": { "type": "string", "description": "When the completion stops counting, as YYYY-MM-DD HH:MM:SS. Set automatically from the module's retake period when the assignment completes, so it rarely needs sending.", "examples": [ null ] }, "score": { "type": "integer", "description": "The score the user achieved. Stored as sent and not validated, so keep it a whole number.", "examples": [ 0 ] }, "external_id": { "type": "string", "description": "Your own reference for the assignment, or the status reported by an externally hosted course. Stored as sent and not validated.", "examples": [ null ] }, "meta": { "type": "object", "description": "Free-form object stored against the assignment. Rosterfy keeps the completion history under a history key, so send a full object rather than a partial one.", "properties": {}, "examples": [ "{}" ] } } } } } } }, "delete": { "summary": "Delete an assignment", "operationId": "deleteAnAssignment", "description": "Removes a user's assignment to the module, along with the progress recorded\nagainst it. There is no endpoint that restores one, so treat this as final.\n\nDeleting an assignment frees the user to be assigned the module again, which\nstarts their progress from nothing.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "204": { "description": "No content, successful deletion", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Training Module" ] }, "parameters": [ { "in": "path", "name": "training_id", "description": "The ID of the training module.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } }, { "in": "path", "name": "id", "description": "The ID of the assignment.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/headcount/functionalarea": { "get": { "summary": "List functional areas", "operationId": "listFunctionalAreas", "description": "Returns the functional areas the account holds - the groups its workforce is\norganised into, each with a target headcount and the roles that sit under it.\n\nThe listing is only paginated when `page` is supplied. Without it every match is\nreturned as a flat array rather than in the paged envelope.", "parameters": [ { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "query", "name": "extras", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "required": false, "schema": { "type": "array", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "items": { "type": "string", "enum": [ "demand" ] }, "examples": [ [ "demand" ] ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "headcount_functional_area_type_id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Guest Services" ] }, "frontend_name": { "type": "string", "examples": [ "Guest Services" ] }, "code": { "type": "string", "examples": [ "GUESTSERVICES" ] }, "target": { "type": "integer", "examples": [ 50 ] }, "auto_update_mode": { "type": "integer", "examples": [ 0 ] }, "rules": { "type": "array", "examples": [ [] ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "is_system": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_by": { "type": "integer", "examples": [ 1234 ] }, "uuid": { "type": "string", "examples": [ "270eebe1-bc48-4ecf-a065-2c5ff65b33b0" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:functional_area:1" ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } }, "examples": [ [ { "object": { "id": 1, "account_id": 20101, "headcount_functional_area_type_id": 1, "name": "Guest Services", "frontend_name": "Guest Services", "code": "GUESTSERVICES", "target": 50, "auto_update_mode": 0, "rules": [], "training_ids": [ 1 ], "is_system": 0, "deleted_at": null, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:16.000000Z", "updated_by": 1234, "uuid": "270eebe1-bc48-4ecf-a065-2c5ff65b33b0" }, "nice": { "rrn": "rrn:local:20101:functional_area:1" }, "relations": [], "permissions": { "read": true, "update": true, "delete": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/headcount/functionalarea?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/headcount/functionalarea?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/headcount/functionalarea" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 1, "account_id": 20101, "headcount_functional_area_type_id": 1, "name": "Guest Services", "frontend_name": "Guest Services", "code": "GUESTSERVICES", "target": 50, "auto_update_mode": 0, "rules": [], "training_ids": [ 1 ], "is_system": 0, "deleted_at": null, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:16.000000Z", "updated_by": 1234, "uuid": "270eebe1-bc48-4ecf-a065-2c5ff65b33b0" }, "nice": { "rrn": "rrn:local:20101:functional_area:1" }, "relations": [], "permissions": { "read": true, "update": true, "delete": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/headcount/functionalarea?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/headcount/functionalarea?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/headcount/functionalarea", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Headcount Module" ] }, "post": { "summary": "Create a functional area", "operationId": "createAFunctionalArea", "description": "Sets up a new group to organise the workforce into, with a target headcount and,\noptionally, a set of conditions that keep its membership up to date on its own.\n\n`code` has to be unique within the account and is stored in upper case whatever\ncase it is sent in. Switching `auto_update_mode` on makes `rules` mandatory - a\ncreate that turns it on without well-formed conditions is rejected.\n\n**The created group comes back with only the fields that were set on it**, not the\nfull record that reading it returns: anything left to its stored default is absent\nrather than present and defaulted. Read the group back if you need its complete\nstate.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "rules": { "type": "array", "examples": [ [] ] }, "auto_update_mode": { "type": "integer", "examples": [ 0 ] }, "name": { "type": "string", "examples": [ "Guest Services" ] }, "frontend_name": { "type": "string", "examples": [ "Guest Services" ] }, "code": { "type": "string", "examples": [ "GUESTSERVICES" ] }, "headcount_functional_area_type_id": { "type": "integer", "examples": [ 1 ] }, "target": { "type": "integer", "examples": [ 50 ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "updated_by": { "type": "integer", "examples": [ 1234 ] }, "uuid": { "type": "string", "examples": [ "428585a9-f02d-4ca8-8383-35b1f8433f1c" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "id": { "type": "integer", "examples": [ 1 ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:functional_area:1" ] } } }, "relations": { "type": "object", "properties": {} }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "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": [ 1 ], "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 } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Headcount Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name administrators see. Required.", "examples": [ "Guest Services" ] }, "frontend_name": { "type": "string", "description": "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.", "examples": [ "Guest Services" ] }, "code": { "type": "string", "description": "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.", "examples": [ "GUESTSERVICES" ] }, "headcount_functional_area_type_id": { "type": "integer", "description": "The ID of the group type to file this group under. Optional; omit or send null to leave the group untyped.", "examples": [ 1 ] }, "target": { "type": "integer", "description": "How many people this group is aiming to have. `0` means no limit. Cannot be negative.", "examples": [ 50 ] }, "auto_update_mode": { "type": "integer", "description": "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.", "examples": [ 0 ] }, "rules": { "type": "array", "description": "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.", "items": { "type": "object" }, "examples": [ [] ] }, "training_ids": { "type": "array", "description": "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.", "items": { "type": "integer" }, "examples": [ [ 1 ] ] } }, "required": [ "name", "frontend_name", "code" ] } } } } } }, "/api/v2/headcount/functionalarea/{id}": { "get": { "summary": "Read a functional area", "operationId": "readAFunctionalArea", "description": "Returns one group with its target headcount, the type it is filed under, the\ntraining assigned to anyone who joins it, and the conditions that maintain its\nmembership if automatic updating is switched on.\n\n`permissions.delete` reflects whether this particular group can be removed, which\ndepends on whether roles are still recruiting under it.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "headcount_functional_area_type_id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Guest Services" ] }, "frontend_name": { "type": "string", "examples": [ "Guest Services" ] }, "code": { "type": "string", "examples": [ "GUESTSERVICES" ] }, "target": { "type": "integer", "examples": [ 50 ] }, "auto_update_mode": { "type": "integer", "examples": [ 0 ] }, "rules": { "type": "array", "examples": [ [] ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "is_system": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_by": { "type": "integer", "examples": [ 1234 ] }, "uuid": { "type": "string", "examples": [ "270eebe1-bc48-4ecf-a065-2c5ff65b33b0" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:functional_area:1" ] } } }, "relations": { "type": "object", "properties": {} }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "account_id": 20101, "headcount_functional_area_type_id": 1, "name": "Guest Services", "frontend_name": "Guest Services", "code": "GUESTSERVICES", "target": 50, "auto_update_mode": 0, "rules": [], "training_ids": [ 1 ], "is_system": 0, "deleted_at": null, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:16.000000Z", "updated_by": 1234, "uuid": "270eebe1-bc48-4ecf-a065-2c5ff65b33b0" }, "nice": { "rrn": "rrn:local:20101:functional_area:1" }, "relations": {}, "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Headcount Module" ] }, "put": { "summary": "Update a functional area", "operationId": "updateAFunctionalArea", "description": "Updates the fields supplied and returns the group in the same shape as reading it.\nOnly the fields sent are touched, so an empty body is a valid request that changes\nnothing.\n\n**`rules` is the exception, and it is worth reading before updating a group that\nupdates its membership automatically.** Omitting `rules` clears the conditions\nrather than leaving them alone, so on a group with `auto_update_mode` switched on\nan update that does not resend them is rejected and nothing changes. Send the\nconditions back on every update to such a group, or switch `auto_update_mode` to\n`0` in the same request.\n\nChanging the conditions does not revisit anyone already in the group in the same\nbreath - membership is reconciled as the conditions are next applied.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "headcount_functional_area_type_id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Guest Services" ] }, "frontend_name": { "type": "string", "examples": [ "Guest Services" ] }, "code": { "type": "string", "examples": [ "GUESTSERVICES" ] }, "target": { "type": "integer", "examples": [ 50 ] }, "auto_update_mode": { "type": "integer", "examples": [ 0 ] }, "rules": { "type": "array", "examples": [ [] ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "is_system": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_by": { "type": "integer", "examples": [ 1234 ] }, "uuid": { "type": "string", "examples": [ "270eebe1-bc48-4ecf-a065-2c5ff65b33b0" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:functional_area:1" ] } } }, "relations": { "type": "object", "properties": {} }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "account_id": 20101, "headcount_functional_area_type_id": 1, "name": "Guest Services", "frontend_name": "Guest Services", "code": "GUESTSERVICES", "target": 50, "auto_update_mode": 0, "rules": [], "training_ids": [ 1 ], "is_system": 0, "deleted_at": null, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:16.000000Z", "updated_by": 1234, "uuid": "270eebe1-bc48-4ecf-a065-2c5ff65b33b0" }, "nice": { "rrn": "rrn:local:20101:functional_area:1" }, "relations": {}, "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Headcount Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name administrators see. Required.", "examples": [ "Guest Services" ] }, "frontend_name": { "type": "string", "description": "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.", "examples": [ "Guest Services" ] }, "code": { "type": "string", "description": "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.", "examples": [ "GUESTSERVICES" ] }, "headcount_functional_area_type_id": { "type": "integer", "description": "The ID of the group type to file this group under. Optional; omit or send null to leave the group untyped.", "examples": [ 1 ] }, "target": { "type": "integer", "description": "How many people this group is aiming to have. `0` means no limit. Cannot be negative.", "examples": [ 50 ] }, "auto_update_mode": { "type": "integer", "description": "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.", "examples": [ 0 ] }, "rules": { "type": "array", "description": "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.", "items": { "type": "object" }, "examples": [ [] ] }, "training_ids": { "type": "array", "description": "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.", "items": { "type": "integer" }, "examples": [ [ 1 ] ] } } } } } } }, "delete": { "summary": "Delete a functional area", "operationId": "deleteAFunctionalArea", "description": "Removes the group. The record is retained internally so past reporting is not lost,\nbut the group can no longer be read or edited and no endpoint restores it.\n\n**A group that still has roles recruiting under it cannot be deleted** - remove or\nreassign its roles first. The same applies to the account's built-in default group,\nwhich is not removable at all.\n\nReturns `200` with a `messages` field rather than an empty `204`. `messages` carries\nanything the platform wants to tell you about the deletion and is `null` when there\nis nothing to say.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": [ "string", "null" ], "examples": [ null ] } }, "examples": [ { "messages": null } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Headcount Module" ] }, "parameters": [ { "in": "path", "name": "id", "description": "The ID of the functional area.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/headcount/functionalarea/{functionalarea_id}/jobtitle": { "get": { "summary": "List job titles", "operationId": "listJobTitles", "description": "Returns the roles recruiting under one functional area, each with the training\nassigned to whoever takes it on.\n\nThe listing is only paginated when `page` is supplied. Without it every match is\nreturned as a flat array rather than in the paged envelope.", "parameters": [ { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "query", "name": "extras", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "required": false, "schema": { "type": "array", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "items": { "type": "string", "enum": [ "demand" ] }, "examples": [ [ "demand" ] ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "headcount_functional_area_id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Information Desk Attendant" ] }, "frontend_name": { "type": "string", "examples": [ "Information Desk Attendant" ] }, "code": { "type": "string", "examples": [ "INFODESK" ] }, "description": { "type": "string", "examples": [ "

Answers visitor questions at the information desk.

" ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "uuid": { "type": "string", "examples": [ "e17404de-d3db-4e85-81ee-4552d19da8c4" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:job_title:1" ] }, "functional_area_name": { "type": "string", "examples": [ "Guest Services" ] } } }, "relations": { "type": "object", "properties": { "functional_area": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "headcount_functional_area_type_id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Guest Services" ] }, "frontend_name": { "type": "string", "examples": [ "Guest Services" ] }, "code": { "type": "string", "examples": [ "GUESTSERVICES" ] }, "target": { "type": "integer", "examples": [ 50 ] }, "auto_update_mode": { "type": "integer", "examples": [ 0 ] }, "rules": { "type": "array", "examples": [ [] ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "is_system": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_by": { "type": "integer", "examples": [ 1234 ] }, "uuid": { "type": "string", "examples": [ "270eebe1-bc48-4ecf-a065-2c5ff65b33b0" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:functional_area:1" ] } } } } } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } }, "examples": [ [ { "object": { "id": 1, "headcount_functional_area_id": 1, "name": "Information Desk Attendant", "frontend_name": "Information Desk Attendant", "code": "INFODESK", "description": "

Answers visitor questions at the information desk.

", "training_ids": [ 1 ], "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": { "object": { "id": 1, "account_id": 20101, "headcount_functional_area_type_id": 1, "name": "Guest Services", "frontend_name": "Guest Services", "code": "GUESTSERVICES", "target": 50, "auto_update_mode": 0, "rules": [], "training_ids": [ 1 ], "is_system": 0, "deleted_at": null, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:16.000000Z", "updated_by": 1234, "uuid": "270eebe1-bc48-4ecf-a065-2c5ff65b33b0" }, "nice": { "rrn": "rrn:local:20101:functional_area:1" } } }, "permissions": { "read": true, "update": true, "delete": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/headcount/functionalarea/{functionalarea}/jobtitle?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/headcount/functionalarea/{functionalarea}/jobtitle?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/headcount/functionalarea/{functionalarea}/jobtitle" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 1, "headcount_functional_area_id": 1, "name": "Information Desk Attendant", "frontend_name": "Information Desk Attendant", "code": "INFODESK", "description": "

Answers visitor questions at the information desk.

", "training_ids": [ 1 ], "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": { "object": { "id": 1, "account_id": 20101, "headcount_functional_area_type_id": 1, "name": "Guest Services", "frontend_name": "Guest Services", "code": "GUESTSERVICES", "target": 50, "auto_update_mode": 0, "rules": [], "training_ids": [ 1 ], "is_system": 0, "deleted_at": null, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:16.000000Z", "updated_by": 1234, "uuid": "270eebe1-bc48-4ecf-a065-2c5ff65b33b0" }, "nice": { "rrn": "rrn:local:20101:functional_area:1" } } }, "permissions": { "read": true, "update": true, "delete": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/headcount/functionalarea/{functionalarea}/jobtitle?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/headcount/functionalarea/{functionalarea}/jobtitle?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/headcount/functionalarea/{functionalarea}/jobtitle", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Headcount Module" ] }, "post": { "summary": "Create a job title", "operationId": "createAJobTitle", "description": "Adds a role under the functional area named in the URL. The parent is taken from\nthe URL, so it is not a body field and cannot be set by sending one.\n\n`code` has to be unique across the whole account, not just within this functional\narea, and is stored in upper case whatever case it is sent in.\n\n**The created role comes back without `deleted_at`**, which reading it includes.\nEverything else matches the read shape.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "headcount_functional_area_id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Information Desk Attendant" ] }, "frontend_name": { "type": "string", "examples": [ "Information Desk Attendant" ] }, "code": { "type": "string", "examples": [ "INFODESK" ] }, "description": { "type": "string", "examples": [ "

Answers visitor questions at the information desk.

" ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "uuid": { "type": "string", "examples": [ "e17404de-d3db-4e85-81ee-4552d19da8c4" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:job_title:1" ] }, "functional_area_name": { "type": "string", "examples": [ "Guest Services" ] } } }, "relations": { "type": "object", "properties": { "functional_area": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "headcount_functional_area_type_id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Guest Services" ] }, "frontend_name": { "type": "string", "examples": [ "Guest Services" ] }, "code": { "type": "string", "examples": [ "GUESTSERVICES" ] }, "target": { "type": "integer", "examples": [ 50 ] }, "auto_update_mode": { "type": "integer", "examples": [ 0 ] }, "rules": { "type": "array", "examples": [ [] ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "is_system": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_by": { "type": "integer", "examples": [ 1234 ] }, "uuid": { "type": "string", "examples": [ "270eebe1-bc48-4ecf-a065-2c5ff65b33b0" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:functional_area:1" ] } } } } } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "headcount_functional_area_id": 1, "name": "Information Desk Attendant", "frontend_name": "Information Desk Attendant", "code": "INFODESK", "description": "

Answers visitor questions at the information desk.

", "training_ids": [ 1 ], "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": { "object": { "id": 1, "account_id": 20101, "headcount_functional_area_type_id": 1, "name": "Guest Services", "frontend_name": "Guest Services", "code": "GUESTSERVICES", "target": 50, "auto_update_mode": 0, "rules": [], "training_ids": [ 1 ], "is_system": 0, "deleted_at": null, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:16.000000Z", "updated_by": 1234, "uuid": "270eebe1-bc48-4ecf-a065-2c5ff65b33b0" }, "nice": { "rrn": "rrn:local:20101:functional_area:1" } } }, "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Headcount Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name administrators see. Required.", "examples": [ "Information Desk Attendant" ] }, "frontend_name": { "type": "string", "description": "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.", "examples": [ "Information Desk Attendant" ] }, "code": { "type": "string", "description": "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.", "examples": [ "INFODESK" ] }, "description": { "type": "string", "description": "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.", "examples": [ "

Answers visitor questions at the information desk.

" ] }, "training_ids": { "type": "array", "description": "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.", "items": { "type": "integer" }, "examples": [ [ 1 ] ] } }, "required": [ "name", "frontend_name", "code" ] } } } } }, "parameters": [ { "in": "path", "name": "functionalarea_id", "description": "The ID of the functional area.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/headcount/functionalarea/{functionalarea_id}/jobtitle/{id}": { "get": { "summary": "Read a job title", "operationId": "readAJobTitle", "description": "Returns one role with its description and the training assigned to whoever takes it\non. `relations.functional_area` carries the parent group in full, so a separate call\nis not needed to see which group the role belongs to.\n\nThe role must belong to the functional area named in the URL; asking for one under\na different group is not found.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "headcount_functional_area_id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Information Desk Attendant" ] }, "frontend_name": { "type": "string", "examples": [ "Information Desk Attendant" ] }, "code": { "type": "string", "examples": [ "INFODESK" ] }, "description": { "type": "string", "examples": [ "

Answers visitor questions at the information desk.

" ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "uuid": { "type": "string", "examples": [ "e17404de-d3db-4e85-81ee-4552d19da8c4" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:job_title:1" ] }, "functional_area_name": { "type": "string", "examples": [ "Guest Services" ] } } }, "relations": { "type": "object", "properties": { "functional_area": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "headcount_functional_area_type_id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Guest Services" ] }, "frontend_name": { "type": "string", "examples": [ "Guest Services" ] }, "code": { "type": "string", "examples": [ "GUESTSERVICES" ] }, "target": { "type": "integer", "examples": [ 50 ] }, "auto_update_mode": { "type": "integer", "examples": [ 0 ] }, "rules": { "type": "array", "examples": [ [] ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "is_system": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_by": { "type": "integer", "examples": [ 1234 ] }, "uuid": { "type": "string", "examples": [ "270eebe1-bc48-4ecf-a065-2c5ff65b33b0" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:functional_area:1" ] } } } } } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "headcount_functional_area_id": 1, "name": "Information Desk Attendant", "frontend_name": "Information Desk Attendant", "code": "INFODESK", "description": "

Answers visitor questions at the information desk.

", "training_ids": [ 1 ], "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": { "object": { "id": 1, "account_id": 20101, "headcount_functional_area_type_id": 1, "name": "Guest Services", "frontend_name": "Guest Services", "code": "GUESTSERVICES", "target": 50, "auto_update_mode": 0, "rules": [], "training_ids": [ 1 ], "is_system": 0, "deleted_at": null, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:16.000000Z", "updated_by": 1234, "uuid": "270eebe1-bc48-4ecf-a065-2c5ff65b33b0" }, "nice": { "rrn": "rrn:local:20101:functional_area:1" } } }, "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Headcount Module" ] }, "put": { "summary": "Update a job title", "operationId": "updateAJobTitle", "description": "Updates the fields supplied and returns the role in the same shape as reading it.\nOnly the fields sent are touched, so an empty body is a valid request that changes\nnothing, and omitting `training_ids` leaves the assigned training alone rather than\nclearing it.\n\nThe role stays under the functional area it was created in; this endpoint does not\nmove it.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "headcount_functional_area_id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Information Desk Attendant" ] }, "frontend_name": { "type": "string", "examples": [ "Information Desk Attendant" ] }, "code": { "type": "string", "examples": [ "INFODESK" ] }, "description": { "type": "string", "examples": [ "

Answers visitor questions at the information desk.

" ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "uuid": { "type": "string", "examples": [ "e17404de-d3db-4e85-81ee-4552d19da8c4" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:job_title:1" ] }, "functional_area_name": { "type": "string", "examples": [ "Guest Services" ] } } }, "relations": { "type": "object", "properties": { "functional_area": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "headcount_functional_area_type_id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Guest Services" ] }, "frontend_name": { "type": "string", "examples": [ "Guest Services" ] }, "code": { "type": "string", "examples": [ "GUESTSERVICES" ] }, "target": { "type": "integer", "examples": [ 50 ] }, "auto_update_mode": { "type": "integer", "examples": [ 0 ] }, "rules": { "type": "array", "examples": [ [] ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "is_system": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_by": { "type": "integer", "examples": [ 1234 ] }, "uuid": { "type": "string", "examples": [ "270eebe1-bc48-4ecf-a065-2c5ff65b33b0" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:functional_area:1" ] } } } } } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "headcount_functional_area_id": 1, "name": "Information Desk Attendant", "frontend_name": "Information Desk Attendant", "code": "INFODESK", "description": "

Answers visitor questions at the information desk.

", "training_ids": [ 1 ], "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": { "object": { "id": 1, "account_id": 20101, "headcount_functional_area_type_id": 1, "name": "Guest Services", "frontend_name": "Guest Services", "code": "GUESTSERVICES", "target": 50, "auto_update_mode": 0, "rules": [], "training_ids": [ 1 ], "is_system": 0, "deleted_at": null, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:16.000000Z", "updated_by": 1234, "uuid": "270eebe1-bc48-4ecf-a065-2c5ff65b33b0" }, "nice": { "rrn": "rrn:local:20101:functional_area:1" } } }, "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Headcount Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name administrators see. Required.", "examples": [ "Information Desk Attendant" ] }, "frontend_name": { "type": "string", "description": "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.", "examples": [ "Information Desk Attendant" ] }, "code": { "type": "string", "description": "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.", "examples": [ "INFODESK" ] }, "description": { "type": "string", "description": "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.", "examples": [ "

Answers visitor questions at the information desk.

" ] }, "training_ids": { "type": "array", "description": "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.", "items": { "type": "integer" }, "examples": [ [ 1 ] ] } } } } } } }, "delete": { "summary": "Delete a job title", "operationId": "deleteAJobTitle", "description": "Removes the role. The record is retained internally so past reporting is not lost,\nbut the role can no longer be read or edited and no endpoint restores it.\n\n**A role that is still recruiting cannot be deleted** - close or reassign its\nrecruitment first.\n\nReturns `200` with a `messages` field rather than an empty `204`. `messages` carries\nanything the platform wants to tell you about the deletion and is `null` when there\nis nothing to say.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": [ "string", "null" ], "examples": [ null ] } }, "examples": [ { "messages": null } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Headcount Module" ] }, "parameters": [ { "in": "path", "name": "functionalarea_id", "description": "The ID of the functional area.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } }, { "in": "path", "name": "id", "description": "The ID of the job title.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/headcount/functionalarea/type": { "get": { "summary": "List functional area types", "operationId": "listFunctionalAreaTypes", "description": "Returns the categories the account files its functional areas under, in the order\n`sort_order` puts them.\n\nThe listing is only paginated when `page` is supplied. Without it every match is\nreturned as a flat array rather than in the paged envelope.", "parameters": [ { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Operations" ] }, "sort_order": { "type": "integer", "examples": [ 1 ] }, "uuid": { "type": "string", "examples": [ "f5d2192c-e3b6-4162-8e6c-5bc6f65900e9" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } }, "examples": [ [ { "object": { "id": 1, "name": "Operations", "sort_order": 1, "uuid": "f5d2192c-e3b6-4162-8e6c-5bc6f65900e9" }, "nice": [], "relations": [], "permissions": { "read": true, "update": true, "delete": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/headcount/functionalarea/type?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/headcount/functionalarea/type?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/headcount/functionalarea/type" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 1, "name": "Operations", "sort_order": 1, "uuid": "f5d2192c-e3b6-4162-8e6c-5bc6f65900e9" }, "nice": [], "relations": [], "permissions": { "read": true, "update": true, "delete": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/headcount/functionalarea/type?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/headcount/functionalarea/type?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/headcount/functionalarea/type", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Headcount Module" ] }, "post": { "summary": "Create a functional area type", "operationId": "createAFunctionalAreaType", "description": "Adds a category that functional areas can be filed under. Point a functional area\nat it with `headcount_functional_area_type_id` on the create or update endpoint for\nthat area.\n\n**A type created without `sort_order` comes back without that field**, rather than\nwith its stored default of `0`. Read the type back if you need its complete state.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Operations" ] }, "sort_order": { "type": "integer", "examples": [ 1 ] }, "uuid": { "type": "string", "examples": [ "f5d2192c-e3b6-4162-8e6c-5bc6f65900e9" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "name": "Operations", "sort_order": 1, "uuid": "f5d2192c-e3b6-4162-8e6c-5bc6f65900e9" }, "nice": [], "relations": [], "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Headcount Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the group type. Required. Sending a plain string sets the name for the account's default language; it is returned as a plain string in the language of the request.", "examples": [ "Operations" ] }, "sort_order": { "type": "integer", "description": "Where this type sits when types are listed together. Lower values come first, and types sharing a value keep no guaranteed order between them. Defaults to `0`.", "examples": [ 1 ] } }, "required": [ "name" ] } } } } } }, "/api/v2/headcount/functionalarea/type/{id}": { "get": { "summary": "Read a functional area type", "operationId": "readAFunctionalAreaType", "description": "Returns one category with its name and sort position.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Operations" ] }, "sort_order": { "type": "integer", "examples": [ 1 ] }, "uuid": { "type": "string", "examples": [ "f5d2192c-e3b6-4162-8e6c-5bc6f65900e9" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "name": "Operations", "sort_order": 1, "uuid": "f5d2192c-e3b6-4162-8e6c-5bc6f65900e9" }, "nice": [], "relations": [], "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Headcount Module" ] }, "put": { "summary": "Update a functional area type", "operationId": "updateAFunctionalAreaType", "description": "Updates the fields supplied and returns the type in the same shape as reading it.\nOnly the fields sent are touched, so an empty body is a valid request that changes\nnothing.\n\nRenaming a type does not affect which functional areas are filed under it.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Operations" ] }, "sort_order": { "type": "integer", "examples": [ 1 ] }, "uuid": { "type": "string", "examples": [ "f5d2192c-e3b6-4162-8e6c-5bc6f65900e9" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "name": "Operations", "sort_order": 1, "uuid": "f5d2192c-e3b6-4162-8e6c-5bc6f65900e9" }, "nice": [], "relations": [], "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Headcount Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the group type. Required. Sending a plain string sets the name for the account's default language; it is returned as a plain string in the language of the request.", "examples": [ "Operations" ] }, "sort_order": { "type": "integer", "description": "Where this type sits when types are listed together. Lower values come first, and types sharing a value keep no guaranteed order between them. Defaults to `0`.", "examples": [ 1 ] } } } } } } }, "delete": { "summary": "Delete a functional area type", "operationId": "deleteAFunctionalAreaType", "description": "Removes the category. The record is retained internally so past reporting is not\nlost, but the type can no longer be read or edited and no endpoint restores it.\n\nFunctional areas filed under it are **not** deleted and keep pointing at the\nremoved type, so reassign them first if they should stay categorised.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "204": { "description": "No content, successful deletion", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Headcount Module" ] }, "parameters": [ { "in": "path", "name": "id", "description": "The ID of the functional area type.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/headcount/functionalarea/{functionalarea_id}/user/mass-create": { "post": { "summary": "Add people to a functional area", "operationId": "addPeopleToAFunctionalArea", "description": "Adds a list of people to the functional area named in the URL, all with the same\nmembership status. The work is queued rather than done while you wait, so a `200`\nmeans the request was accepted, not that anyone has been added yet.\n\n**Send this request as form-encoded parameters, not as a JSON body.** A JSON body\nis not read for `selected`, and the request is reported as not found.\n\nPeople who cannot be added are skipped rather than reported: IDs that do not\nresolve, people in another account, and anyone already in the group. The response\ndoes not say how many were added, and the `queue` value it returns is a correlation\nreference that no endpoint resolves - **there is nothing to poll**. Confirm the\noutcome by listing the group's members.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "queue": { "type": "string", "examples": [ "mTsVQ1NCLS3vg7WwP5kG1Vbt" ] } }, "examples": [ { "queue": "mTsVQ1NCLS3vg7WwP5kG1Vbt" } ] } } } } }, "tags": [ "Headcount Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "selected": { "type": "array", "description": "The IDs of the people to add to the group. Required - a request without it is not found rather than rejected as invalid. IDs that do not resolve, belong to another account, or are already in the group are skipped without being reported.", "items": { "type": "integer" }, "examples": [ [] ] }, "status": { "type": "string", "description": "The membership status each person is added with: `pending`, `accepted` or `rejected`. Required, and any other value is rejected.", "examples": [ null ] }, "applyTo": { "type": "string", "description": "Required, and conventionally `selected`. This endpoint always adds exactly the people listed in `selected`, so the value sent does not change what happens - but the request is rejected if the field is missing. Note the camelCase name, which is deliberate here and differs from the snake_case used elsewhere.", "examples": [ null ] } }, "required": [ "selected", "status", "applyTo" ] } } } } }, "parameters": [ { "in": "path", "name": "functionalarea_id", "description": "The ID of the functional area.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/headcount/location": { "get": { "summary": "List locations", "operationId": "listLocations", "description": "Returns the locations the account holds - the places it recruits and rosters people\nto, each of which groups one or more venues.\n\nThe listing is only paginated when `page` is supplied. Without it every match is\nreturned as a flat array rather than in the paged envelope.", "parameters": [ { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "query", "name": "extras", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "required": false, "schema": { "type": "array", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "items": { "type": "string", "enum": [ "demand" ] }, "examples": [ [ "demand" ] ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "headcount_location_type_id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Main Campus" ] }, "frontend_name": { "type": "string", "examples": [ "Main Campus" ] }, "code": { "type": "string", "examples": [ "MAINCAMPUS" ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "is_system": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "uuid": { "type": "string", "examples": [ "ec98790e-5bab-4ad7-9357-31556e2efbc4" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:location:1" ] }, "headcount_location_type_name": { "type": "string", "examples": [ "Stadium" ] } } }, "relations": { "type": "object", "properties": { "headcount_location_type": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Stadium" ] }, "sort_order": { "type": "integer", "examples": [ 1 ] }, "uuid": { "type": "string", "examples": [ "bf46e175-87a9-4968-8e58-21efec6873a2" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } }, "examples": [ [ { "object": { "id": 1, "account_id": 20101, "headcount_location_type_id": 1, "name": "Main Campus", "frontend_name": "Main Campus", "code": "MAINCAMPUS", "training_ids": [ 1 ], "is_system": 0, "deleted_at": null, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:16.000000Z", "uuid": "ec98790e-5bab-4ad7-9357-31556e2efbc4" }, "nice": { "rrn": "rrn:local:20101:location:1", "headcount_location_type_name": "Stadium" }, "relations": { "headcount_location_type": { "object": { "id": 1, "name": "Stadium", "sort_order": 1, "uuid": "bf46e175-87a9-4968-8e58-21efec6873a2" }, "nice": [], "permissions": { "read": true, "update": true, "delete": true } } }, "permissions": { "read": true, "update": true, "delete": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/headcount/location?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/headcount/location?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/headcount/location" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 1, "account_id": 20101, "headcount_location_type_id": 1, "name": "Main Campus", "frontend_name": "Main Campus", "code": "MAINCAMPUS", "training_ids": [ 1 ], "is_system": 0, "deleted_at": null, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:16.000000Z", "uuid": "ec98790e-5bab-4ad7-9357-31556e2efbc4" }, "nice": { "rrn": "rrn:local:20101:location:1", "headcount_location_type_name": "Stadium" }, "relations": { "headcount_location_type": { "object": { "id": 1, "name": "Stadium", "sort_order": 1, "uuid": "bf46e175-87a9-4968-8e58-21efec6873a2" }, "nice": [], "permissions": { "read": true, "update": true, "delete": true } } }, "permissions": { "read": true, "update": true, "delete": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/headcount/location?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/headcount/location?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/headcount/location", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Headcount Module" ] }, "post": { "summary": "Create a location", "operationId": "createALocation", "description": "Sets up a new place to recruit and roster people to. Venues are then created under\nit, and roles are advertised against those venues rather than against the location\nitself.\n\n`code` has to be unique within the account and is stored in upper case whatever case\nit is sent in, so `mainstadium` and `MAINSTADIUM` are the same code.\n\n**The created location comes back with only the fields that were set on it**, not\nthe full record that reading it returns: anything left to its stored default is\nabsent rather than present and defaulted. Read the location back if you need its\ncomplete state.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "name": { "type": "string", "examples": [ "Main Campus" ] }, "frontend_name": { "type": "string", "examples": [ "Main Campus" ] }, "headcount_location_type_id": { "type": "integer", "examples": [ 1 ] }, "code": { "type": "string", "examples": [ "MAINCAMPUS" ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "uuid": { "type": "string", "examples": [ "ec98790e-5bab-4ad7-9357-31556e2efbc4" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "id": { "type": "integer", "examples": [ 1 ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:location:1" ] }, "headcount_location_type_name": { "type": "string", "examples": [ "Stadium" ] } } }, "relations": { "type": "object", "properties": { "headcount_location_type": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Stadium" ] }, "sort_order": { "type": "integer", "examples": [ 1 ] }, "uuid": { "type": "string", "examples": [ "bf46e175-87a9-4968-8e58-21efec6873a2" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "name": "Main Campus", "frontend_name": "Main Campus", "headcount_location_type_id": 1, "code": "MAINCAMPUS", "training_ids": [ 1 ], "account_id": 20101, "uuid": "ec98790e-5bab-4ad7-9357-31556e2efbc4", "updated_at": "2026-06-09T05:36:16.000000Z", "created_at": "2026-06-09T05:36:16.000000Z", "id": 1 }, "nice": { "rrn": "rrn:local:20101:location:1", "headcount_location_type_name": "Stadium" }, "relations": { "headcount_location_type": { "object": { "id": 1, "name": "Stadium", "sort_order": 1, "uuid": "bf46e175-87a9-4968-8e58-21efec6873a2" }, "nice": [], "permissions": { "read": true, "update": true, "delete": true } } }, "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Headcount Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name administrators see. Required.", "examples": [ "Main Campus" ] }, "frontend_name": { "type": "string", "description": "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.", "examples": [ "Main Campus" ] }, "code": { "type": "string", "description": "A short reference for the location, unique within the account regardless of case. Letters, numbers, dashes and underscores only - spaces and punctuation are rejected. Stored and returned in upper case whatever case it is sent in.", "examples": [ "MAINCAMPUS" ] }, "headcount_location_type_id": { "type": "integer", "description": "The ID of the location type to file this location under. Optional; omit or send null to leave the location untyped. Must be the ID of a type the account holds.", "examples": [ 1 ] }, "training_ids": { "type": "array", "description": "The IDs of the training modules assigned to anyone who accepts a role at this location. **Replaces the whole list** rather than adding to it, so send every module you want kept. Omitting the field leaves the stored list untouched.", "items": { "type": "integer" }, "examples": [ [ 1 ] ] } }, "required": [ "name", "frontend_name", "code" ] } } } } } }, "/api/v2/headcount/location/{id}": { "get": { "summary": "Read a location", "operationId": "readALocation", "description": "Returns one location with its code, the type it is filed under and the training\nassigned to anyone who accepts a role there.\n\n`permissions.delete` reflects whether this particular location can be removed, which\ndepends on whether roles are still recruiting at its venues.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "headcount_location_type_id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Main Campus" ] }, "frontend_name": { "type": "string", "examples": [ "Main Campus" ] }, "code": { "type": "string", "examples": [ "MAINCAMPUS" ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "is_system": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "uuid": { "type": "string", "examples": [ "ec98790e-5bab-4ad7-9357-31556e2efbc4" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:location:1" ] }, "headcount_location_type_name": { "type": "string", "examples": [ "Stadium" ] } } }, "relations": { "type": "object", "properties": { "headcount_location_type": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Stadium" ] }, "sort_order": { "type": "integer", "examples": [ 1 ] }, "uuid": { "type": "string", "examples": [ "bf46e175-87a9-4968-8e58-21efec6873a2" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "account_id": 20101, "headcount_location_type_id": 1, "name": "Main Campus", "frontend_name": "Main Campus", "code": "MAINCAMPUS", "training_ids": [ 1 ], "is_system": 0, "deleted_at": null, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:16.000000Z", "uuid": "ec98790e-5bab-4ad7-9357-31556e2efbc4" }, "nice": { "rrn": "rrn:local:20101:location:1", "headcount_location_type_name": "Stadium" }, "relations": { "headcount_location_type": { "object": { "id": 1, "name": "Stadium", "sort_order": 1, "uuid": "bf46e175-87a9-4968-8e58-21efec6873a2" }, "nice": [], "permissions": { "read": true, "update": true, "delete": true } } }, "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Headcount Module" ] }, "put": { "summary": "Update a location", "operationId": "updateALocation", "description": "Updates the fields supplied and returns the location in the same shape as reading\nit. Only the fields sent are touched, so an empty body is a valid request that\nchanges nothing.\n\nRenaming a location does not affect the venues under it or the roles advertised at\nthose venues.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "headcount_location_type_id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Main Campus" ] }, "frontend_name": { "type": "string", "examples": [ "Main Campus" ] }, "code": { "type": "string", "examples": [ "MAINCAMPUS" ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "is_system": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "uuid": { "type": "string", "examples": [ "ec98790e-5bab-4ad7-9357-31556e2efbc4" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:location:1" ] }, "headcount_location_type_name": { "type": "string", "examples": [ "Stadium" ] } } }, "relations": { "type": "object", "properties": { "headcount_location_type": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Stadium" ] }, "sort_order": { "type": "integer", "examples": [ 1 ] }, "uuid": { "type": "string", "examples": [ "bf46e175-87a9-4968-8e58-21efec6873a2" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "account_id": 20101, "headcount_location_type_id": 1, "name": "Main Campus", "frontend_name": "Main Campus", "code": "MAINCAMPUS", "training_ids": [ 1 ], "is_system": 0, "deleted_at": null, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:16.000000Z", "uuid": "ec98790e-5bab-4ad7-9357-31556e2efbc4" }, "nice": { "rrn": "rrn:local:20101:location:1", "headcount_location_type_name": "Stadium" }, "relations": { "headcount_location_type": { "object": { "id": 1, "name": "Stadium", "sort_order": 1, "uuid": "bf46e175-87a9-4968-8e58-21efec6873a2" }, "nice": [], "permissions": { "read": true, "update": true, "delete": true } } }, "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Headcount Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name administrators see. Required.", "examples": [ "Main Campus" ] }, "frontend_name": { "type": "string", "description": "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.", "examples": [ "Main Campus" ] }, "code": { "type": "string", "description": "A short reference for the location, unique within the account regardless of case. Letters, numbers, dashes and underscores only - spaces and punctuation are rejected. Stored and returned in upper case whatever case it is sent in.", "examples": [ "MAINCAMPUS" ] }, "headcount_location_type_id": { "type": "integer", "description": "The ID of the location type to file this location under. Optional; omit or send null to leave the location untyped. Must be the ID of a type the account holds.", "examples": [ 1 ] }, "training_ids": { "type": "array", "description": "The IDs of the training modules assigned to anyone who accepts a role at this location. **Replaces the whole list** rather than adding to it, so send every module you want kept. Omitting the field leaves the stored list untouched.", "items": { "type": "integer" }, "examples": [ [ 1 ] ] } } } } } } }, "delete": { "summary": "Delete a location", "operationId": "deleteALocation", "description": "Removes the location. The record is retained internally so past reporting is not\nlost, but the location can no longer be read or edited and no endpoint restores it.\n\n**A location with roles still recruiting at any of its venues cannot be deleted** -\nremove or reassign those roles first. The same applies to the account's built-in\ndefault location, which is not removable at all.\n\n**The venues under it are not deleted, but they do become unreachable**: every venue\nendpoint resolves a venue through its location, so once the location is gone its\nvenues stop appearing in venue listings and can no longer be read, updated or\nremoved. Move or delete the venues first if you need them to stay available.\n\nReturns `200` with a `messages` field rather than an empty `204`. `messages` carries\nanything the platform wants to tell you about the deletion and is `null` when there\nis nothing to say.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": [ "string", "null" ], "examples": [ null ] } }, "examples": [ { "messages": null } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Headcount Module" ] }, "parameters": [ { "in": "path", "name": "id", "description": "The ID of the location.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/headcount/location/{location_id}/venue": { "get": { "summary": "List a location's venues", "operationId": "listALocationsVenues", "description": "Returns the venues filed under one location - the addressable places within it that\nroles are advertised at.\n\nThe listing is only paginated when `page` is supplied. Without it every match is\nreturned as a flat array rather than in the paged envelope.", "parameters": [ { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "query", "name": "extras", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "required": false, "schema": { "type": "array", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "items": { "type": "string", "enum": [ "demand" ] }, "examples": [ [ "demand" ] ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "headcount_location_id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "North Gate" ] }, "frontend_name": { "type": "string", "examples": [ "North Gate" ] }, "code": { "type": "string", "examples": [ "NORTHGATE" ] }, "is_virtual": { "type": "integer", "examples": [ 0 ] }, "description": { "type": "string", "examples": [ "

Main pedestrian entrance.

" ] }, "is_system": { "type": "integer", "examples": [ 0 ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "uuid": { "type": "string", "examples": [ "f64e8d2b-7f0d-42fb-91bc-98a098a7f191" ] }, "address": { "type": "object", "properties": { "iso": { "type": "string", "examples": [ "AUS" ] }, "region_code": { "type": "string", "examples": [ "Example Region" ] }, "coordinates": { "type": "object", "properties": { "latitude": { "type": [ "string", "null" ], "examples": [ null ] }, "longitude": { "type": [ "string", "null" ], "examples": [ null ] } } }, "street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "city": { "type": "string", "examples": [ "Example City" ] }, "postcode": { "type": "string", "examples": [ "1000" ] }, "region": { "type": "string", "examples": [ "Example Region" ] }, "country": { "type": "string", "examples": [ "AU" ] }, "latitude": { "type": [ "string", "null" ], "examples": [ null ] }, "longitude": { "type": [ "string", "null" ], "examples": [ null ] } } } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:venue:1" ] }, "address": { "type": "string", "examples": [ "1 Example Street\nExample City\nExample Region\nAustralia\n1000" ] }, "address_oneline": { "type": "string", "examples": [ "1 Example Street, Example City, Example Region, Australia, 1000" ] }, "address.country": { "type": "string", "examples": [ "Australia" ] }, "address.country:raw": { "type": "string", "examples": [ "AUS" ] }, "address.city": { "type": "string", "examples": [ "Example City" ] }, "address.region": { "type": "string", "examples": [ "Example Region" ] }, "address.region:raw": { "type": "string", "examples": [ "Example Region" ] }, "address.postcode": { "type": "string", "examples": [ "1000" ] }, "address.street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "address.street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "address.street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "address.latitude": { "type": [ "string", "null" ], "examples": [ null ] }, "address.longitude": { "type": [ "string", "null" ], "examples": [ null ] }, "location_name": { "type": "string", "examples": [ "Main Campus" ] }, "headcount_location_type_name": { "type": "string", "examples": [ "Stadium" ] }, "headcount_location_type_id": { "type": "integer", "examples": [ 1 ] } } }, "relations": { "type": "object", "properties": { "location": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "headcount_location_type_id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Main Campus" ] }, "frontend_name": { "type": "string", "examples": [ "Main Campus" ] }, "code": { "type": "string", "examples": [ "MAINCAMPUS" ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "is_system": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "uuid": { "type": "string", "examples": [ "ec98790e-5bab-4ad7-9357-31556e2efbc4" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:location:1" ] }, "headcount_location_type_name": { "type": "string", "examples": [ "Stadium" ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } }, "examples": [ [ { "object": { "id": 1, "headcount_location_id": 1, "name": "North Gate", "frontend_name": "North Gate", "code": "NORTHGATE", "is_virtual": 0, "description": "

Main pedestrian entrance.

", "is_system": 0, "training_ids": [ 1 ], "deleted_at": null, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:16.000000Z", "uuid": "f64e8d2b-7f0d-42fb-91bc-98a098a7f191", "address": { "iso": "AUS", "region_code": "Example Region", "coordinates": { "latitude": null, "longitude": null }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "Example City", "postcode": "1000", "region": "Example Region", "country": "AU", "latitude": null, "longitude": null } }, "nice": { "rrn": "rrn:local:20101:venue:1", "address": "1 Example Street\nExample City\nExample Region\nAustralia\n1000", "address_oneline": "1 Example Street, Example City, Example Region, Australia, 1000", "address.country": "Australia", "address.country:raw": "AUS", "address.city": "Example City", "address.region": "Example Region", "address.region:raw": "Example Region", "address.postcode": "1000", "address.street_address_1": "1 Example Street", "address.street_address_2": null, "address.street_address_3": null, "address.latitude": null, "address.longitude": null, "location_name": "Main Campus", "headcount_location_type_name": "Stadium", "headcount_location_type_id": 1 }, "relations": { "location": { "object": { "id": 1, "account_id": 20101, "headcount_location_type_id": 1, "name": "Main Campus", "frontend_name": "Main Campus", "code": "MAINCAMPUS", "training_ids": [ 1 ], "is_system": 0, "deleted_at": null, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:16.000000Z", "uuid": "ec98790e-5bab-4ad7-9357-31556e2efbc4" }, "nice": { "rrn": "rrn:local:20101:location:1", "headcount_location_type_name": "Stadium" }, "permissions": { "read": true, "update": true, "delete": true } } }, "permissions": { "read": true, "update": true, "delete": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/headcount/location/{location}/venue?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/headcount/location/{location}/venue?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/headcount/location/{location}/venue" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 1, "headcount_location_id": 1, "name": "North Gate", "frontend_name": "North Gate", "code": "NORTHGATE", "is_virtual": 0, "description": "

Main pedestrian entrance.

", "is_system": 0, "training_ids": [ 1 ], "deleted_at": null, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:16.000000Z", "uuid": "f64e8d2b-7f0d-42fb-91bc-98a098a7f191", "address": { "iso": "AUS", "region_code": "Example Region", "coordinates": { "latitude": null, "longitude": null }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "Example City", "postcode": "1000", "region": "Example Region", "country": "AU", "latitude": null, "longitude": null } }, "nice": { "rrn": "rrn:local:20101:venue:1", "address": "1 Example Street\nExample City\nExample Region\nAustralia\n1000", "address_oneline": "1 Example Street, Example City, Example Region, Australia, 1000", "address.country": "Australia", "address.country:raw": "AUS", "address.city": "Example City", "address.region": "Example Region", "address.region:raw": "Example Region", "address.postcode": "1000", "address.street_address_1": "1 Example Street", "address.street_address_2": null, "address.street_address_3": null, "address.latitude": null, "address.longitude": null, "location_name": "Main Campus", "headcount_location_type_name": "Stadium", "headcount_location_type_id": 1 }, "relations": { "location": { "object": { "id": 1, "account_id": 20101, "headcount_location_type_id": 1, "name": "Main Campus", "frontend_name": "Main Campus", "code": "MAINCAMPUS", "training_ids": [ 1 ], "is_system": 0, "deleted_at": null, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:16.000000Z", "uuid": "ec98790e-5bab-4ad7-9357-31556e2efbc4" }, "nice": { "rrn": "rrn:local:20101:location:1", "headcount_location_type_name": "Stadium" }, "permissions": { "read": true, "update": true, "delete": true } } }, "permissions": { "read": true, "update": true, "delete": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/headcount/location/{location}/venue?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/headcount/location/{location}/venue?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/headcount/location/{location}/venue", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Headcount Module" ] }, "post": { "summary": "Create a venue", "operationId": "createAVenue", "description": "Adds an addressable place under the location in the path. Roles are advertised\nagainst venues rather than against the location itself, so a location needs at least\none before it can be recruited for.\n\nSend `address` unless the venue is virtual. An address is not mandatory - a venue can\nbe created without one and given it later - but a venue with no address and\n`is_virtual` unset is excluded from proximity searches until one is added.\n\n**`description` is not read on create.** It is accepted by the update endpoint only;\na create that sends it returns `201` with the description unset. Add it in a\nfollow-up update.\n\n**The created venue comes back with only the fields that were set on it**, not the\nfull record that reading it returns. Read the venue back if you need its complete\nstate.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "name": { "type": "string", "examples": [ "North Gate" ] }, "frontend_name": { "type": "string", "examples": [ "North Gate" ] }, "code": { "type": "string", "examples": [ "NORTHGATE" ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "is_virtual": { "type": "integer", "examples": [ 0 ] }, "headcount_location_id": { "type": "integer", "examples": [ 1 ] }, "uuid": { "type": "string", "examples": [ "f64e8d2b-7f0d-42fb-91bc-98a098a7f191" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "id": { "type": "integer", "examples": [ 1 ] }, "address": { "type": "object", "properties": { "iso": { "type": "string", "examples": [ "AUS" ] }, "region_code": { "type": "string", "examples": [ "Example Region" ] }, "coordinates": { "type": "object", "properties": { "latitude": { "type": [ "string", "null" ], "examples": [ null ] }, "longitude": { "type": [ "string", "null" ], "examples": [ null ] } } }, "street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "city": { "type": "string", "examples": [ "Example City" ] }, "region": { "type": "string", "examples": [ "Example Region" ] }, "postcode": { "type": "string", "examples": [ "1000" ] }, "country": { "type": "string", "examples": [ "AU" ] }, "latitude": { "type": [ "string", "null" ], "examples": [ null ] }, "longitude": { "type": [ "string", "null" ], "examples": [ null ] } } } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:venue:1" ] }, "address": { "type": "string", "examples": [ "1 Example Street\nExample City\nExample Region\nAustralia\n1000" ] }, "address_oneline": { "type": "string", "examples": [ "1 Example Street, Example City, Example Region, Australia, 1000" ] }, "address.country": { "type": "string", "examples": [ "Australia" ] }, "address.country:raw": { "type": "string", "examples": [ "AUS" ] }, "address.city": { "type": "string", "examples": [ "Example City" ] }, "address.region": { "type": "string", "examples": [ "Example Region" ] }, "address.region:raw": { "type": "string", "examples": [ "Example Region" ] }, "address.postcode": { "type": "string", "examples": [ "1000" ] }, "address.street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "address.street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "address.street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "address.latitude": { "type": [ "string", "null" ], "examples": [ null ] }, "address.longitude": { "type": [ "string", "null" ], "examples": [ null ] }, "location_name": { "type": "string", "examples": [ "Main Campus" ] }, "headcount_location_type_name": { "type": "string", "examples": [ "Stadium" ] }, "headcount_location_type_id": { "type": "integer", "examples": [ 1 ] } } }, "relations": { "type": "object", "properties": { "location": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "headcount_location_type_id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Main Campus" ] }, "frontend_name": { "type": "string", "examples": [ "Main Campus" ] }, "code": { "type": "string", "examples": [ "MAINCAMPUS" ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "is_system": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "uuid": { "type": "string", "examples": [ "ec98790e-5bab-4ad7-9357-31556e2efbc4" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:location:1" ] }, "headcount_location_type_name": { "type": "string", "examples": [ "Stadium" ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "name": "North Gate", "frontend_name": "North Gate", "code": "NORTHGATE", "training_ids": [ 1 ], "is_virtual": 0, "headcount_location_id": 1, "uuid": "f64e8d2b-7f0d-42fb-91bc-98a098a7f191", "updated_at": "2026-06-09T05:36:16.000000Z", "created_at": "2026-06-09T05:36:16.000000Z", "id": 1, "address": { "iso": "AUS", "region_code": "Example Region", "coordinates": { "latitude": null, "longitude": null }, "street_address_1": "1 Example Street", "city": "Example City", "region": "Example Region", "postcode": "1000", "country": "AU", "latitude": null, "longitude": null } }, "nice": { "rrn": "rrn:local:20101:venue:1", "address": "1 Example Street\nExample City\nExample Region\nAustralia\n1000", "address_oneline": "1 Example Street, Example City, Example Region, Australia, 1000", "address.country": "Australia", "address.country:raw": "AUS", "address.city": "Example City", "address.region": "Example Region", "address.region:raw": "Example Region", "address.postcode": "1000", "address.street_address_1": "1 Example Street", "address.street_address_2": null, "address.street_address_3": null, "address.latitude": null, "address.longitude": null, "location_name": "Main Campus", "headcount_location_type_name": "Stadium", "headcount_location_type_id": 1 }, "relations": { "location": { "object": { "id": 1, "account_id": 20101, "headcount_location_type_id": 1, "name": "Main Campus", "frontend_name": "Main Campus", "code": "MAINCAMPUS", "training_ids": [ 1 ], "is_system": 0, "deleted_at": null, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:16.000000Z", "uuid": "ec98790e-5bab-4ad7-9357-31556e2efbc4" }, "nice": { "rrn": "rrn:local:20101:location:1", "headcount_location_type_name": "Stadium" }, "permissions": { "read": true, "update": true, "delete": true } } }, "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Headcount Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name administrators see. Required.", "examples": [ "North Gate" ] }, "frontend_name": { "type": "string", "description": "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.", "examples": [ "North Gate" ] }, "code": { "type": "string", "description": "A short reference for the venue. Letters, numbers, commas, dashes and underscores only - spaces and other punctuation are rejected. Accounts configured to require unique venue codes reject a code already in use; otherwise codes may repeat.", "examples": [ "NORTHGATE" ] }, "training_ids": { "type": "array", "description": "The IDs of the training modules assigned to anyone who accepts a role at this venue. **Replaces the whole list** rather than adding to it, so send every module you want kept. Omitting the field leaves the stored list untouched.", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "is_virtual": { "type": "boolean", "description": "Whether the venue has no physical address. A virtual venue is excluded from proximity searches and sorts after venues that have coordinates. Setting this on an existing venue **detaches the address**, and switching it back off does not restore it - send the address again.", "examples": [ 0 ] }, "address": { "type": "object", "description": "Where the venue is, as an address object with `street_address_1`, `street_address_2`, `street_address_3`, `city`, `region`, `postcode` and a two-letter `country`. Optional even for a venue that is not virtual. On create the address is stored as sent; on update it replaces the address already held. Ignored when `is_virtual` is set in the same request.", "properties": {}, "examples": [ { "iso": "AUS", "region_code": "Example Region", "coordinates": { "latitude": null, "longitude": null }, "street_address_1": "1 Example Street", "city": "Example City", "region": "Example Region", "postcode": "1000", "country": "AU", "latitude": null, "longitude": null } ] } }, "required": [ "name", "frontend_name", "code" ] } } } } }, "parameters": [ { "in": "path", "name": "location_id", "description": "The ID of the location.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/headcount/location/{location_id}/venue/{id}": { "get": { "summary": "Read a venue", "operationId": "readAVenue", "description": "Returns one venue with its address, the training assigned to anyone who accepts a\nrole there, and the location it belongs to. `nice` carries the address pre-formatted\nfor display, both as a block and on one line.\n\nThe venue has to belong to the location in the path.\n\n`permissions.delete` reflects whether this particular venue can be removed, which\ndepends on whether roles are still recruiting at it.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "headcount_location_id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "North Gate" ] }, "frontend_name": { "type": "string", "examples": [ "North Gate" ] }, "code": { "type": "string", "examples": [ "NORTHGATE" ] }, "is_virtual": { "type": "integer", "examples": [ 0 ] }, "description": { "type": "string", "examples": [ "

Main pedestrian entrance.

" ] }, "is_system": { "type": "integer", "examples": [ 0 ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "uuid": { "type": "string", "examples": [ "f64e8d2b-7f0d-42fb-91bc-98a098a7f191" ] }, "address": { "type": "object", "properties": { "iso": { "type": "string", "examples": [ "AUS" ] }, "region_code": { "type": "string", "examples": [ "Example Region" ] }, "coordinates": { "type": "object", "properties": { "latitude": { "type": [ "string", "null" ], "examples": [ null ] }, "longitude": { "type": [ "string", "null" ], "examples": [ null ] } } }, "street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "city": { "type": "string", "examples": [ "Example City" ] }, "postcode": { "type": "string", "examples": [ "1000" ] }, "region": { "type": "string", "examples": [ "Example Region" ] }, "country": { "type": "string", "examples": [ "AU" ] }, "latitude": { "type": [ "string", "null" ], "examples": [ null ] }, "longitude": { "type": [ "string", "null" ], "examples": [ null ] } } } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:venue:1" ] }, "address": { "type": "string", "examples": [ "1 Example Street\nExample City\nExample Region\nAustralia\n1000" ] }, "address_oneline": { "type": "string", "examples": [ "1 Example Street, Example City, Example Region, Australia, 1000" ] }, "address.country": { "type": "string", "examples": [ "Australia" ] }, "address.country:raw": { "type": "string", "examples": [ "AUS" ] }, "address.city": { "type": "string", "examples": [ "Example City" ] }, "address.region": { "type": "string", "examples": [ "Example Region" ] }, "address.region:raw": { "type": "string", "examples": [ "Example Region" ] }, "address.postcode": { "type": "string", "examples": [ "1000" ] }, "address.street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "address.street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "address.street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "address.latitude": { "type": [ "string", "null" ], "examples": [ null ] }, "address.longitude": { "type": [ "string", "null" ], "examples": [ null ] }, "location_name": { "type": "string", "examples": [ "Main Campus" ] }, "headcount_location_type_name": { "type": "string", "examples": [ "Stadium" ] }, "headcount_location_type_id": { "type": "integer", "examples": [ 1 ] } } }, "relations": { "type": "object", "properties": { "location": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "headcount_location_type_id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Main Campus" ] }, "frontend_name": { "type": "string", "examples": [ "Main Campus" ] }, "code": { "type": "string", "examples": [ "MAINCAMPUS" ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "is_system": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "uuid": { "type": "string", "examples": [ "ec98790e-5bab-4ad7-9357-31556e2efbc4" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:location:1" ] }, "headcount_location_type_name": { "type": "string", "examples": [ "Stadium" ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "headcount_location_id": 1, "name": "North Gate", "frontend_name": "North Gate", "code": "NORTHGATE", "is_virtual": 0, "description": "

Main pedestrian entrance.

", "is_system": 0, "training_ids": [ 1 ], "deleted_at": null, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:16.000000Z", "uuid": "f64e8d2b-7f0d-42fb-91bc-98a098a7f191", "address": { "iso": "AUS", "region_code": "Example Region", "coordinates": { "latitude": null, "longitude": null }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "Example City", "postcode": "1000", "region": "Example Region", "country": "AU", "latitude": null, "longitude": null } }, "nice": { "rrn": "rrn:local:20101:venue:1", "address": "1 Example Street\nExample City\nExample Region\nAustralia\n1000", "address_oneline": "1 Example Street, Example City, Example Region, Australia, 1000", "address.country": "Australia", "address.country:raw": "AUS", "address.city": "Example City", "address.region": "Example Region", "address.region:raw": "Example Region", "address.postcode": "1000", "address.street_address_1": "1 Example Street", "address.street_address_2": null, "address.street_address_3": null, "address.latitude": null, "address.longitude": null, "location_name": "Main Campus", "headcount_location_type_name": "Stadium", "headcount_location_type_id": 1 }, "relations": { "location": { "object": { "id": 1, "account_id": 20101, "headcount_location_type_id": 1, "name": "Main Campus", "frontend_name": "Main Campus", "code": "MAINCAMPUS", "training_ids": [ 1 ], "is_system": 0, "deleted_at": null, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:16.000000Z", "uuid": "ec98790e-5bab-4ad7-9357-31556e2efbc4" }, "nice": { "rrn": "rrn:local:20101:location:1", "headcount_location_type_name": "Stadium" }, "permissions": { "read": true, "update": true, "delete": true } } }, "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Headcount Module" ] }, "put": { "summary": "Update a venue", "operationId": "updateAVenue", "description": "Updates the fields supplied and returns the venue. Only the fields sent are touched,\nso an empty body is a valid request that changes nothing.\n\nSending `address` replaces the address already held rather than merging into it, so\nsend the whole address every time. Sending `is_virtual` as true detaches the address\ninstead, and the response to that request still shows the old address even though it\nis gone - read the venue back to see its settled state.\n\nA venue stays under the location it was created in; this endpoint does not move it.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "headcount_location_id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "North Gate" ] }, "frontend_name": { "type": "string", "examples": [ "North Gate" ] }, "code": { "type": "string", "examples": [ "NORTHGATE" ] }, "is_virtual": { "type": "integer", "examples": [ 0 ] }, "description": { "type": "string", "examples": [ "

Main pedestrian entrance.

" ] }, "is_system": { "type": "integer", "examples": [ 0 ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "uuid": { "type": "string", "examples": [ "f64e8d2b-7f0d-42fb-91bc-98a098a7f191" ] }, "address": { "type": "object", "properties": { "iso": { "type": "string", "examples": [ "AUS" ] }, "region_code": { "type": "string", "examples": [ "Example Region" ] }, "coordinates": { "type": "object", "properties": { "latitude": { "type": [ "string", "null" ], "examples": [ null ] }, "longitude": { "type": [ "string", "null" ], "examples": [ null ] } } }, "street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "city": { "type": "string", "examples": [ "Example City" ] }, "postcode": { "type": "string", "examples": [ "1000" ] }, "region": { "type": "string", "examples": [ "Example Region" ] }, "country": { "type": "string", "examples": [ "AU" ] }, "latitude": { "type": [ "string", "null" ], "examples": [ null ] }, "longitude": { "type": [ "string", "null" ], "examples": [ null ] } } } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:venue:1" ] }, "address": { "type": "string", "examples": [ "1 Example Street\nExample City\nExample Region\nAustralia\n1000" ] }, "address_oneline": { "type": "string", "examples": [ "1 Example Street, Example City, Example Region, Australia, 1000" ] }, "address.country": { "type": "string", "examples": [ "Australia" ] }, "address.country:raw": { "type": "string", "examples": [ "AUS" ] }, "address.city": { "type": "string", "examples": [ "Example City" ] }, "address.region": { "type": "string", "examples": [ "Example Region" ] }, "address.region:raw": { "type": "string", "examples": [ "Example Region" ] }, "address.postcode": { "type": "string", "examples": [ "1000" ] }, "address.street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "address.street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "address.street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "address.latitude": { "type": [ "string", "null" ], "examples": [ null ] }, "address.longitude": { "type": [ "string", "null" ], "examples": [ null ] }, "location_name": { "type": "string", "examples": [ "Main Campus" ] }, "headcount_location_type_name": { "type": "string", "examples": [ "Stadium" ] }, "headcount_location_type_id": { "type": "integer", "examples": [ 1 ] } } }, "relations": { "type": "object", "properties": { "location": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "headcount_location_type_id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Main Campus" ] }, "frontend_name": { "type": "string", "examples": [ "Main Campus" ] }, "code": { "type": "string", "examples": [ "MAINCAMPUS" ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "is_system": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "uuid": { "type": "string", "examples": [ "ec98790e-5bab-4ad7-9357-31556e2efbc4" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:location:1" ] }, "headcount_location_type_name": { "type": "string", "examples": [ "Stadium" ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "headcount_location_id": 1, "name": "North Gate", "frontend_name": "North Gate", "code": "NORTHGATE", "is_virtual": 0, "description": "

Main pedestrian entrance.

", "is_system": 0, "training_ids": [ 1 ], "deleted_at": null, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:16.000000Z", "uuid": "f64e8d2b-7f0d-42fb-91bc-98a098a7f191", "address": { "iso": "AUS", "region_code": "Example Region", "coordinates": { "latitude": null, "longitude": null }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "Example City", "postcode": "1000", "region": "Example Region", "country": "AU", "latitude": null, "longitude": null } }, "nice": { "rrn": "rrn:local:20101:venue:1", "address": "1 Example Street\nExample City\nExample Region\nAustralia\n1000", "address_oneline": "1 Example Street, Example City, Example Region, Australia, 1000", "address.country": "Australia", "address.country:raw": "AUS", "address.city": "Example City", "address.region": "Example Region", "address.region:raw": "Example Region", "address.postcode": "1000", "address.street_address_1": "1 Example Street", "address.street_address_2": null, "address.street_address_3": null, "address.latitude": null, "address.longitude": null, "location_name": "Main Campus", "headcount_location_type_name": "Stadium", "headcount_location_type_id": 1 }, "relations": { "location": { "object": { "id": 1, "account_id": 20101, "headcount_location_type_id": 1, "name": "Main Campus", "frontend_name": "Main Campus", "code": "MAINCAMPUS", "training_ids": [ 1 ], "is_system": 0, "deleted_at": null, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:16.000000Z", "uuid": "ec98790e-5bab-4ad7-9357-31556e2efbc4" }, "nice": { "rrn": "rrn:local:20101:location:1", "headcount_location_type_name": "Stadium" }, "permissions": { "read": true, "update": true, "delete": true } } }, "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Headcount Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name administrators see. Required.", "examples": [ "North Gate" ] }, "frontend_name": { "type": "string", "description": "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.", "examples": [ "North Gate" ] }, "code": { "type": "string", "description": "A short reference for the venue. Letters, numbers, commas, dashes and underscores only - spaces and other punctuation are rejected. Accounts configured to require unique venue codes reject a code already in use; otherwise codes may repeat.", "examples": [ "NORTHGATE" ] }, "training_ids": { "type": "array", "description": "The IDs of the training modules assigned to anyone who accepts a role at this venue. **Replaces the whole list** rather than adding to it, so send every module you want kept. Omitting the field leaves the stored list untouched.", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "is_virtual": { "type": "boolean", "description": "Whether the venue has no physical address. A virtual venue is excluded from proximity searches and sorts after venues that have coordinates. Setting this on an existing venue **detaches the address**, and switching it back off does not restore it - send the address again.", "examples": [ 0 ] }, "description": { "type": "string", "description": "A description of the venue, in HTML. Shown to volunteers alongside the venue name.", "examples": [ "

Main pedestrian entrance.

" ] }, "address": { "type": "object", "description": "Where the venue is, as an address object with `street_address_1`, `street_address_2`, `street_address_3`, `city`, `region`, `postcode` and a two-letter `country`. Optional even for a venue that is not virtual. On create the address is stored as sent; on update it replaces the address already held. Ignored when `is_virtual` is set in the same request.", "properties": {}, "examples": [ { "iso": "AUS", "region_code": "Example Region", "coordinates": { "latitude": null, "longitude": null }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "Example City", "postcode": "1000", "region": "Example Region", "country": "AU", "latitude": null, "longitude": null } ] } } } } } } }, "delete": { "summary": "Delete a venue", "operationId": "deleteAVenue", "description": "Removes the venue. The record is retained internally so past reporting is not lost,\nbut the venue can no longer be read or edited and no endpoint restores it.\n\n**A venue with roles still recruiting at it cannot be deleted** - remove or reassign\nthose roles first. The same applies to the account's built-in default venue, which is\nnot removable at all.\n\nReturns `200` with a `messages` field rather than an empty `204`. `messages` carries\nanything the platform wants to tell you about the deletion and is `null` when there is\nnothing to say.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": [ "string", "null" ], "examples": [ null ] } }, "examples": [ { "messages": null } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Headcount Module" ] }, "parameters": [ { "in": "path", "name": "location_id", "description": "The ID of the location.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } }, { "in": "path", "name": "id", "description": "The ID of the venue.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/headcount/location/type": { "get": { "summary": "List location types", "operationId": "listLocationTypes", "description": "Returns the categories the account files its locations under, in the order\n`sort_order` puts them.\n\nThe listing is only paginated when `page` is supplied. Without it every match is\nreturned as a flat array rather than in the paged envelope.", "parameters": [ { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Stadium" ] }, "sort_order": { "type": "integer", "examples": [ 1 ] }, "uuid": { "type": "string", "examples": [ "bf46e175-87a9-4968-8e58-21efec6873a2" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } }, "examples": [ [ { "object": { "id": 1, "name": "Stadium", "sort_order": 1, "uuid": "bf46e175-87a9-4968-8e58-21efec6873a2" }, "nice": [], "relations": [], "permissions": { "read": true, "update": true, "delete": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/headcount/location/type?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/headcount/location/type?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/headcount/location/type" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 1, "name": "Stadium", "sort_order": 1, "uuid": "bf46e175-87a9-4968-8e58-21efec6873a2" }, "nice": [], "relations": [], "permissions": { "read": true, "update": true, "delete": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/headcount/location/type?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/headcount/location/type?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/headcount/location/type", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Headcount Module" ] }, "post": { "summary": "Create a location type", "operationId": "createALocationType", "description": "Adds a category that locations can be filed under. Point a location at it with\n`headcount_location_type_id` on the create or update endpoint for that location.\n\n**A type created without `sort_order` comes back without that field**, rather than\nwith its stored default of `0`. Read the type back if you need its complete state.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Stadium" ] }, "sort_order": { "type": "integer", "examples": [ 1 ] }, "uuid": { "type": "string", "examples": [ "bf46e175-87a9-4968-8e58-21efec6873a2" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "name": "Stadium", "sort_order": 1, "uuid": "bf46e175-87a9-4968-8e58-21efec6873a2" }, "nice": [], "relations": [], "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Headcount Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the location type. Required.", "examples": [ "Stadium" ] }, "sort_order": { "type": "integer", "description": "Where this type sits in the list, lowest first. Optional; types created without one sort as `0`.", "examples": [ 1 ] } }, "required": [ "name" ] } } } } } }, "/api/v2/headcount/location/type/{id}": { "get": { "summary": "Read a location type", "operationId": "readALocationType", "description": "Returns one category with its name and sort position.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Stadium" ] }, "sort_order": { "type": "integer", "examples": [ 1 ] }, "uuid": { "type": "string", "examples": [ "bf46e175-87a9-4968-8e58-21efec6873a2" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "name": "Stadium", "sort_order": 1, "uuid": "bf46e175-87a9-4968-8e58-21efec6873a2" }, "nice": [], "relations": [], "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Headcount Module" ] }, "put": { "summary": "Update a location type", "operationId": "updateALocationType", "description": "Updates the fields supplied and returns the type in the same shape as reading it.\nOnly the fields sent are touched, so an empty body is a valid request that changes\nnothing.\n\nRenaming a type does not affect which locations are filed under it.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "name": { "type": "string", "examples": [ "Stadium" ] }, "sort_order": { "type": "integer", "examples": [ 1 ] }, "uuid": { "type": "string", "examples": [ "bf46e175-87a9-4968-8e58-21efec6873a2" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "name": "Stadium", "sort_order": 1, "uuid": "bf46e175-87a9-4968-8e58-21efec6873a2" }, "nice": [], "relations": [], "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Headcount Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the location type. Required.", "examples": [ "Stadium" ] }, "sort_order": { "type": "integer", "description": "Where this type sits in the list, lowest first. Optional; types created without one sort as `0`.", "examples": [ 1 ] } } } } } } }, "delete": { "summary": "Delete a location type", "operationId": "deleteALocationType", "description": "Removes the category. The record is retained internally so past reporting is not\nlost, but the type can no longer be read or edited and no endpoint restores it.\n\nLocations filed under it are **not** deleted and keep pointing at the removed type,\nso reassign them first if they should stay categorised.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "204": { "description": "No content, successful deletion", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Headcount Module" ] }, "parameters": [ { "in": "path", "name": "id", "description": "The ID of the location type.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/inventory/item": { "get": { "summary": "List inventory items", "operationId": "listInventoryItems", "description": "Returns the items in the account's catalogue - the things that can be allocated\nto people, such as uniforms, equipment and redeemable rewards.\n\nItems shared down from a parent account are included alongside the account's\nown. nice carries the stock figures worked out for each item: how many are\nallocated, how many have been handed over, and how many remain.\n\nThe response is only wrapped in a paginated envelope when a page parameter is\nsent. Without one, every match comes back as a flat array.", "parameters": [ { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "query", "name": "extras", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "required": false, "schema": { "type": "array", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "items": { "type": "string", "enum": [ "stats", "variations" ] }, "examples": [ [ "stats" ] ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "parent_id": { "type": [ "string", "null" ], "examples": [ null ] }, "type": { "type": "string", "examples": [ "distributable" ] }, "external_id": { "type": "string", "examples": [ "SKU-10023" ] }, "certificate_id": { "type": [ "string", "null" ], "examples": [ null ] }, "is_image": { "type": "integer", "examples": [ 0 ] }, "icon": { "type": "string", "examples": [ "fab fa-accusoft" ] }, "variation_config": { "type": [ "string", "null" ], "examples": [ null ] }, "has_quantity": { "type": "integer", "examples": [ 1 ] }, "quantity": { "type": "integer", "examples": [ 54 ] }, "max_per_user": { "type": "integer", "examples": [ 0 ] }, "has_serial": { "type": "integer", "examples": [ 0 ] }, "category_id": { "type": [ "string", "null" ], "examples": [ null ] }, "serial_assignment_mode": { "type": [ "string", "null" ], "examples": [ null ] }, "is_distributable": { "type": "integer", "examples": [ 0 ] }, "is_redeemable": { "type": "integer", "examples": [ 0 ] }, "ttl": { "type": [ "string", "null" ], "examples": [ null ] }, "reward_point_cost": { "type": "integer", "examples": [ 0 ] }, "budget_cost": { "type": "string", "examples": [ "0.00" ] }, "publish": { "type": "integer", "examples": [ 1 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "has_variants": { "type": "integer", "examples": [ 0 ] }, "varied_by_attribute_id": { "type": [ "string", "null" ], "examples": [ null ] }, "variant_source_id": { "type": [ "string", "null" ], "examples": [ null ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "is_distributable_at_checkin_checkout": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:26.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:26.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "is_inheritable": { "type": "integer", "examples": [ 0 ] }, "name": { "type": "string", "examples": [ "Volunteer T-Shirt" ] } } }, "nice": { "type": "object", "properties": { "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "external_id": { "type": "string", "examples": [ "SKU-10023" ] }, "has_quantity": { "type": "string", "examples": [ "Yes" ] }, "has_variants": { "type": "string", "examples": [ "No" ] }, "is_distributable_at_checkin_checkout": { "type": "string", "examples": [ "No" ] }, "name": { "type": "string", "examples": [ "Volunteer T-Shirt" ] }, "publish": { "type": "string", "examples": [ "Yes" ] }, "type": { "type": "string", "examples": [ "Distributable" ] }, "type:value": { "type": "string", "examples": [ "distributable" ] }, "type:array": { "type": "string", "examples": [ "Distributable" ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "distributed": { "type": "integer", "examples": [ 1 ] }, "allocated": { "type": "integer", "examples": [ 0 ] }, "available": { "type": "integer", "examples": [ 53 ] }, "stock_level": { "type": "string", "examples": [ "98%" ] }, "manual_serial_required": { "type": "boolean", "examples": [ false ] }, "account_name_path": { "type": "string", "examples": [ "Rosterfy Subaccount" ] }, "is_foreign_account": { "type": "boolean", "examples": [ false ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "redeem": { "type": "boolean", "examples": [ true ] } } }, "attributes": { "type": "array", "examples": [ [] ] } } }, "examples": [ [ { "object": { "id": 1, "parent_id": null, "type": "distributable", "external_id": "SKU-10023", "certificate_id": null, "is_image": 0, "icon": "fab fa-accusoft", "variation_config": null, "has_quantity": 1, "quantity": 54, "max_per_user": 0, "has_serial": 0, "category_id": null, "serial_assignment_mode": null, "is_distributable": 0, "is_redeemable": 0, "ttl": null, "reward_point_cost": 0, "budget_cost": "0.00", "publish": 1, "sort_order": 0, "has_variants": 0, "varied_by_attribute_id": null, "variant_source_id": null, "is_archived": 0, "is_distributable_at_checkin_checkout": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:36:26.000000Z", "updated_at": "2026-06-09T05:36:26.000000Z", "deleted_by": null, "is_inheritable": 0, "name": "Volunteer T-Shirt" }, "nice": { "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "external_id": "SKU-10023", "has_quantity": "Yes", "has_variants": "No", "is_distributable_at_checkin_checkout": "No", "name": "Volunteer T-Shirt", "publish": "Yes", "type": "Distributable", "type:value": "distributable", "type:array": "Distributable", "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "distributed": 1, "allocated": 0, "available": 53, "stock_level": "98%", "manual_serial_required": false, "account_name_path": "Rosterfy Subaccount", "is_foreign_account": false }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "redeem": true }, "attributes": [] }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/inventory/item?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/inventory/item?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/inventory/item" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 1, "parent_id": null, "type": "distributable", "external_id": "SKU-10023", "certificate_id": null, "is_image": 0, "icon": "fab fa-accusoft", "variation_config": null, "has_quantity": 1, "quantity": 54, "max_per_user": 0, "has_serial": 0, "category_id": null, "serial_assignment_mode": null, "is_distributable": 0, "is_redeemable": 0, "ttl": null, "reward_point_cost": 0, "budget_cost": "0.00", "publish": 1, "sort_order": 0, "has_variants": 0, "varied_by_attribute_id": null, "variant_source_id": null, "is_archived": 0, "is_distributable_at_checkin_checkout": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:36:26.000000Z", "updated_at": "2026-06-09T05:36:26.000000Z", "deleted_by": null, "is_inheritable": 0, "name": "Volunteer T-Shirt" }, "nice": { "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "external_id": "SKU-10023", "has_quantity": "Yes", "has_variants": "No", "is_distributable_at_checkin_checkout": "No", "name": "Volunteer T-Shirt", "publish": "Yes", "type": "Distributable", "type:value": "distributable", "type:array": "Distributable", "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "distributed": 1, "allocated": 0, "available": 53, "stock_level": "98%", "manual_serial_required": false, "account_name_path": "Rosterfy Subaccount", "is_foreign_account": false }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "redeem": true }, "attributes": [] }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/inventory/item?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/inventory/item?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/inventory/item", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Inventory Module" ] }, "post": { "summary": "Create an inventory item", "operationId": "createAnInventoryItem", "description": "Adds an item to the account's catalogue and returns it.\n\n**The created item comes back with only the fields that were set on it**, not\nthe full record that reading it returns - the columns left to their defaults\nare absent rather than present and defaulted. Read the item back if you need\nits complete state.\n\nname and type are required. type decides which of the other fields apply: a\n`distributable` item is physical and tracked per person, `virtual` is issued\nwithout stock, and `certificate` issues a certificate when allocated.\n\n**Four fields are gated by a companion switch** and are rejected without it -\nquantity needs has_quantity, ttl needs has_expiry, reward_point_cost needs\nis_redeemable, and serial_assignment_mode needs has_serial. Sending the value\nwithout the switch returns a 422 naming the field. Leaving a switch off resets\nits field rather than storing what was sent, so quantity comes back 0, ttl\nnull, reward_point_cost 0 and serial_assignment_mode null.\n\n**To attach an uploaded image**, set is_image and send the request as\n`multipart/form-data` with the image in the file_path part; the other fields go\nin the same form. To point at an image you already host, set is_image and send\nfile_path as a URL in an ordinary JSON body. Either way the resolved image is\nstored on icon and file_path itself is not kept. Without is_image, send an icon\nclass name on icon instead.\n\nThe account's own attribute configuration also applies, so a create may accept\nor require fields beyond those listed here.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "name": { "type": "string", "examples": [ "Volunteer T-Shirt" ] }, "type": { "type": "string", "examples": [ "distributable" ] }, "publish": { "type": "integer", "examples": [ 1 ] }, "icon": { "type": "string", "examples": [ "fas fa-shirt" ] }, "external_id": { "type": "string", "examples": [ "SKU-10023" ] }, "has_quantity": { "type": "integer", "examples": [ 1 ] }, "quantity": { "type": "integer", "examples": [ 250 ] }, "max_per_user": { "type": "integer", "examples": [ 1 ] }, "ttl": { "type": [ "string", "null" ], "examples": [ null ] }, "reward_point_cost": { "type": "integer", "examples": [ 0 ] }, "serial_assignment_mode": { "type": [ "string", "null" ], "examples": [ null ] }, "varied_by_attribute_id": { "type": [ "string", "null" ], "examples": [ null ] }, "updated_at": { "type": "string", "examples": [ "2026-08-06T02:15:55.000000Z" ] }, "created_at": { "type": "string", "examples": [ "2026-08-06T02:15:55.000000Z" ] }, "id": { "type": "integer", "examples": [ 34 ] } } }, "nice": { "type": "object", "properties": { "created_at": { "type": "string", "examples": [ "Aug 6, 2026, 2:15 AM" ] }, "created_at__date": { "type": "string", "examples": [ "Aug 6, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "2:15 AM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Thursday" ] }, "external_id": { "type": "string", "examples": [ "SKU-10023" ] }, "has_quantity": { "type": "string", "examples": [ "Yes" ] }, "has_variants": { "type": "string", "examples": [ "No" ] }, "is_distributable_at_checkin_checkout": { "type": "string", "examples": [ "No" ] }, "name": { "type": "string", "examples": [ "Volunteer T-Shirt" ] }, "publish": { "type": "string", "examples": [ "Yes" ] }, "type": { "type": "string", "examples": [ "Distributable" ] }, "type:value": { "type": "string", "examples": [ "distributable" ] }, "type:array": { "type": "string", "examples": [ "Distributable" ] }, "updated_at": { "type": "string", "examples": [ "Aug 6, 2026, 2:15 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Aug 6, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "2:15 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Thursday" ] }, "distributed": { "type": "integer", "examples": [ 0 ] }, "allocated": { "type": "integer", "examples": [ 0 ] }, "available": { "type": "integer", "examples": [ 250 ] }, "stock_level": { "type": "string", "examples": [ "100%" ] }, "manual_serial_required": { "type": "boolean", "examples": [ false ] }, "account_name_path": { "type": "string", "examples": [ "Rosterfy Subaccount" ] }, "is_foreign_account": { "type": "boolean", "examples": [ false ] } } }, "relations": { "type": "object", "properties": {} }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "redeem": { "type": "boolean", "examples": [ true ] } } }, "attributes": { "type": "object", "properties": {} } }, "examples": [ { "object": { "name": "Volunteer T-Shirt", "type": "distributable", "publish": 1, "icon": "fas fa-shirt", "external_id": "SKU-10023", "has_quantity": 1, "quantity": 250, "max_per_user": 1, "ttl": null, "reward_point_cost": 0, "serial_assignment_mode": null, "varied_by_attribute_id": null, "updated_at": "2026-08-06T02:15:55.000000Z", "created_at": "2026-08-06T02:15:55.000000Z", "id": 34 }, "nice": { "created_at": "Aug 6, 2026, 2:15 AM", "created_at__date": "Aug 6, 2026", "created_at__time": "2:15 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Thursday", "external_id": "SKU-10023", "has_quantity": "Yes", "has_variants": "No", "is_distributable_at_checkin_checkout": "No", "name": "Volunteer T-Shirt", "publish": "Yes", "type": "Distributable", "type:value": "distributable", "type:array": "Distributable", "updated_at": "Aug 6, 2026, 2:15 AM", "updated_at__date": "Aug 6, 2026", "updated_at__time": "2:15 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Thursday", "distributed": 0, "allocated": 0, "available": 250, "stock_level": "100%", "manual_serial_required": false, "account_name_path": "Rosterfy Subaccount", "is_foreign_account": false }, "relations": {}, "permissions": { "read": true, "update": true, "delete": true, "redeem": true }, "attributes": {} } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Inventory Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the item, as it appears to administrators and to volunteers choosing a reward. Required, and limited to 255 characters.", "examples": [ "Volunteer T-Shirt" ] }, "type": { "type": "string", "description": "What kind of item this is. `distributable` is a physical item handed out and tracked per person, `virtual` is issued without stock, and `certificate` issues a certificate on allocation. Required, and it determines which of the other fields apply.", "examples": [ "distributable" ] }, "external_id": { "type": "string", "description": "Your own reference for the item - a SKU or catalogue code. Not used by Rosterfy for anything; it exists so you can match an item back to your own system.", "examples": [ "SKU-10023" ] }, "parent_id": { "type": "integer", "description": "The ID of the item this one is a variant of. Set only on variant items.", "examples": [ 1 ] }, "certificate_id": { "type": "integer", "description": "The ID of the certificate template to issue when the item is allocated. Applies to items of type `certificate`.", "examples": [ 1 ] }, "category_id": { "type": "integer", "description": "The ID of the category the item is filed under.", "examples": [ 1 ] }, "icon": { "type": "string", "description": "The icon shown against the item. Either an icon class name, or an image URL when is_image is set. See file_path for uploading an image instead.", "examples": [ "fas fa-shirt" ] }, "is_image": { "type": "boolean", "description": "Whether the item is shown with an uploaded image rather than an icon. When set, supply the image through file_path.", "examples": [ true ] }, "file_path": { "type": "string", "description": "The image to show against the item, used only when is_image is set. Send either a URL to an existing image, or the image itself as a file - see the endpoint description for how to send a file. The value is not stored as sent; it is resolved and the result is stored on icon.", "examples": [ null ] }, "has_quantity": { "type": "boolean", "description": "Whether stock is tracked for this item. When set, quantity must be given and must be greater than 0. When not set, quantity is reset to 0.", "examples": [ 1 ] }, "quantity": { "type": "integer", "description": "How many of the item are in stock. Only accepted when has_quantity is set, and must be greater than 0.", "examples": [ 250 ] }, "max_per_user": { "type": "integer", "description": "The most of this item any one person may hold at once. 0 means no limit. Cannot be negative. An allocation that would exceed it is rejected unless the request overrides the limit.", "examples": [ 1 ] }, "has_serial": { "type": "boolean", "description": "Whether individual units carry serial numbers. When set, serial_assignment_mode must be given. When not set, serial_assignment_mode is reset to null.", "examples": [ true ] }, "serial_assignment_mode": { "type": "string", "description": "How a serial is chosen when the item is allocated: `auto` takes the next free serial, `manual` requires the serial to be named on the allocation. Only accepted when has_serial is set.", "examples": [ null ] }, "has_daily_targets": { "type": "boolean", "description": "Whether daily distribution targets can be set for this item. Only takes effect on distributable items without variants. The admin form offers it only when the account has daily targets enabled.", "examples": [ true ] }, "is_redeemable": { "type": "boolean", "description": "Whether volunteers can redeem this item with reward points. When set, reward_point_cost must be given. When not set, reward_point_cost is reset to 0.", "examples": [ true ] }, "reward_point_cost": { "type": "integer", "description": "How many reward points redeeming the item costs. Only accepted when is_redeemable is set, and must be greater than 0.", "examples": [ 0 ] }, "has_expiry": { "type": "boolean", "description": "Whether an allocation of this item expires. When set, ttl must be given. When not set, ttl is reset to null. Not stored on the item itself - it is the switch that decides whether ttl is accepted.", "examples": [ true ] }, "ttl": { "type": "integer", "description": "How long an allocation of this item stays valid, in seconds. Used to work out the expiry date when the item is given to someone. Only accepted when has_expiry is set; when has_expiry is not set it is reset to null.", "examples": [ 1 ] }, "budget_cost": { "type": "number", "description": "The unit cost of the item, used in budget reporting. Two decimal places.", "examples": [ 1.23 ] }, "publish": { "type": "boolean", "description": "Whether the item is live. An unpublished item cannot be collected and is not offered to volunteers.", "examples": [ 1 ] }, "is_archived": { "type": "boolean", "description": "Whether the item is archived. An archived item is kept for reporting but is no longer offered.", "examples": [ true ] }, "is_inheritable": { "type": "boolean", "description": "Whether subaccounts of this account can use the item.", "examples": [ true ] }, "is_distributable_at_checkin_checkout": { "type": "boolean", "description": "Whether the item can be handed out as part of checking a volunteer in or out of a shift.", "examples": [ true ] }, "has_variants": { "type": "boolean", "description": "Whether this item is a parent that holds variants, such as a garment held in several sizes.", "examples": [ true ] }, "varied_by_attribute_id": { "type": "integer", "description": "The ID of the attribute the variants differ by, such as size. Set on a parent item.", "examples": [ 1 ] }, "variant_source_id": { "type": "integer", "description": "The ID of the option, within the varying attribute, that this variant represents. Set on a variant item.", "examples": [ 1 ] }, "variation_config": { "type": "object", "description": "The variant configuration for a parent item.", "properties": {}, "examples": [ "{}" ] }, "sort_order": { "type": "integer", "description": "Where the item sits in lists. Lower sorts first.", "examples": [ 1 ] }, "custom_*": { "type": "string", "description": "A custom attribute, named by its code - custom_shirt_size, for example. The value follows the attribute's own type, so it may be a string, a number, a boolean or a list. See the custom attributes documentation.", "examples": [ null ] } }, "required": [ "name", "type" ] } } } } } }, "/api/v2/inventory/item/{id}": { "get": { "summary": "Read an inventory item", "operationId": "readAnInventoryItem", "description": "Returns one item from the catalogue, with its stock settings, how it may be\nobtained, and what happens when it is allocated.\n\nnice carries the worked-out stock position - allocated, distributed, available\nand a stock_level percentage - which is the useful view of how much is left,\nsince quantity on its own is the figure the item was stocked with.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "parent_id": { "type": [ "string", "null" ], "examples": [ null ] }, "type": { "type": "string", "examples": [ "distributable" ] }, "external_id": { "type": "string", "examples": [ "SKU-10023" ] }, "certificate_id": { "type": [ "string", "null" ], "examples": [ null ] }, "is_image": { "type": "integer", "examples": [ 0 ] }, "icon": { "type": "string", "examples": [ "fab fa-accusoft" ] }, "variation_config": { "type": [ "string", "null" ], "examples": [ null ] }, "has_quantity": { "type": "integer", "examples": [ 1 ] }, "quantity": { "type": "integer", "examples": [ 54 ] }, "max_per_user": { "type": "integer", "examples": [ 0 ] }, "has_serial": { "type": "integer", "examples": [ 0 ] }, "category_id": { "type": [ "string", "null" ], "examples": [ null ] }, "serial_assignment_mode": { "type": [ "string", "null" ], "examples": [ null ] }, "is_distributable": { "type": "integer", "examples": [ 0 ] }, "is_redeemable": { "type": "integer", "examples": [ 0 ] }, "ttl": { "type": [ "string", "null" ], "examples": [ null ] }, "reward_point_cost": { "type": "integer", "examples": [ 0 ] }, "budget_cost": { "type": "string", "examples": [ "0.00" ] }, "publish": { "type": "integer", "examples": [ 1 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "has_variants": { "type": "integer", "examples": [ 0 ] }, "varied_by_attribute_id": { "type": [ "string", "null" ], "examples": [ null ] }, "variant_source_id": { "type": [ "string", "null" ], "examples": [ null ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "is_distributable_at_checkin_checkout": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:26.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:26.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "is_inheritable": { "type": "integer", "examples": [ 0 ] }, "name": { "type": "string", "examples": [ "Volunteer T-Shirt" ] } } }, "nice": { "type": "object", "properties": { "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "external_id": { "type": "string", "examples": [ "SKU-10023" ] }, "has_quantity": { "type": "string", "examples": [ "Yes" ] }, "has_variants": { "type": "string", "examples": [ "No" ] }, "is_distributable_at_checkin_checkout": { "type": "string", "examples": [ "No" ] }, "name": { "type": "string", "examples": [ "Volunteer T-Shirt" ] }, "publish": { "type": "string", "examples": [ "Yes" ] }, "type": { "type": "string", "examples": [ "Distributable" ] }, "type:value": { "type": "string", "examples": [ "distributable" ] }, "type:array": { "type": "string", "examples": [ "Distributable" ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "distributed": { "type": "integer", "examples": [ 1 ] }, "allocated": { "type": "integer", "examples": [ 0 ] }, "available": { "type": "integer", "examples": [ 53 ] }, "stock_level": { "type": "string", "examples": [ "98%" ] }, "manual_serial_required": { "type": "boolean", "examples": [ false ] }, "account_name_path": { "type": "string", "examples": [ "Rosterfy Subaccount" ] }, "is_foreign_account": { "type": "boolean", "examples": [ false ] } } }, "relations": { "type": "object", "properties": {} }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "redeem": { "type": "boolean", "examples": [ true ] } } }, "attributes": { "type": "object", "properties": {} } }, "examples": [ { "object": { "id": 1, "parent_id": null, "type": "distributable", "external_id": "SKU-10023", "certificate_id": null, "is_image": 0, "icon": "fab fa-accusoft", "variation_config": null, "has_quantity": 1, "quantity": 54, "max_per_user": 0, "has_serial": 0, "category_id": null, "serial_assignment_mode": null, "is_distributable": 0, "is_redeemable": 0, "ttl": null, "reward_point_cost": 0, "budget_cost": "0.00", "publish": 1, "sort_order": 0, "has_variants": 0, "varied_by_attribute_id": null, "variant_source_id": null, "is_archived": 0, "is_distributable_at_checkin_checkout": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:36:26.000000Z", "updated_at": "2026-06-09T05:36:26.000000Z", "deleted_by": null, "is_inheritable": 0, "name": "Volunteer T-Shirt" }, "nice": { "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "external_id": "SKU-10023", "has_quantity": "Yes", "has_variants": "No", "is_distributable_at_checkin_checkout": "No", "name": "Volunteer T-Shirt", "publish": "Yes", "type": "Distributable", "type:value": "distributable", "type:array": "Distributable", "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "distributed": 1, "allocated": 0, "available": 53, "stock_level": "98%", "manual_serial_required": false, "account_name_path": "Rosterfy Subaccount", "is_foreign_account": false }, "relations": {}, "permissions": { "read": true, "update": true, "delete": true, "redeem": true }, "attributes": {} } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Inventory Module" ] }, "put": { "summary": "Update an inventory item", "operationId": "updateAnInventoryItem", "description": "Updates the fields supplied and returns the item in the same shape as reading\nit.\n\nThe companion-switch pairs behave as they do on create, and that matters more\nhere because turning a switch off **discards the stored value**: clearing\nhas_quantity resets quantity to 0, clearing has_expiry resets ttl to null,\nclearing is_redeemable resets reward_point_cost to 0, and clearing has_serial\nresets serial_assignment_mode to null. Sending one of those values while its\nswitch is off returns a 422 naming the field.\n\nChanging stock settings does not touch items already allocated to people. An\nallocation keeps the expiry it was given, so shortening the item's validity\nperiod changes only what future allocations get.\n\nImages work as they do on create - see the create endpoint for how to send a\nfile rather than a URL.\n\nThe account's own attribute configuration also applies, so an update may accept\nfields beyond those listed here.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "parent_id": { "type": [ "string", "null" ], "examples": [ null ] }, "type": { "type": "string", "examples": [ "distributable" ] }, "external_id": { "type": "string", "examples": [ "SKU-10023" ] }, "certificate_id": { "type": [ "string", "null" ], "examples": [ null ] }, "is_image": { "type": "integer", "examples": [ 0 ] }, "icon": { "type": "string", "examples": [ "fab fa-accusoft" ] }, "variation_config": { "type": [ "string", "null" ], "examples": [ null ] }, "has_quantity": { "type": "integer", "examples": [ 1 ] }, "quantity": { "type": "integer", "examples": [ 54 ] }, "max_per_user": { "type": "integer", "examples": [ 0 ] }, "has_serial": { "type": "integer", "examples": [ 0 ] }, "category_id": { "type": [ "string", "null" ], "examples": [ null ] }, "serial_assignment_mode": { "type": [ "string", "null" ], "examples": [ null ] }, "is_distributable": { "type": "integer", "examples": [ 0 ] }, "is_redeemable": { "type": "integer", "examples": [ 0 ] }, "ttl": { "type": [ "string", "null" ], "examples": [ null ] }, "reward_point_cost": { "type": "integer", "examples": [ 0 ] }, "budget_cost": { "type": "string", "examples": [ "0.00" ] }, "publish": { "type": "integer", "examples": [ 1 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "has_variants": { "type": "integer", "examples": [ 0 ] }, "varied_by_attribute_id": { "type": [ "string", "null" ], "examples": [ null ] }, "variant_source_id": { "type": [ "string", "null" ], "examples": [ null ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "is_distributable_at_checkin_checkout": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:26.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:26.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "is_inheritable": { "type": "integer", "examples": [ 0 ] }, "name": { "type": "string", "examples": [ "Volunteer T-Shirt" ] } } }, "nice": { "type": "object", "properties": { "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "external_id": { "type": "string", "examples": [ "SKU-10023" ] }, "has_quantity": { "type": "string", "examples": [ "Yes" ] }, "has_variants": { "type": "string", "examples": [ "No" ] }, "is_distributable_at_checkin_checkout": { "type": "string", "examples": [ "No" ] }, "name": { "type": "string", "examples": [ "Volunteer T-Shirt" ] }, "publish": { "type": "string", "examples": [ "Yes" ] }, "type": { "type": "string", "examples": [ "Distributable" ] }, "type:value": { "type": "string", "examples": [ "distributable" ] }, "type:array": { "type": "string", "examples": [ "Distributable" ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "distributed": { "type": "integer", "examples": [ 1 ] }, "allocated": { "type": "integer", "examples": [ 0 ] }, "available": { "type": "integer", "examples": [ 53 ] }, "stock_level": { "type": "string", "examples": [ "98%" ] }, "manual_serial_required": { "type": "boolean", "examples": [ false ] }, "account_name_path": { "type": "string", "examples": [ "Rosterfy Subaccount" ] }, "is_foreign_account": { "type": "boolean", "examples": [ false ] } } }, "relations": { "type": "object", "properties": {} }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "redeem": { "type": "boolean", "examples": [ true ] } } }, "attributes": { "type": "object", "properties": {} } }, "examples": [ { "object": { "id": 1, "parent_id": null, "type": "distributable", "external_id": "SKU-10023", "certificate_id": null, "is_image": 0, "icon": "fab fa-accusoft", "variation_config": null, "has_quantity": 1, "quantity": 54, "max_per_user": 0, "has_serial": 0, "category_id": null, "serial_assignment_mode": null, "is_distributable": 0, "is_redeemable": 0, "ttl": null, "reward_point_cost": 0, "budget_cost": "0.00", "publish": 1, "sort_order": 0, "has_variants": 0, "varied_by_attribute_id": null, "variant_source_id": null, "is_archived": 0, "is_distributable_at_checkin_checkout": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:36:26.000000Z", "updated_at": "2026-06-09T05:36:26.000000Z", "deleted_by": null, "is_inheritable": 0, "name": "Volunteer T-Shirt" }, "nice": { "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "external_id": "SKU-10023", "has_quantity": "Yes", "has_variants": "No", "is_distributable_at_checkin_checkout": "No", "name": "Volunteer T-Shirt", "publish": "Yes", "type": "Distributable", "type:value": "distributable", "type:array": "Distributable", "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "distributed": 1, "allocated": 0, "available": 53, "stock_level": "98%", "manual_serial_required": false, "account_name_path": "Rosterfy Subaccount", "is_foreign_account": false }, "relations": {}, "permissions": { "read": true, "update": true, "delete": true, "redeem": true }, "attributes": {} } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Inventory Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the item, as it appears to administrators and to volunteers choosing a reward. Required, and limited to 255 characters.", "examples": [ "Volunteer T-Shirt" ] }, "type": { "type": "string", "description": "What kind of item this is. `distributable` is a physical item handed out and tracked per person, `virtual` is issued without stock, and `certificate` issues a certificate on allocation. Required, and it determines which of the other fields apply.", "examples": [ "distributable" ] }, "external_id": { "type": "string", "description": "Your own reference for the item - a SKU or catalogue code. Not used by Rosterfy for anything; it exists so you can match an item back to your own system.", "examples": [ "SKU-10023" ] }, "parent_id": { "type": "integer", "description": "The ID of the item this one is a variant of. Set only on variant items.", "examples": [ 1 ] }, "certificate_id": { "type": "integer", "description": "The ID of the certificate template to issue when the item is allocated. Applies to items of type `certificate`.", "examples": [ 1 ] }, "category_id": { "type": "integer", "description": "The ID of the category the item is filed under.", "examples": [ 1 ] }, "icon": { "type": "string", "description": "The icon shown against the item. Either an icon class name, or an image URL when is_image is set. See file_path for uploading an image instead.", "examples": [ "fab fa-accusoft" ] }, "is_image": { "type": "boolean", "description": "Whether the item is shown with an uploaded image rather than an icon. When set, supply the image through file_path.", "examples": [ 0 ] }, "file_path": { "type": "string", "description": "The image to show against the item, used only when is_image is set. Send either a URL to an existing image, or the image itself as a file - see the endpoint description for how to send a file. The value is not stored as sent; it is resolved and the result is stored on icon.", "examples": [ null ] }, "has_quantity": { "type": "boolean", "description": "Whether stock is tracked for this item. When set, quantity must be given and must be greater than 0. When not set, quantity is reset to 0.", "examples": [ 1 ] }, "quantity": { "type": "integer", "description": "How many of the item are in stock. Only accepted when has_quantity is set, and must be greater than 0.", "examples": [ 54 ] }, "max_per_user": { "type": "integer", "description": "The most of this item any one person may hold at once. 0 means no limit. Cannot be negative. An allocation that would exceed it is rejected unless the request overrides the limit.", "examples": [ 0 ] }, "has_serial": { "type": "boolean", "description": "Whether individual units carry serial numbers. When set, serial_assignment_mode must be given. When not set, serial_assignment_mode is reset to null.", "examples": [ 0 ] }, "serial_assignment_mode": { "type": "string", "description": "How a serial is chosen when the item is allocated: `auto` takes the next free serial, `manual` requires the serial to be named on the allocation. Only accepted when has_serial is set.", "examples": [ null ] }, "has_daily_targets": { "type": "boolean", "description": "Whether daily distribution targets can be set for this item. Only takes effect on distributable items without variants. The admin form offers it only when the account has daily targets enabled.", "examples": [ true ] }, "is_redeemable": { "type": "boolean", "description": "Whether volunteers can redeem this item with reward points. When set, reward_point_cost must be given. When not set, reward_point_cost is reset to 0.", "examples": [ 0 ] }, "reward_point_cost": { "type": "integer", "description": "How many reward points redeeming the item costs. Only accepted when is_redeemable is set, and must be greater than 0.", "examples": [ 0 ] }, "has_expiry": { "type": "boolean", "description": "Whether an allocation of this item expires. When set, ttl must be given. When not set, ttl is reset to null. Not stored on the item itself - it is the switch that decides whether ttl is accepted.", "examples": [ true ] }, "ttl": { "type": "integer", "description": "How long an allocation of this item stays valid, in seconds. Used to work out the expiry date when the item is given to someone. Only accepted when has_expiry is set; when has_expiry is not set it is reset to null.", "examples": [ 1 ] }, "budget_cost": { "type": "number", "description": "The unit cost of the item, used in budget reporting. Two decimal places.", "examples": [ "0.00" ] }, "publish": { "type": "boolean", "description": "Whether the item is live. An unpublished item cannot be collected and is not offered to volunteers.", "examples": [ 1 ] }, "is_archived": { "type": "boolean", "description": "Whether the item is archived. An archived item is kept for reporting but is no longer offered.", "examples": [ 0 ] }, "is_inheritable": { "type": "boolean", "description": "Whether subaccounts of this account can use the item.", "examples": [ 0 ] }, "is_distributable_at_checkin_checkout": { "type": "boolean", "description": "Whether the item can be handed out as part of checking a volunteer in or out of a shift.", "examples": [ true ] }, "has_variants": { "type": "boolean", "description": "Whether this item is a parent that holds variants, such as a garment held in several sizes.", "examples": [ 0 ] }, "varied_by_attribute_id": { "type": "integer", "description": "The ID of the attribute the variants differ by, such as size. Set on a parent item.", "examples": [ 1 ] }, "variant_source_id": { "type": "integer", "description": "The ID of the option, within the varying attribute, that this variant represents. Set on a variant item.", "examples": [ 1 ] }, "variation_config": { "type": "object", "description": "The variant configuration for a parent item.", "properties": {}, "examples": [ "{}" ] }, "sort_order": { "type": "integer", "description": "Where the item sits in lists. Lower sorts first.", "examples": [ 0 ] }, "custom_*": { "type": "string", "description": "A custom attribute, named by its code - custom_shirt_size, for example. The value follows the attribute's own type, so it may be a string, a number, a boolean or a list. See the custom attributes documentation.", "examples": [ null ] } } } } } } }, "delete": { "summary": "Delete an inventory item", "operationId": "deleteAnInventoryItem", "description": "Removes the item from the catalogue. The record is retained internally, so\nexisting allocations and past reporting are not lost, but the item can no\nlonger be allocated and no endpoint restores it.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "204": { "description": "No content, successful deletion", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Inventory Module" ] }, "parameters": [ { "in": "path", "name": "id", "description": "The ID of the inventory item.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/inventory/item/{item_id}/user": { "post": { "summary": "Allocate an item to a person", "operationId": "allocateAnItemToAPerson", "description": "Gives one unit of the item in the URL to one person and returns the allocation.\n\n**One record is one unit.** quantity is accepted but not stored, so send the\nrequest again to give someone several.\n\nIf the item limits how many one person may hold, an allocation that would\nexceed the limit is **rejected** and reports the limit. Send\nignore_max_per_user to allocate anyway.\n\nFor an item with serials, the serial is taken care of according to how the item\nis set up - assigned automatically from the free pool, or expected to be named\nwhen the item is handed over. An item with no free serials left cannot be\nallocated.\n\nLeave collected_at unset for an allocation that has not been handed over yet;\nthat is what the collect endpoint acts on. Leave expires_at unset to take the\nexpiry from the item's validity period.\n\nThe allocation comes back with the person and the item embedded, so a\nfollow-up read is not needed.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 11 ] }, "inventory_allocation_id": { "type": [ "string", "null" ], "examples": [ null ] }, "inventory_item_id": { "type": "integer", "examples": [ 1 ] }, "user_id": { "type": "integer", "examples": [ 1234 ] }, "entity": { "type": [ "string", "null" ], "examples": [ null ] }, "entity_id": { "type": [ "string", "null" ], "examples": [ null ] }, "inventory_allocation_type": { "type": "string", "examples": [ "rewards" ] }, "serial": { "type": [ "string", "null" ], "examples": [ null ] }, "inventory_item_serial_id": { "type": [ "string", "null" ], "examples": [ null ] }, "expires_at": { "type": "string", "examples": [ "2026-06-10T05:36:49.000000Z" ] }, "collected_at": { "type": "string", "examples": [ "2026-06-02T05:29:35.000000Z" ] }, "collected_entity": { "type": [ "string", "null" ], "examples": [ null ] }, "collected_by": { "type": [ "string", "null" ], "examples": [ null ] }, "data": { "type": [ "string", "null" ], "examples": [ null ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:49.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:49.000000Z" ] } } }, "nice": { "type": "object", "properties": { "inventory_allocation_type": { "type": "string", "examples": [ "Rewards" ] }, "user_name": { "type": "string", "examples": [ "Alex Example" ] } } }, "relations": { "type": "object", "properties": { "user": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1234 ] }, "first_name": { "type": "string", "examples": [ "Alex" ] }, "last_name": { "type": "string", "examples": [ "Example" ] }, "email": { "type": "string", "examples": [ "alex.example@example.com" ] } } }, "nice": { "type": "object", "properties": { "first_name": { "type": "string", "examples": [ "Alex" ] }, "last_name": { "type": "string", "examples": [ "Example" ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } }, "id": { "type": "integer", "examples": [ 1234 ] }, "name": { "type": "string", "examples": [ "Alex Example" ] } } }, "inventory_allocation": { "type": [ "string", "null" ], "examples": [ null ] }, "inventory_item": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "parent_id": { "type": [ "string", "null" ], "examples": [ null ] }, "type": { "type": "string", "examples": [ "distributable" ] }, "external_id": { "type": "string", "examples": [ "SKU-10023" ] }, "certificate_id": { "type": [ "string", "null" ], "examples": [ null ] }, "is_image": { "type": "integer", "examples": [ 0 ] }, "icon": { "type": "string", "examples": [ "fab fa-accusoft" ] }, "variation_config": { "type": [ "string", "null" ], "examples": [ null ] }, "has_quantity": { "type": "integer", "examples": [ 1 ] }, "quantity": { "type": "integer", "examples": [ 54 ] }, "max_per_user": { "type": "integer", "examples": [ 0 ] }, "has_serial": { "type": "integer", "examples": [ 0 ] }, "category_id": { "type": [ "string", "null" ], "examples": [ null ] }, "serial_assignment_mode": { "type": [ "string", "null" ], "examples": [ null ] }, "is_distributable": { "type": "integer", "examples": [ 0 ] }, "is_redeemable": { "type": "integer", "examples": [ 0 ] }, "ttl": { "type": [ "string", "null" ], "examples": [ null ] }, "reward_point_cost": { "type": "integer", "examples": [ 0 ] }, "budget_cost": { "type": "string", "examples": [ "0.00" ] }, "publish": { "type": "integer", "examples": [ 1 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "has_variants": { "type": "integer", "examples": [ 0 ] }, "varied_by_attribute_id": { "type": [ "string", "null" ], "examples": [ null ] }, "variant_source_id": { "type": [ "string", "null" ], "examples": [ null ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "is_distributable_at_checkin_checkout": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:26.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:26.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "is_inheritable": { "type": "integer", "examples": [ 0 ] }, "name": { "type": "string", "examples": [ "Volunteer T-Shirt" ] } } }, "nice": { "type": "object", "properties": { "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "external_id": { "type": "string", "examples": [ "SKU-10023" ] }, "has_quantity": { "type": "string", "examples": [ "Yes" ] }, "has_variants": { "type": "string", "examples": [ "No" ] }, "is_distributable_at_checkin_checkout": { "type": "string", "examples": [ "No" ] }, "name": { "type": "string", "examples": [ "Volunteer T-Shirt" ] }, "publish": { "type": "string", "examples": [ "Yes" ] }, "type": { "type": "string", "examples": [ "Distributable" ] }, "type:value": { "type": "string", "examples": [ "distributable" ] }, "type:array": { "type": "string", "examples": [ "Distributable" ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "distributed": { "type": "integer", "examples": [ 1 ] }, "allocated": { "type": "integer", "examples": [ 0 ] }, "available": { "type": "integer", "examples": [ 53 ] }, "stock_level": { "type": "string", "examples": [ "98%" ] }, "manual_serial_required": { "type": "boolean", "examples": [ false ] }, "account_name_path": { "type": "string", "examples": [ "Rosterfy Subaccount" ] }, "is_foreign_account": { "type": "boolean", "examples": [ false ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } }, "serial_obj": { "type": [ "string", "null" ], "examples": [ null ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "user_update": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 11, "inventory_allocation_id": null, "inventory_item_id": 1, "user_id": 1234, "entity": null, "entity_id": null, "inventory_allocation_type": "rewards", "serial": null, "inventory_item_serial_id": null, "expires_at": "2026-06-10T05:36:49.000000Z", "collected_at": "2026-06-02T05:29:35.000000Z", "collected_entity": null, "collected_by": null, "data": null, "sort_order": 0, "deleted_at": null, "created_at": "2026-06-09T05:36:49.000000Z", "updated_at": "2026-06-09T05:36:49.000000Z" }, "nice": { "inventory_allocation_type": "Rewards", "user_name": "Alex Example" }, "relations": { "user": { "object": { "id": 1234, "first_name": "Alex", "last_name": "Example", "email": "alex.example@example.com" }, "nice": { "first_name": "Alex", "last_name": "Example" }, "permissions": { "read": true, "update": true, "delete": true }, "id": 1234, "name": "Alex Example" }, "inventory_allocation": null, "inventory_item": { "object": { "id": 1, "parent_id": null, "type": "distributable", "external_id": "SKU-10023", "certificate_id": null, "is_image": 0, "icon": "fab fa-accusoft", "variation_config": null, "has_quantity": 1, "quantity": 54, "max_per_user": 0, "has_serial": 0, "category_id": null, "serial_assignment_mode": null, "is_distributable": 0, "is_redeemable": 0, "ttl": null, "reward_point_cost": 0, "budget_cost": "0.00", "publish": 1, "sort_order": 0, "has_variants": 0, "varied_by_attribute_id": null, "variant_source_id": null, "is_archived": 0, "is_distributable_at_checkin_checkout": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:36:26.000000Z", "updated_at": "2026-06-09T05:36:26.000000Z", "deleted_by": null, "is_inheritable": 0, "name": "Volunteer T-Shirt" }, "nice": { "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "external_id": "SKU-10023", "has_quantity": "Yes", "has_variants": "No", "is_distributable_at_checkin_checkout": "No", "name": "Volunteer T-Shirt", "publish": "Yes", "type": "Distributable", "type:value": "distributable", "type:array": "Distributable", "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "distributed": 1, "allocated": 0, "available": 53, "stock_level": "98%", "manual_serial_required": false, "account_name_path": "Rosterfy Subaccount", "is_foreign_account": false }, "permissions": { "read": true, "update": true, "delete": true } }, "serial_obj": null }, "permissions": { "read": true, "update": true, "delete": true, "user_update": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Inventory Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "The ID of the person the item is allocated to. Required on create.", "examples": [ 1234 ] }, "inventory_allocation_type": { "type": "string", "description": "How the person came by the item - for example `rewards` when they redeemed it with points. Recorded against the allocation and used in reporting; it does not change how the allocation behaves.", "examples": [ "rewards" ] }, "expires_at": { "type": "string", "description": "When the allocation stops being valid, as `YYYY-MM-DD HH:MM:SS`. Left unset on create, it is worked out from the item's validity period if it has one.", "examples": [ "2026-06-10T05:36:49.000000Z" ] }, "collected_at": { "type": "string", "description": "When the person physically received the item, as `YYYY-MM-DD HH:MM:SS`. Leave unset for an allocation that has not been handed over yet; an allocation with no collection time is what the collect endpoint acts on.", "examples": [ "2026-06-02T05:29:35.000000Z" ] }, "ignore_max_per_user": { "type": "boolean", "description": "Set to allocate the item even though the person already holds as many as the item permits. Without it, an allocation over that limit is rejected. Accepted on create only.", "examples": [ true ] }, "quantity": { "type": "integer", "description": "Not stored. The allocation record holds one unit, so this field is accepted and then discarded - allocate the item more than once to give someone several.", "examples": [ 1 ] } }, "required": [ "user_id" ] } } } } }, "parameters": [ { "in": "path", "name": "item_id", "description": "The ID of the inventory item.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/inventory/item/{item_id}/user/{id}": { "get": { "summary": "Read an allocation", "operationId": "readAnAllocation", "description": "Returns one allocation of an item to a person: when it was given, when it was\ncollected, when it expires, and which serial was assigned if the item carries\nthem.\n\nThe person and the item are embedded in the response by default rather than\nhaving to be asked for. The person is returned as their full profile, so treat\nthis response as carrying personal data even when all you wanted was the\nallocation.\n\nAn allocation with no collection time has not been handed over yet.\n\nThe allocation must belong to the item in the URL; a mismatched pair returns a\n404.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 11 ] }, "inventory_allocation_id": { "type": [ "string", "null" ], "examples": [ null ] }, "inventory_item_id": { "type": "integer", "examples": [ 1 ] }, "user_id": { "type": "integer", "examples": [ 1234 ] }, "entity": { "type": [ "string", "null" ], "examples": [ null ] }, "entity_id": { "type": [ "string", "null" ], "examples": [ null ] }, "inventory_allocation_type": { "type": "string", "examples": [ "rewards" ] }, "serial": { "type": [ "string", "null" ], "examples": [ null ] }, "inventory_item_serial_id": { "type": [ "string", "null" ], "examples": [ null ] }, "expires_at": { "type": "string", "examples": [ "2026-06-10T05:36:49.000000Z" ] }, "collected_at": { "type": "string", "examples": [ "2026-06-02T05:29:35.000000Z" ] }, "collected_entity": { "type": [ "string", "null" ], "examples": [ null ] }, "collected_by": { "type": [ "string", "null" ], "examples": [ null ] }, "data": { "type": [ "string", "null" ], "examples": [ null ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:49.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:49.000000Z" ] } } }, "nice": { "type": "object", "properties": { "inventory_allocation_type": { "type": "string", "examples": [ "Rewards" ] }, "user_name": { "type": "string", "examples": [ "Alex Example" ] } } }, "relations": { "type": "object", "properties": { "user": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1234 ] }, "first_name": { "type": "string", "examples": [ "Alex" ] }, "last_name": { "type": "string", "examples": [ "Example" ] }, "email": { "type": "string", "examples": [ "alex.example@example.com" ] } } }, "nice": { "type": "object", "properties": { "first_name": { "type": "string", "examples": [ "Alex" ] }, "last_name": { "type": "string", "examples": [ "Example" ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } }, "id": { "type": "integer", "examples": [ 1234 ] }, "name": { "type": "string", "examples": [ "Alex Example" ] } } }, "inventory_allocation": { "type": [ "string", "null" ], "examples": [ null ] }, "inventory_item": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "parent_id": { "type": [ "string", "null" ], "examples": [ null ] }, "type": { "type": "string", "examples": [ "distributable" ] }, "external_id": { "type": "string", "examples": [ "SKU-10023" ] }, "certificate_id": { "type": [ "string", "null" ], "examples": [ null ] }, "is_image": { "type": "integer", "examples": [ 0 ] }, "icon": { "type": "string", "examples": [ "fab fa-accusoft" ] }, "variation_config": { "type": [ "string", "null" ], "examples": [ null ] }, "has_quantity": { "type": "integer", "examples": [ 1 ] }, "quantity": { "type": "integer", "examples": [ 54 ] }, "max_per_user": { "type": "integer", "examples": [ 0 ] }, "has_serial": { "type": "integer", "examples": [ 0 ] }, "category_id": { "type": [ "string", "null" ], "examples": [ null ] }, "serial_assignment_mode": { "type": [ "string", "null" ], "examples": [ null ] }, "is_distributable": { "type": "integer", "examples": [ 0 ] }, "is_redeemable": { "type": "integer", "examples": [ 0 ] }, "ttl": { "type": [ "string", "null" ], "examples": [ null ] }, "reward_point_cost": { "type": "integer", "examples": [ 0 ] }, "budget_cost": { "type": "string", "examples": [ "0.00" ] }, "publish": { "type": "integer", "examples": [ 1 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "has_variants": { "type": "integer", "examples": [ 0 ] }, "varied_by_attribute_id": { "type": [ "string", "null" ], "examples": [ null ] }, "variant_source_id": { "type": [ "string", "null" ], "examples": [ null ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "is_distributable_at_checkin_checkout": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:26.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:26.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "is_inheritable": { "type": "integer", "examples": [ 0 ] }, "name": { "type": "string", "examples": [ "Volunteer T-Shirt" ] } } }, "nice": { "type": "object", "properties": { "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "external_id": { "type": "string", "examples": [ "SKU-10023" ] }, "has_quantity": { "type": "string", "examples": [ "Yes" ] }, "has_variants": { "type": "string", "examples": [ "No" ] }, "is_distributable_at_checkin_checkout": { "type": "string", "examples": [ "No" ] }, "name": { "type": "string", "examples": [ "Volunteer T-Shirt" ] }, "publish": { "type": "string", "examples": [ "Yes" ] }, "type": { "type": "string", "examples": [ "Distributable" ] }, "type:value": { "type": "string", "examples": [ "distributable" ] }, "type:array": { "type": "string", "examples": [ "Distributable" ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "distributed": { "type": "integer", "examples": [ 1 ] }, "allocated": { "type": "integer", "examples": [ 0 ] }, "available": { "type": "integer", "examples": [ 53 ] }, "stock_level": { "type": "string", "examples": [ "98%" ] }, "manual_serial_required": { "type": "boolean", "examples": [ false ] }, "account_name_path": { "type": "string", "examples": [ "Rosterfy Subaccount" ] }, "is_foreign_account": { "type": "boolean", "examples": [ false ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } }, "serial_obj": { "type": [ "string", "null" ], "examples": [ null ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "user_update": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 11, "inventory_allocation_id": null, "inventory_item_id": 1, "user_id": 1234, "entity": null, "entity_id": null, "inventory_allocation_type": "rewards", "serial": null, "inventory_item_serial_id": null, "expires_at": "2026-06-10T05:36:49.000000Z", "collected_at": "2026-06-02T05:29:35.000000Z", "collected_entity": null, "collected_by": null, "data": null, "sort_order": 0, "deleted_at": null, "created_at": "2026-06-09T05:36:49.000000Z", "updated_at": "2026-06-09T05:36:49.000000Z" }, "nice": { "inventory_allocation_type": "Rewards", "user_name": "Alex Example" }, "relations": { "user": { "object": { "id": 1234, "first_name": "Alex", "last_name": "Example", "email": "alex.example@example.com" }, "nice": { "first_name": "Alex", "last_name": "Example" }, "permissions": { "read": true, "update": true, "delete": true }, "id": 1234, "name": "Alex Example" }, "inventory_allocation": null, "inventory_item": { "object": { "id": 1, "parent_id": null, "type": "distributable", "external_id": "SKU-10023", "certificate_id": null, "is_image": 0, "icon": "fab fa-accusoft", "variation_config": null, "has_quantity": 1, "quantity": 54, "max_per_user": 0, "has_serial": 0, "category_id": null, "serial_assignment_mode": null, "is_distributable": 0, "is_redeemable": 0, "ttl": null, "reward_point_cost": 0, "budget_cost": "0.00", "publish": 1, "sort_order": 0, "has_variants": 0, "varied_by_attribute_id": null, "variant_source_id": null, "is_archived": 0, "is_distributable_at_checkin_checkout": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:36:26.000000Z", "updated_at": "2026-06-09T05:36:26.000000Z", "deleted_by": null, "is_inheritable": 0, "name": "Volunteer T-Shirt" }, "nice": { "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "external_id": "SKU-10023", "has_quantity": "Yes", "has_variants": "No", "is_distributable_at_checkin_checkout": "No", "name": "Volunteer T-Shirt", "publish": "Yes", "type": "Distributable", "type:value": "distributable", "type:array": "Distributable", "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "distributed": 1, "allocated": 0, "available": 53, "stock_level": "98%", "manual_serial_required": false, "account_name_path": "Rosterfy Subaccount", "is_foreign_account": false }, "permissions": { "read": true, "update": true, "delete": true } }, "serial_obj": null }, "permissions": { "read": true, "update": true, "delete": true, "user_update": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Inventory Module" ] }, "put": { "summary": "Update an allocation", "operationId": "updateAnAllocation", "description": "Updates the fields supplied and leaves the rest untouched, then returns the\nallocation in the same shape as reading it. Every field is optional.\n\nSetting collected_at is how an allocation is marked as handed over one at a\ntime; the collect endpoint does the same thing for many at once and also\nrecords who collected it.\n\nSending user_id moves the allocation to a different person. The item's\nper-person limit is **not** rechecked when it does, so an update can leave\nsomeone holding more than the item permits.\n\nquantity is accepted and discarded here as it is on create.\n\nThe allocation must belong to the item in the URL; a mismatched pair returns a\n404.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 11 ] }, "inventory_allocation_id": { "type": [ "string", "null" ], "examples": [ null ] }, "inventory_item_id": { "type": "integer", "examples": [ 1 ] }, "user_id": { "type": "integer", "examples": [ 1234 ] }, "entity": { "type": [ "string", "null" ], "examples": [ null ] }, "entity_id": { "type": [ "string", "null" ], "examples": [ null ] }, "inventory_allocation_type": { "type": "string", "examples": [ "rewards" ] }, "serial": { "type": [ "string", "null" ], "examples": [ null ] }, "inventory_item_serial_id": { "type": [ "string", "null" ], "examples": [ null ] }, "expires_at": { "type": "string", "examples": [ "2026-06-10T05:36:49.000000Z" ] }, "collected_at": { "type": "string", "examples": [ "2026-06-02T05:29:35.000000Z" ] }, "collected_entity": { "type": [ "string", "null" ], "examples": [ null ] }, "collected_by": { "type": [ "string", "null" ], "examples": [ null ] }, "data": { "type": [ "string", "null" ], "examples": [ null ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:49.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:49.000000Z" ] } } }, "nice": { "type": "object", "properties": { "inventory_allocation_type": { "type": "string", "examples": [ "Rewards" ] }, "user_name": { "type": "string", "examples": [ "Alex Example" ] } } }, "relations": { "type": "object", "properties": { "user": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1234 ] }, "first_name": { "type": "string", "examples": [ "Alex" ] }, "last_name": { "type": "string", "examples": [ "Example" ] }, "email": { "type": "string", "examples": [ "alex.example@example.com" ] } } }, "nice": { "type": "object", "properties": { "first_name": { "type": "string", "examples": [ "Alex" ] }, "last_name": { "type": "string", "examples": [ "Example" ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } }, "id": { "type": "integer", "examples": [ 1234 ] }, "name": { "type": "string", "examples": [ "Alex Example" ] } } }, "inventory_allocation": { "type": [ "string", "null" ], "examples": [ null ] }, "inventory_item": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "parent_id": { "type": [ "string", "null" ], "examples": [ null ] }, "type": { "type": "string", "examples": [ "distributable" ] }, "external_id": { "type": "string", "examples": [ "SKU-10023" ] }, "certificate_id": { "type": [ "string", "null" ], "examples": [ null ] }, "is_image": { "type": "integer", "examples": [ 0 ] }, "icon": { "type": "string", "examples": [ "fab fa-accusoft" ] }, "variation_config": { "type": [ "string", "null" ], "examples": [ null ] }, "has_quantity": { "type": "integer", "examples": [ 1 ] }, "quantity": { "type": "integer", "examples": [ 54 ] }, "max_per_user": { "type": "integer", "examples": [ 0 ] }, "has_serial": { "type": "integer", "examples": [ 0 ] }, "category_id": { "type": [ "string", "null" ], "examples": [ null ] }, "serial_assignment_mode": { "type": [ "string", "null" ], "examples": [ null ] }, "is_distributable": { "type": "integer", "examples": [ 0 ] }, "is_redeemable": { "type": "integer", "examples": [ 0 ] }, "ttl": { "type": [ "string", "null" ], "examples": [ null ] }, "reward_point_cost": { "type": "integer", "examples": [ 0 ] }, "budget_cost": { "type": "string", "examples": [ "0.00" ] }, "publish": { "type": "integer", "examples": [ 1 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "has_variants": { "type": "integer", "examples": [ 0 ] }, "varied_by_attribute_id": { "type": [ "string", "null" ], "examples": [ null ] }, "variant_source_id": { "type": [ "string", "null" ], "examples": [ null ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "is_distributable_at_checkin_checkout": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:26.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:26.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "is_inheritable": { "type": "integer", "examples": [ 0 ] }, "name": { "type": "string", "examples": [ "Volunteer T-Shirt" ] } } }, "nice": { "type": "object", "properties": { "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "external_id": { "type": "string", "examples": [ "SKU-10023" ] }, "has_quantity": { "type": "string", "examples": [ "Yes" ] }, "has_variants": { "type": "string", "examples": [ "No" ] }, "is_distributable_at_checkin_checkout": { "type": "string", "examples": [ "No" ] }, "name": { "type": "string", "examples": [ "Volunteer T-Shirt" ] }, "publish": { "type": "string", "examples": [ "Yes" ] }, "type": { "type": "string", "examples": [ "Distributable" ] }, "type:value": { "type": "string", "examples": [ "distributable" ] }, "type:array": { "type": "string", "examples": [ "Distributable" ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "distributed": { "type": "integer", "examples": [ 1 ] }, "allocated": { "type": "integer", "examples": [ 0 ] }, "available": { "type": "integer", "examples": [ 53 ] }, "stock_level": { "type": "string", "examples": [ "98%" ] }, "manual_serial_required": { "type": "boolean", "examples": [ false ] }, "account_name_path": { "type": "string", "examples": [ "Rosterfy Subaccount" ] }, "is_foreign_account": { "type": "boolean", "examples": [ false ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } }, "serial_obj": { "type": [ "string", "null" ], "examples": [ null ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "user_update": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 11, "inventory_allocation_id": null, "inventory_item_id": 1, "user_id": 1234, "entity": null, "entity_id": null, "inventory_allocation_type": "rewards", "serial": null, "inventory_item_serial_id": null, "expires_at": "2026-06-10T05:36:49.000000Z", "collected_at": "2026-06-02T05:29:35.000000Z", "collected_entity": null, "collected_by": null, "data": null, "sort_order": 0, "deleted_at": null, "created_at": "2026-06-09T05:36:49.000000Z", "updated_at": "2026-06-09T05:36:49.000000Z" }, "nice": { "inventory_allocation_type": "Rewards", "user_name": "Alex Example" }, "relations": { "user": { "object": { "id": 1234, "first_name": "Alex", "last_name": "Example", "email": "alex.example@example.com" }, "nice": { "first_name": "Alex", "last_name": "Example" }, "permissions": { "read": true, "update": true, "delete": true }, "id": 1234, "name": "Alex Example" }, "inventory_allocation": null, "inventory_item": { "object": { "id": 1, "parent_id": null, "type": "distributable", "external_id": "SKU-10023", "certificate_id": null, "is_image": 0, "icon": "fab fa-accusoft", "variation_config": null, "has_quantity": 1, "quantity": 54, "max_per_user": 0, "has_serial": 0, "category_id": null, "serial_assignment_mode": null, "is_distributable": 0, "is_redeemable": 0, "ttl": null, "reward_point_cost": 0, "budget_cost": "0.00", "publish": 1, "sort_order": 0, "has_variants": 0, "varied_by_attribute_id": null, "variant_source_id": null, "is_archived": 0, "is_distributable_at_checkin_checkout": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:36:26.000000Z", "updated_at": "2026-06-09T05:36:26.000000Z", "deleted_by": null, "is_inheritable": 0, "name": "Volunteer T-Shirt" }, "nice": { "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "external_id": "SKU-10023", "has_quantity": "Yes", "has_variants": "No", "is_distributable_at_checkin_checkout": "No", "name": "Volunteer T-Shirt", "publish": "Yes", "type": "Distributable", "type:value": "distributable", "type:array": "Distributable", "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "distributed": 1, "allocated": 0, "available": 53, "stock_level": "98%", "manual_serial_required": false, "account_name_path": "Rosterfy Subaccount", "is_foreign_account": false }, "permissions": { "read": true, "update": true, "delete": true } }, "serial_obj": null }, "permissions": { "read": true, "update": true, "delete": true, "user_update": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Inventory Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "The ID of the person the item is allocated to. Required on create.", "examples": [ 1234 ] }, "inventory_allocation_type": { "type": "string", "description": "How the person came by the item - for example `rewards` when they redeemed it with points. Recorded against the allocation and used in reporting; it does not change how the allocation behaves.", "examples": [ "rewards" ] }, "expires_at": { "type": "string", "description": "When the allocation stops being valid, as `YYYY-MM-DD HH:MM:SS`. Left unset on create, it is worked out from the item's validity period if it has one.", "examples": [ "2026-06-10T05:36:49.000000Z" ] }, "collected_at": { "type": "string", "description": "When the person physically received the item, as `YYYY-MM-DD HH:MM:SS`. Leave unset for an allocation that has not been handed over yet; an allocation with no collection time is what the collect endpoint acts on.", "examples": [ "2026-06-02T05:29:35.000000Z" ] }, "quantity": { "type": "integer", "description": "Not stored. The allocation record holds one unit, so this field is accepted and then discarded - allocate the item more than once to give someone several.", "examples": [ 1 ] } } } } } } }, "delete": { "summary": "Delete an allocation", "operationId": "deleteAnAllocation", "description": "Takes the item back from the person. The record is retained internally so past\nreporting is not lost, and no endpoint restores it.\n\nDeleting an allocation frees the person to be allocated the item again, and\nreturns any serial it held to the free pool.\n\nThe allocation must belong to the item in the URL; a mismatched pair returns a\n404.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "204": { "description": "No content, successful deletion", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Inventory Module" ] }, "parameters": [ { "in": "path", "name": "item_id", "description": "The ID of the inventory item.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } }, { "in": "path", "name": "id", "description": "The ID of the allocation.", "required": true, "schema": { "type": "integer", "examples": [ 11 ] } } ] }, "/api/v2/inventory/item/user/mass-add-item-to-users": { "post": { "summary": "Allocate an item to many people", "operationId": "allocateAnItemToManyPeople", "description": "Allocates one item to a set of people in a single call. The work is queued\nrather than done while you wait, so a 200 means the request was accepted, not\nthat anyone has been allocated anything yet.\n\n**The token in the response cannot be looked up.** There is no endpoint that\nresolves it and no completion callback, so confirm the outcome by listing the\nitem's allocations rather than by polling. Nothing is reported back if some\npeople could not be allocated - a person already holding as many as the item\npermits, or an item that runs out of stock or serials part way through, is\nskipped and the run continues.\n\nChoose who to allocate to with applyTo: send `selected` together with the list\nof person IDs, or any other value to allocate to everyone the caller can see,\nnarrowed by filter.\n\nquantity is how many of the item each person gets, and it is honoured here -\nthe item is allocated that many times per person.\n\nNote applyTo is camelCase, unlike every other field on this endpoint.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "queue": { "type": "string", "examples": [ "mTsVQ1NCLS3vg7WwP5kG1Vbt" ] } }, "examples": [ { "queue": "mTsVQ1NCLS3vg7WwP5kG1Vbt" } ] } } } } }, "tags": [ "Inventory Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "inventory_item_id": { "type": "integer", "description": "The ID of the item to allocate. Required, and it must be an item the account can use.", "examples": [ 1 ] }, "inventory_allocation_type": { "type": "string", "description": "How the people being allocated the item came by it - for example `rewards`. Recorded against each allocation and used in reporting.", "examples": [ null ] }, "quantity": { "type": "integer", "description": "How many of the item each person gets. Required. Unlike the single-allocation endpoint, this figure is honoured: the item is allocated this many times to every person matched.", "examples": [ 1 ] }, "applyTo": { "type": "string", "description": "Send `selected` to allocate to the people named in selected. Any other value allocates to every person the caller can see, narrowed by filter if one is sent.", "examples": [ null ] }, "expires_at": { "type": "string", "description": "When the allocations stop being valid, as `YYYY-MM-DD HH:MM:SS`. Left unset, each allocation takes its expiry from the item's validity period if it has one. Applies to distributable items.", "examples": [ null ] }, "collected_at": { "type": "string", "description": "When the item was handed over, as `YYYY-MM-DD HH:MM:SS`. Set it to record allocations that have already been collected. Applies to distributable items.", "examples": [ null ] }, "selected": { "type": "array", "description": "The IDs of the people to allocate to. Required when applyTo is `selected`, and ignored otherwise.", "items": { "type": "integer" }, "examples": [ [] ] }, "filter": { "type": "array", "description": "Narrows who the item is allocated to when applyTo is not `selected`, using the same filter syntax as the user listing.", "items": { "type": "object" }, "examples": [ [] ] } }, "required": [ "inventory_item_id", "inventory_allocation_type", "quantity", "applyTo" ] } } } } } }, "/api/v2/inventory/item/user/collect": { "post": { "summary": "Mark allocations as collected", "operationId": "markAllocationsAsCollected", "description": "Records that items already allocated to people have now been handed over,\nseveral at once. This is the counterpart to setting collected_at on a single\nallocation, and it also records who handed the item over.\n\nEach entry in items names the allocation to collect. Entries are matched only\nagainst allocations held by one of the people in user_ids and only against\nallocations not already collected, so calling this twice with the same body\ndoes not double-record anything.\n\n**Every entry is checked before anything is recorded** - an unknown allocation,\none belonging to an unpublished item, or a missing or unusable serial where the\nitem needs one, rejects the whole request with a 422 and nothing is collected.\n\nAn entry that passes validation but matches no uncollected allocation is\nskipped silently, so a success does not by itself mean every entry took effect.\nThe response carries no body; read the allocations back to confirm.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "examples": [ {} ] } } } } }, "tags": [ "Inventory Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_ids": { "type": "array", "description": "The IDs of the people whose allocations are being collected. An entry in items is only matched against allocations held by one of these people.", "items": { "type": "integer" }, "examples": [ [] ] }, "items": { "type": "array", "description": "The allocations being collected. Each entry is an object with an `item_user_id`, the ID of the allocation to mark as collected, and, for an item whose serials are assigned by hand, a `serial` naming the unit handed over. Every entry is checked before anything is recorded, and one bad entry rejects the whole request.", "items": { "type": "object" }, "examples": [ [] ] } }, "required": [ "user_ids", "items" ] } } } } } }, "/api/v2/inventory/allocation": { "post": { "summary": "Create an allocation rule", "operationId": "createAnAllocationRule", "description": "Sets up a rule that hands items out on its own: it names a thing to measure -\nshifts worked, events attended, hours attended - and a threshold, and everyone\nwho reaches that threshold is given the items attached to the rule. Attach those\nitems with the create endpoint on the rule's own item list; a rule with no items\nis valid and does nothing.\n\nThe rule is applied as people work, not retrospectively, so it takes effect from\nthe moment it is created rather than granting items to anyone who already meets\nthe threshold.\n\n**The created rule comes back with only the fields that were set on it**, not\nthe full record that reading it returns, and without the item list. Read the\nrule back if you need its complete state.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "examples": [ "total_number_of_shifts" ] }, "value": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "type": "total_number_of_shifts", "value": 5 } ] ] }, "conditions": { "type": "array", "examples": [ [] ] }, "type": { "type": "string", "examples": [ "entitlements" ] }, "name": { "type": "string", "examples": [ "Event Volunteer T-Shirt" ] }, "updated_at": { "type": "string", "examples": [ "2026-08-06T05:57:11.000000Z" ] }, "created_at": { "type": "string", "examples": [ "2026-08-06T05:57:11.000000Z" ] }, "id": { "type": "integer", "examples": [ 1 ] } } }, "nice": { "type": "object", "properties": { "rule_name": { "type": "string", "examples": [ "Total Number Of Shifts" ] }, "rule_value": { "type": "integer", "examples": [ 5 ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "rules": [ { "type": "total_number_of_shifts", "value": 5 } ], "conditions": [], "type": "entitlements", "name": "Event Volunteer T-Shirt", "updated_at": "2026-08-06T05:57:11.000000Z", "created_at": "2026-08-06T05:57:11.000000Z", "id": 1 }, "nice": { "rule_name": "Total Number Of Shifts", "rule_value": 5 }, "relations": [], "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Inventory Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "A name for the allocation rule, used wherever it is listed.", "examples": [ "Event Volunteer T-Shirt" ] }, "type": { "type": "string", "description": "What the people who qualify are being given. `entitlements` for something they have earned, `rewards` for something granted as a reward, and `redemption` for something exchanged for points. The value is recorded on every allocation the rule creates and is used in reporting. Send one of the three: other values are accepted here but stop the rule allocating anything when it next runs.", "examples": [ "entitlements" ] }, "rules": { "type": "array", "description": "The qualifying condition, as a list holding exactly one entry of the form `{\"type\": \"\", \"value\": }`. `type` is the measure to count and `value` is the number the person has to reach. The measures are `total_number_of_shifts`, `total_number_of_events`, `total_shift_hours` (counted from scheduled times), `total_shift_hours_attended` (counted from check-in to check-out) and `shift_hours_per_day`. Required - and note that anything else, including an empty list, more than one entry, an unrecognised measure or a missing threshold, is rejected with a message saying the field is required rather than one describing what was wrong.", "items": { "type": "object" }, "examples": [ [ { "type": "total_number_of_shifts", "value": 5 } ] ] }, "conditions": { "type": "array", "description": "An optional list of further conditions narrowing who the rule applies to, on top of the measure in `rules`. The structure is not currently validated and is not part of this contract - build it in the console rather than by hand, and send back what you were given if you are updating a rule that already has one.", "items": { "type": "object" }, "examples": [ [] ] } }, "required": [ "name", "type", "rules" ] } } } } } }, "/api/v2/inventory/allocation/{id}": { "get": { "summary": "Read an allocation rule", "operationId": "readAnAllocationRule", "description": "Returns one rule with its qualifying condition and the items it hands out.\n\n`relations.items` carries the item list in full, so a separate call is not\nneeded to see what the rule gives away. `nice` restates the qualifying condition\nin readable form - `rule_name` is the measure and `rule_value` the threshold.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "type": { "type": "string", "examples": [ "entitlements" ] }, "name": { "type": "string", "examples": [ "Event Volunteer T-Shirt" ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "examples": [ "total_number_of_shifts" ] }, "value": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "type": "total_number_of_shifts", "value": 5 } ] ] }, "conditions": { "type": "array", "examples": [ [] ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-08-06T05:57:11.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-08-06T05:57:11.000000Z" ] } } }, "nice": { "type": "object", "properties": { "rule_name": { "type": "string", "examples": [ "Total Number Of Shifts" ] }, "rule_value": { "type": "integer", "examples": [ 5 ] } } }, "relations": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "inventory_item_id": { "type": "integer", "examples": [ 1 ] }, "quantity": { "type": "integer", "examples": [ 1 ] }, "valid_duration": { "type": "integer", "examples": [ 31536000 ] }, "created_at": { "type": "string", "examples": [ "2026-08-06T05:57:11.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-08-06T05:57:11.000000Z" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } }, "examples": [ [ { "object": { "id": 1, "inventory_item_id": 1, "quantity": 1, "valid_duration": 31536000, "created_at": "2026-08-06T05:57:11.000000Z", "updated_at": "2026-08-06T05:57:11.000000Z" }, "nice": [], "permissions": { "read": true, "update": true, "delete": true } } ] ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "type": "entitlements", "name": "Event Volunteer T-Shirt", "rules": [ { "type": "total_number_of_shifts", "value": 5 } ], "conditions": [], "deleted_at": null, "created_at": "2026-08-06T05:57:11.000000Z", "updated_at": "2026-08-06T05:57:11.000000Z" }, "nice": { "rule_name": "Total Number Of Shifts", "rule_value": 5 }, "relations": { "items": [ { "object": { "id": 1, "inventory_item_id": 1, "quantity": 1, "valid_duration": 31536000, "created_at": "2026-08-06T05:57:11.000000Z", "updated_at": "2026-08-06T05:57:11.000000Z" }, "nice": [], "permissions": { "read": true, "update": true, "delete": true } } ] }, "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Inventory Module" ] }, "put": { "summary": "Update an allocation rule", "operationId": "updateAnAllocationRule", "description": "Updates the fields supplied and returns the rule in the same shape as reading\nit. Only the fields sent are touched, so an empty body is a valid request that\nchanges nothing, and omitting `rules` leaves the qualifying condition alone\nrather than clearing it.\n\nChanging the threshold does not revisit anyone who already qualified - items\nalready handed out stay handed out, and raising the threshold does not take them\nback. The new condition applies from here on.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "type": { "type": "string", "examples": [ "entitlements" ] }, "name": { "type": "string", "examples": [ "Event Volunteer T-Shirt" ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "examples": [ "total_number_of_shifts" ] }, "value": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "type": "total_number_of_shifts", "value": 5 } ] ] }, "conditions": { "type": "array", "examples": [ [] ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-08-06T05:57:11.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-08-06T05:57:11.000000Z" ] } } }, "nice": { "type": "object", "properties": { "rule_name": { "type": "string", "examples": [ "Total Number Of Shifts" ] }, "rule_value": { "type": "integer", "examples": [ 5 ] } } }, "relations": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "inventory_item_id": { "type": "integer", "examples": [ 1 ] }, "quantity": { "type": "integer", "examples": [ 1 ] }, "valid_duration": { "type": "integer", "examples": [ 31536000 ] }, "created_at": { "type": "string", "examples": [ "2026-08-06T05:57:11.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-08-06T05:57:11.000000Z" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } } }, "examples": [ [ { "object": { "id": 1, "inventory_item_id": 1, "quantity": 1, "valid_duration": 31536000, "created_at": "2026-08-06T05:57:11.000000Z", "updated_at": "2026-08-06T05:57:11.000000Z" }, "nice": [], "permissions": { "read": true, "update": true, "delete": true } } ] ] } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "type": "entitlements", "name": "Event Volunteer T-Shirt", "rules": [ { "type": "total_number_of_shifts", "value": 5 } ], "conditions": [], "deleted_at": null, "created_at": "2026-08-06T05:57:11.000000Z", "updated_at": "2026-08-06T05:57:11.000000Z" }, "nice": { "rule_name": "Total Number Of Shifts", "rule_value": 5 }, "relations": { "items": [ { "object": { "id": 1, "inventory_item_id": 1, "quantity": 1, "valid_duration": 31536000, "created_at": "2026-08-06T05:57:11.000000Z", "updated_at": "2026-08-06T05:57:11.000000Z" }, "nice": [], "permissions": { "read": true, "update": true, "delete": true } } ] }, "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Inventory Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "A name for the allocation rule, used wherever it is listed.", "examples": [ "Event Volunteer T-Shirt" ] }, "type": { "type": "string", "description": "What the people who qualify are being given. `entitlements` for something they have earned, `rewards` for something granted as a reward, and `redemption` for something exchanged for points. The value is recorded on every allocation the rule creates and is used in reporting. Send one of the three: other values are accepted here but stop the rule allocating anything when it next runs.", "examples": [ "entitlements" ] }, "rules": { "type": "array", "description": "The qualifying condition, as a list holding exactly one entry of the form `{\"type\": \"\", \"value\": }`. `type` is the measure to count and `value` is the number the person has to reach. The measures are `total_number_of_shifts`, `total_number_of_events`, `total_shift_hours` (counted from scheduled times), `total_shift_hours_attended` (counted from check-in to check-out) and `shift_hours_per_day`. Required - and note that anything else, including an empty list, more than one entry, an unrecognised measure or a missing threshold, is rejected with a message saying the field is required rather than one describing what was wrong.", "items": { "type": "object" }, "examples": [ [ { "type": "total_number_of_shifts", "value": 5 } ] ] }, "conditions": { "type": "array", "description": "An optional list of further conditions narrowing who the rule applies to, on top of the measure in `rules`. The structure is not currently validated and is not part of this contract - build it in the console rather than by hand, and send back what you were given if you are updating a rule that already has one.", "items": { "type": "object" }, "examples": [ [] ] } } } } } } }, "delete": { "summary": "Delete an allocation rule", "operationId": "deleteAnAllocationRule", "description": "Stops the rule handing anything else out. The record is retained internally so\npast reporting is not lost, but the rule can no longer be read or edited and no\nendpoint restores it.\n\nItems already given to people under this rule are not affected - they stay with\nwhoever holds them. The rule's own item list is left behind rather than removed,\nand becomes unreachable once the rule is gone, so remove any lines you still\nneed first.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "204": { "description": "No content, successful deletion", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Inventory Module" ] }, "parameters": [ { "in": "path", "name": "id", "description": "The ID of the allocation rule.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/inventory/allocation/{allocation_id}/item": { "post": { "summary": "Add an item to an allocation rule", "operationId": "addAnItemToAnAllocationRule", "description": "Adds a catalogue item to the list a rule hands out, so that everyone who meets\nthe rule's condition receives it. A rule can hand out several different items;\nadd each one separately.\n\nAdding an item does not give it to anyone who already qualified - the list is\nread each time the rule runs, so it applies from here on.\n\nWhen the rule does run, an item is quietly skipped for that person if there is\nnot enough of it left or if giving it would take them over the limit the item\nsets per person. The rest of the list is still handed out, so check what people\nactually hold rather than assuming everything on the list was given.\n\n**The created line comes back with only the fields that were set on it**, so\n`valid_duration` is absent rather than null when it was not sent.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "inventory_item_id": { "type": "integer", "examples": [ 1 ] }, "quantity": { "type": "integer", "examples": [ 1 ] }, "valid_duration": { "type": "integer", "examples": [ 31536000 ] }, "created_at": { "type": "string", "examples": [ "2026-08-06T05:57:11.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-08-06T05:57:11.000000Z" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "inventory_item_id": 1, "quantity": 1, "valid_duration": 31536000, "created_at": "2026-08-06T05:57:11.000000Z", "updated_at": "2026-08-06T05:57:11.000000Z" }, "nice": [], "relations": [], "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Inventory Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "inventory_item_id": { "type": "integer", "description": "The ID of the catalogue item to give out.", "examples": [ 1 ] }, "quantity": { "type": "integer", "description": "How many of the item each qualifying person receives, as a whole number of 1 or more. Each one is allocated separately, so a quantity of 3 produces three allocations.", "examples": [ 1 ] }, "valid_duration": { "type": "integer", "description": "How long the allocation stays valid, in seconds, counted from the moment it is granted. Leave it unset for an allocation that does not expire.", "examples": [ 31536000 ] } }, "required": [ "inventory_item_id", "quantity" ] } } } } }, "parameters": [ { "in": "path", "name": "allocation_id", "description": "The ID of the allocation rule.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/inventory/allocation/{allocation_id}/item/{id}": { "get": { "summary": "Read an item on an allocation rule", "operationId": "readAnItemOnAnAllocationRule", "description": "Returns one line from a rule's item list: which catalogue item it gives out, how\nmany, and how long the allocation stays valid.\n\nThe line has to belong to the rule named in the URL; asking for one under the\nwrong rule is not found.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "inventory_item_id": { "type": "integer", "examples": [ 1 ] }, "quantity": { "type": "integer", "examples": [ 1 ] }, "valid_duration": { "type": "integer", "examples": [ 31536000 ] }, "created_at": { "type": "string", "examples": [ "2026-08-06T05:57:11.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-08-06T05:57:11.000000Z" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "inventory_item_id": 1, "quantity": 1, "valid_duration": 31536000, "created_at": "2026-08-06T05:57:11.000000Z", "updated_at": "2026-08-06T05:57:11.000000Z" }, "nice": [], "relations": [], "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Inventory Module" ] }, "put": { "summary": "Update an item on an allocation rule", "operationId": "updateAnItemOnAnAllocationRule", "description": "Updates the fields supplied and returns the line in the same shape as reading\nit. Only the fields sent are touched.\n\nChanges apply to allocations made from here on. Anything already handed out\nkeeps the validity period it was given, so shortening `valid_duration` does not\nbring forward an expiry that has already been set.\n\nThe line has to belong to the rule named in the URL; updating one under the\nwrong rule is not found and nothing is written.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "inventory_item_id": { "type": "integer", "examples": [ 1 ] }, "quantity": { "type": "integer", "examples": [ 1 ] }, "valid_duration": { "type": "integer", "examples": [ 31536000 ] }, "created_at": { "type": "string", "examples": [ "2026-08-06T05:57:11.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-08-06T05:57:11.000000Z" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 1, "inventory_item_id": 1, "quantity": 1, "valid_duration": 31536000, "created_at": "2026-08-06T05:57:11.000000Z", "updated_at": "2026-08-06T05:57:11.000000Z" }, "nice": [], "relations": [], "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Inventory Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "inventory_item_id": { "type": "integer", "description": "The ID of the catalogue item to give out.", "examples": [ 1 ] }, "quantity": { "type": "integer", "description": "How many of the item each qualifying person receives, as a whole number of 1 or more. Each one is allocated separately, so a quantity of 3 produces three allocations.", "examples": [ 1 ] }, "valid_duration": { "type": "integer", "description": "How long the allocation stays valid, in seconds, counted from the moment it is granted. Leave it unset for an allocation that does not expire.", "examples": [ 31536000 ] } } } } } } }, "delete": { "summary": "Remove an item from an allocation rule", "operationId": "removeAnItemFromAnAllocationRule", "description": "Takes the item off the rule's list so it is no longer handed out. **This is\npermanent** - the line is removed outright rather than retained, and no endpoint\nrestores it.\n\nItems already given to people under this rule are not affected; they stay with\nwhoever holds them.\n\nThe line has to belong to the rule named in the URL; deleting one under the\nwrong rule is not found and nothing is removed.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "204": { "description": "No content, successful deletion", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Inventory Module" ] }, "parameters": [ { "in": "path", "name": "allocation_id", "description": "The ID of the allocation rule.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } }, { "in": "path", "name": "id", "description": "The ID of the item line on that rule.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/report": { "get": { "summary": "List reports", "operationId": "listReports", "description": "Returns a paginated list of the current account's reports. A report whose owner\nhas been deleted is omitted from this listing.", "parameters": [ { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 21 ] }, "report_type_id": { "type": "integer", "examples": [ 36 ] }, "report_category_id": { "type": [ "string", "null" ], "examples": [ null ] }, "user_id": { "type": "integer", "examples": [ 23453473 ] }, "name": { "type": "string", "examples": [ "Payment Report" ] }, "filters": { "type": "array", "examples": [ [] ] }, "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "examples": [ "user ID" ] }, "label": { "type": "string", "examples": [ "user ID" ] }, "value": { "type": "string", "examples": [ "[user.id]" ] } } }, "examples": [ [ { "name": "user ID", "label": "user ID", "value": "[user.id]" }, { "name": "role_offer ID", "label": "role_offer ID", "value": "[role_offer.id]" }, { "name": "role_offer_user ID", "label": "role_offer_user ID", "value": "[role_offer_user.id]" }, { "name": "payment_user ID", "label": "payment_user ID", "value": "[payment_user.id]" } ] ] }, "sorting": { "type": "array", "examples": [ [] ] }, "grouping": { "type": "array", "examples": [ [] ] }, "with_media": { "type": "integer", "examples": [ 0 ] }, "with_subaccounts": { "type": "integer", "examples": [ 0 ] }, "file_path": { "type": [ "string", "null" ], "examples": [ null ] }, "file_type": { "type": "string", "examples": [ "xlsx" ] }, "status": { "type": "string", "examples": [ "queued" ] }, "error_message": { "type": [ "string", "null" ], "examples": [ null ] }, "is_scheduled": { "type": "integer", "examples": [ 0 ] }, "start_date": { "type": [ "string", "null" ], "examples": [ null ] }, "start_time": { "type": [ "string", "null" ], "examples": [ null ] }, "end_date": { "type": [ "string", "null" ], "examples": [ null ] }, "timezone": { "type": [ "string", "null" ], "examples": [ null ] }, "repeat": { "type": [ "string", "null" ], "examples": [ null ] }, "meta": { "type": "array", "examples": [ [] ] }, "last_generated_at": { "type": [ "string", "null" ], "examples": [ null ] }, "destination_meta": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:34.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:34.000000Z" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:report:21" ] }, "status": { "type": "string", "examples": [ "Queued" ] }, "columns_preview": { "type": "string", "examples": [ "user ID, role_offer ID, role_offer_user ID, payment_user ID" ] } } }, "relations": { "type": "object", "properties": { "report_type": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 36 ] }, "type": { "type": "string", "examples": [ "payment_user" ] }, "name": { "type": "string", "examples": [ "Payment Report" ] }, "entities": { "type": "array", "items": { "type": "string" }, "examples": [ [ "user", "role_offer", "role_offer_user", "payment_user" ] ] }, "only_trashed": { "type": "integer", "examples": [ 0 ] }, "filters": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2024-08-08T10:32:42.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2024-08-08T10:32:42.000000Z" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ false ] }, "delete": { "type": "boolean", "examples": [ false ] } } } } } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "share": { "type": "boolean", "examples": [ true ] } } } } }, "examples": [ [ { "object": { "id": 21, "report_type_id": 36, "report_category_id": null, "user_id": 23453473, "name": "Payment Report", "filters": [], "columns": [ { "name": "user ID", "label": "user ID", "value": "[user.id]" }, { "name": "role_offer ID", "label": "role_offer ID", "value": "[role_offer.id]" }, { "name": "role_offer_user ID", "label": "role_offer_user ID", "value": "[role_offer_user.id]" }, { "name": "payment_user ID", "label": "payment_user ID", "value": "[payment_user.id]" } ], "sorting": [], "grouping": [], "with_media": 0, "with_subaccounts": 0, "file_path": null, "file_type": "xlsx", "status": "queued", "error_message": null, "is_scheduled": 0, "start_date": null, "start_time": null, "end_date": null, "timezone": null, "repeat": null, "meta": [], "last_generated_at": null, "destination_meta": null, "deleted_at": null, "created_at": "2026-06-09T05:36:34.000000Z", "updated_at": "2026-06-09T05:36:34.000000Z" }, "nice": { "rrn": "rrn:local:20101:report:21", "status": "Queued", "columns_preview": "user ID, role_offer ID, role_offer_user ID, payment_user ID" }, "relations": { "report_type": { "object": { "id": 36, "type": "payment_user", "name": "Payment Report", "entities": [ "user", "role_offer", "role_offer_user", "payment_user" ], "only_trashed": 0, "filters": null, "deleted_at": null, "created_at": "2024-08-08T10:32:42.000000Z", "updated_at": "2024-08-08T10:32:42.000000Z" }, "nice": [], "permissions": { "read": true, "update": false, "delete": false } } }, "permissions": { "read": true, "update": true, "delete": true, "share": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/report?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/report?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/report" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 21, "report_type_id": 36, "report_category_id": null, "user_id": 23453473, "name": "Payment Report", "filters": [], "columns": [ { "name": "user ID", "label": "user ID", "value": "[user.id]" }, { "name": "role_offer ID", "label": "role_offer ID", "value": "[role_offer.id]" }, { "name": "role_offer_user ID", "label": "role_offer_user ID", "value": "[role_offer_user.id]" }, { "name": "payment_user ID", "label": "payment_user ID", "value": "[payment_user.id]" } ], "sorting": [], "grouping": [], "with_media": 0, "with_subaccounts": 0, "file_path": null, "file_type": "xlsx", "status": "queued", "error_message": null, "is_scheduled": 0, "start_date": null, "start_time": null, "end_date": null, "timezone": null, "repeat": null, "meta": [], "last_generated_at": null, "destination_meta": null, "deleted_at": null, "created_at": "2026-06-09T05:36:34.000000Z", "updated_at": "2026-06-09T05:36:34.000000Z" }, "nice": { "rrn": "rrn:local:20101:report:21", "status": "Queued", "columns_preview": "user ID, role_offer ID, role_offer_user ID, payment_user ID" }, "relations": { "report_type": { "object": { "id": 36, "type": "payment_user", "name": "Payment Report", "entities": [ "user", "role_offer", "role_offer_user", "payment_user" ], "only_trashed": 0, "filters": null, "deleted_at": null, "created_at": "2024-08-08T10:32:42.000000Z", "updated_at": "2024-08-08T10:32:42.000000Z" }, "nice": [], "permissions": { "read": true, "update": false, "delete": false } } }, "permissions": { "read": true, "update": true, "delete": true, "share": true } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/report?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/report?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/report", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Report Module" ] }, "post": { "summary": "Create a report", "operationId": "createAReport", "description": "Creates a report definition and, unless it is scheduled, immediately queues it\nfor generation - so a 201 means the report exists, not that the file is ready.\nPoll the report until status becomes completed, then use the download endpoint.\nA scheduled report is stored with status scheduled and is not run now.\n\naccount_id and user_id are taken from the caller and cannot be set from the\nrequest; a value sent for either is overwritten. The response is the same shape\nas reading the report, so a follow-up read is not needed.\n\nInvalid input returns a 422 identifying the fields at fault. Some report types\nrequire more than the fields below - the inventory bundle type also requires\nmeta.bundle_template_id, for instance.\n\nSending _options.save_as_template also saves the report's type, category,\nfilters, columns, sorting, media, sub-account and file-type settings as a\nreusable report template. It requires the report:template:create permission and\nis silently skipped without it.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 21 ] }, "report_type_id": { "type": "integer", "examples": [ 36 ] }, "report_category_id": { "type": [ "string", "null" ], "examples": [ null ] }, "user_id": { "type": "integer", "examples": [ 23453473 ] }, "name": { "type": "string", "examples": [ "Payment Report" ] }, "filters": { "type": "array", "examples": [ [] ] }, "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "examples": [ "user ID" ] }, "label": { "type": "string", "examples": [ "user ID" ] }, "value": { "type": "string", "examples": [ "[user.id]" ] } } }, "examples": [ [ { "name": "user ID", "label": "user ID", "value": "[user.id]" }, { "name": "role_offer ID", "label": "role_offer ID", "value": "[role_offer.id]" }, { "name": "role_offer_user ID", "label": "role_offer_user ID", "value": "[role_offer_user.id]" }, { "name": "payment_user ID", "label": "payment_user ID", "value": "[payment_user.id]" } ] ] }, "sorting": { "type": "array", "examples": [ [] ] }, "grouping": { "type": "array", "examples": [ [] ] }, "with_media": { "type": "integer", "examples": [ 0 ] }, "with_subaccounts": { "type": "integer", "examples": [ 0 ] }, "file_path": { "type": [ "string", "null" ], "examples": [ null ] }, "file_type": { "type": "string", "examples": [ "xlsx" ] }, "status": { "type": "string", "examples": [ "queued" ] }, "error_message": { "type": [ "string", "null" ], "examples": [ null ] }, "is_scheduled": { "type": "integer", "examples": [ 0 ] }, "start_date": { "type": [ "string", "null" ], "examples": [ null ] }, "start_time": { "type": [ "string", "null" ], "examples": [ null ] }, "end_date": { "type": [ "string", "null" ], "examples": [ null ] }, "timezone": { "type": [ "string", "null" ], "examples": [ null ] }, "repeat": { "type": [ "string", "null" ], "examples": [ null ] }, "meta": { "type": "array", "examples": [ [] ] }, "last_generated_at": { "type": [ "string", "null" ], "examples": [ null ] }, "destination_meta": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:34.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:34.000000Z" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:report:21" ] }, "status": { "type": "string", "examples": [ "Queued" ] }, "columns_preview": { "type": "string", "examples": [ "user ID, role_offer ID, role_offer_user ID, payment_user ID" ] } } }, "relations": { "type": "object", "properties": { "report_type": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 36 ] }, "type": { "type": "string", "examples": [ "payment_user" ] }, "name": { "type": "string", "examples": [ "Payment Report" ] }, "entities": { "type": "array", "items": { "type": "string" }, "examples": [ [ "user", "role_offer", "role_offer_user", "payment_user" ] ] }, "only_trashed": { "type": "integer", "examples": [ 0 ] }, "filters": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2024-08-08T10:32:42.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2024-08-08T10:32:42.000000Z" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ false ] }, "delete": { "type": "boolean", "examples": [ false ] } } } } } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "share": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 21, "report_type_id": 36, "report_category_id": null, "user_id": 23453473, "name": "Payment Report", "filters": [], "columns": [ { "name": "user ID", "label": "user ID", "value": "[user.id]" }, { "name": "role_offer ID", "label": "role_offer ID", "value": "[role_offer.id]" }, { "name": "role_offer_user ID", "label": "role_offer_user ID", "value": "[role_offer_user.id]" }, { "name": "payment_user ID", "label": "payment_user ID", "value": "[payment_user.id]" } ], "sorting": [], "grouping": [], "with_media": 0, "with_subaccounts": 0, "file_path": null, "file_type": "xlsx", "status": "queued", "error_message": null, "is_scheduled": 0, "start_date": null, "start_time": null, "end_date": null, "timezone": null, "repeat": null, "meta": [], "last_generated_at": null, "destination_meta": null, "deleted_at": null, "created_at": "2026-06-09T05:36:34.000000Z", "updated_at": "2026-06-09T05:36:34.000000Z" }, "nice": { "rrn": "rrn:local:20101:report:21", "status": "Queued", "columns_preview": "user ID, role_offer ID, role_offer_user ID, payment_user ID" }, "relations": { "report_type": { "object": { "id": 36, "type": "payment_user", "name": "Payment Report", "entities": [ "user", "role_offer", "role_offer_user", "payment_user" ], "only_trashed": 0, "filters": null, "deleted_at": null, "created_at": "2024-08-08T10:32:42.000000Z", "updated_at": "2024-08-08T10:32:42.000000Z" }, "nice": [], "permissions": { "read": true, "update": false, "delete": false } } }, "permissions": { "read": true, "update": true, "delete": true, "share": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Report Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "report_type_id": { "type": "integer", "description": "The kind of data the report extracts, from the report type list. Determines which columns and filters are available. Treat it as fixed once the report exists: the update endpoint accepts the field, but changing the type of an existing report is not supported.", "examples": [ 36 ] }, "name": { "type": "string", "description": "Display name for the report, up to 255 characters. Also used as the report template name when _options.save_as_template is set on create.", "examples": [ "Payment Report" ] }, "file_type": { "type": "string", "description": "Output format of the generated file: xlsx or csv.", "examples": [ "xlsx" ] }, "filters": { "type": "array", "description": "Conditions restricting which records the report includes, as groups of {attribute, operator, value} objects. Rows missing an attribute or operator are dropped on save rather than rejected, so a report can come back with fewer filters than were sent.", "items": { "type": "object" }, "examples": [ [] ] }, "sorting": { "type": "array", "description": "Order to output rows in, as a list of {field, direction} objects where direction is asc or desc. Only sortable columns of the report's primary entity are applied; anything else is ignored.", "items": { "type": "object" }, "examples": [ [] ] }, "columns": { "type": "array", "description": "The columns to output, in order, as objects carrying at least a value such as \"[user.email]\" plus its name and label. Required, and limited to 60 columns of which at most 55 may be custom fields.", "items": { "type": "object" }, "examples": [ [ { "name": "user ID", "label": "user ID", "value": "[user.id]" }, { "name": "role_offer ID", "label": "role_offer ID", "value": "[role_offer.id]" }, { "name": "role_offer_user ID", "label": "role_offer_user ID", "value": "[role_offer_user.id]" }, { "name": "payment_user ID", "label": "payment_user ID", "value": "[payment_user.id]" } ] ] }, "with_media": { "type": "boolean", "description": "Whether to deliver the report as a zip containing the uploaded files its rows reference, rather than the spreadsheet on its own.", "examples": [ 0 ] }, "with_subaccounts": { "type": "boolean", "description": "Whether to include records belonging to accounts below this one in the hierarchy.", "examples": [ 0 ] }, "is_scheduled": { "type": "boolean", "description": "Whether the report runs on a schedule instead of immediately. Setting it makes the schedule fields required, and is capped by the account's max scheduled report limit. Leaving it false queues the report for generation as soon as the request returns, and clears any schedule already stored.", "examples": [ 0 ] }, "start_date": { "type": "string", "description": "First date the schedule runs, as YYYY-MM-DD. Required when is_scheduled is true.", "examples": [ null ] }, "start_time": { "type": "string", "description": "Time of day the schedule runs, as HH:MM in the report's timezone. Required when is_scheduled is true.", "examples": [ null ] }, "end_date": { "type": "string", "description": "Date the schedule stops running, as YYYY-MM-DD. Required when is_scheduled is true.", "examples": [ null ] }, "timezone": { "type": "string", "description": "Timezone the schedule's dates and times are interpreted in, as a tz database name such as Australia/Melbourne. Required when is_scheduled is true; defaults to the account's timezone.", "examples": [ null ] }, "repeat": { "type": "string", "description": "How often the schedule repeats, as an interval and unit joined by a pipe - \"1|day\", \"2|week\" or \"1|month\". Required when is_scheduled is true.", "examples": [ null ] }, "destination_meta": { "type": "object", "description": "Where a scheduled report delivers its file. source selects the transport, sftp or ftp, and the remaining keys configure it: sftp takes sftp_host, sftp_port, sftp_username, sftp_authentication (password or key), then sftp_password or sftp_privateKey, and an optional sftp_directory; ftp takes ftp_host, ftp_port, ftp_username, ftp_password, ftp_passive and ftp_ssl. Keys that do not belong to the chosen source are stripped on save, the whole object is discarded if is_scheduled is false, and credentials are stored encrypted.", "properties": {}, "examples": [ "{}" ] }, "meta": { "type": "object", "description": "Additional per-report-type options. use_field_value outputs the stored value of a custom field rather than its label. Some report types require their own subkeys - the inventory bundle type requires meta.bundle_template_id.", "properties": {}, "examples": [ [] ] }, "report_category_id": { "type": "integer", "description": "Optional category to file the report under. Reports left uncategorised return null.", "examples": [ 1 ] } }, "required": [ "report_type_id", "name", "file_type", "columns" ] } } } } } }, "/api/v2/report/{id}": { "get": { "summary": "Read a report", "operationId": "readAReport", "description": "Returns a single report's definition and current generation state. status moves\nthrough queued, processing and then completed or failed, and last_generated_at\nand file_path are only populated once a run has finished - use the download\nendpoint to obtain a link rather than reading file_path directly.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 21 ] }, "report_type_id": { "type": "integer", "examples": [ 36 ] }, "report_category_id": { "type": [ "string", "null" ], "examples": [ null ] }, "user_id": { "type": "integer", "examples": [ 23453473 ] }, "name": { "type": "string", "examples": [ "Payment Report" ] }, "filters": { "type": "array", "examples": [ [] ] }, "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "examples": [ "user ID" ] }, "label": { "type": "string", "examples": [ "user ID" ] }, "value": { "type": "string", "examples": [ "[user.id]" ] } } }, "examples": [ [ { "name": "user ID", "label": "user ID", "value": "[user.id]" }, { "name": "role_offer ID", "label": "role_offer ID", "value": "[role_offer.id]" }, { "name": "role_offer_user ID", "label": "role_offer_user ID", "value": "[role_offer_user.id]" }, { "name": "payment_user ID", "label": "payment_user ID", "value": "[payment_user.id]" } ] ] }, "sorting": { "type": "array", "examples": [ [] ] }, "grouping": { "type": "array", "examples": [ [] ] }, "with_media": { "type": "integer", "examples": [ 0 ] }, "with_subaccounts": { "type": "integer", "examples": [ 0 ] }, "file_path": { "type": [ "string", "null" ], "examples": [ null ] }, "file_type": { "type": "string", "examples": [ "xlsx" ] }, "status": { "type": "string", "examples": [ "queued" ] }, "error_message": { "type": [ "string", "null" ], "examples": [ null ] }, "is_scheduled": { "type": "integer", "examples": [ 0 ] }, "start_date": { "type": [ "string", "null" ], "examples": [ null ] }, "start_time": { "type": [ "string", "null" ], "examples": [ null ] }, "end_date": { "type": [ "string", "null" ], "examples": [ null ] }, "timezone": { "type": [ "string", "null" ], "examples": [ null ] }, "repeat": { "type": [ "string", "null" ], "examples": [ null ] }, "meta": { "type": "array", "examples": [ [] ] }, "last_generated_at": { "type": [ "string", "null" ], "examples": [ null ] }, "destination_meta": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:34.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:34.000000Z" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:report:21" ] }, "status": { "type": "string", "examples": [ "Queued" ] }, "columns_preview": { "type": "string", "examples": [ "user ID, role_offer ID, role_offer_user ID, payment_user ID" ] } } }, "relations": { "type": "object", "properties": { "report_type": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 36 ] }, "type": { "type": "string", "examples": [ "payment_user" ] }, "name": { "type": "string", "examples": [ "Payment Report" ] }, "entities": { "type": "array", "items": { "type": "string" }, "examples": [ [ "user", "role_offer", "role_offer_user", "payment_user" ] ] }, "only_trashed": { "type": "integer", "examples": [ 0 ] }, "filters": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2024-08-08T10:32:42.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2024-08-08T10:32:42.000000Z" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ false ] }, "delete": { "type": "boolean", "examples": [ false ] } } } } } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "share": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 21, "report_type_id": 36, "report_category_id": null, "user_id": 23453473, "name": "Payment Report", "filters": [], "columns": [ { "name": "user ID", "label": "user ID", "value": "[user.id]" }, { "name": "role_offer ID", "label": "role_offer ID", "value": "[role_offer.id]" }, { "name": "role_offer_user ID", "label": "role_offer_user ID", "value": "[role_offer_user.id]" }, { "name": "payment_user ID", "label": "payment_user ID", "value": "[payment_user.id]" } ], "sorting": [], "grouping": [], "with_media": 0, "with_subaccounts": 0, "file_path": null, "file_type": "xlsx", "status": "queued", "error_message": null, "is_scheduled": 0, "start_date": null, "start_time": null, "end_date": null, "timezone": null, "repeat": null, "meta": [], "last_generated_at": null, "destination_meta": null, "deleted_at": null, "created_at": "2026-06-09T05:36:34.000000Z", "updated_at": "2026-06-09T05:36:34.000000Z" }, "nice": { "rrn": "rrn:local:20101:report:21", "status": "Queued", "columns_preview": "user ID, role_offer ID, role_offer_user ID, payment_user ID" }, "relations": { "report_type": { "object": { "id": 36, "type": "payment_user", "name": "Payment Report", "entities": [ "user", "role_offer", "role_offer_user", "payment_user" ], "only_trashed": 0, "filters": null, "deleted_at": null, "created_at": "2024-08-08T10:32:42.000000Z", "updated_at": "2024-08-08T10:32:42.000000Z" }, "nice": [], "permissions": { "read": true, "update": false, "delete": false } } }, "permissions": { "read": true, "update": true, "delete": true, "share": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Report Module" ] }, "put": { "summary": "Update a report", "operationId": "updateAReport", "description": "Updates the fields supplied and leaves the rest untouched, then returns the\nreport in the same shape as reading it. Every field is optional.\n\nUpdating a report that is not scheduled re-queues it: status is reset to queued,\nerror_message is cleared and generation starts again. So this endpoint is also\nhow a report is re-run with different columns or filters. Turning is_scheduled\noff clears the whole schedule - start_date, start_time, end_date, timezone,\nrepeat and destination_meta are all nulled.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 21 ] }, "report_type_id": { "type": "integer", "examples": [ 36 ] }, "report_category_id": { "type": [ "string", "null" ], "examples": [ null ] }, "user_id": { "type": "integer", "examples": [ 23453473 ] }, "name": { "type": "string", "examples": [ "Payment Report" ] }, "filters": { "type": "array", "examples": [ [] ] }, "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "examples": [ "user ID" ] }, "label": { "type": "string", "examples": [ "user ID" ] }, "value": { "type": "string", "examples": [ "[user.id]" ] } } }, "examples": [ [ { "name": "user ID", "label": "user ID", "value": "[user.id]" }, { "name": "role_offer ID", "label": "role_offer ID", "value": "[role_offer.id]" }, { "name": "role_offer_user ID", "label": "role_offer_user ID", "value": "[role_offer_user.id]" }, { "name": "payment_user ID", "label": "payment_user ID", "value": "[payment_user.id]" } ] ] }, "sorting": { "type": "array", "examples": [ [] ] }, "grouping": { "type": "array", "examples": [ [] ] }, "with_media": { "type": "integer", "examples": [ 0 ] }, "with_subaccounts": { "type": "integer", "examples": [ 0 ] }, "file_path": { "type": [ "string", "null" ], "examples": [ null ] }, "file_type": { "type": "string", "examples": [ "xlsx" ] }, "status": { "type": "string", "examples": [ "queued" ] }, "error_message": { "type": [ "string", "null" ], "examples": [ null ] }, "is_scheduled": { "type": "integer", "examples": [ 0 ] }, "start_date": { "type": [ "string", "null" ], "examples": [ null ] }, "start_time": { "type": [ "string", "null" ], "examples": [ null ] }, "end_date": { "type": [ "string", "null" ], "examples": [ null ] }, "timezone": { "type": [ "string", "null" ], "examples": [ null ] }, "repeat": { "type": [ "string", "null" ], "examples": [ null ] }, "meta": { "type": "array", "examples": [ [] ] }, "last_generated_at": { "type": [ "string", "null" ], "examples": [ null ] }, "destination_meta": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:34.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:34.000000Z" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:report:21" ] }, "status": { "type": "string", "examples": [ "Queued" ] }, "columns_preview": { "type": "string", "examples": [ "user ID, role_offer ID, role_offer_user ID, payment_user ID" ] } } }, "relations": { "type": "object", "properties": { "report_type": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 36 ] }, "type": { "type": "string", "examples": [ "payment_user" ] }, "name": { "type": "string", "examples": [ "Payment Report" ] }, "entities": { "type": "array", "items": { "type": "string" }, "examples": [ [ "user", "role_offer", "role_offer_user", "payment_user" ] ] }, "only_trashed": { "type": "integer", "examples": [ 0 ] }, "filters": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2024-08-08T10:32:42.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2024-08-08T10:32:42.000000Z" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ false ] }, "delete": { "type": "boolean", "examples": [ false ] } } } } } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "share": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 21, "report_type_id": 36, "report_category_id": null, "user_id": 23453473, "name": "Payment Report", "filters": [], "columns": [ { "name": "user ID", "label": "user ID", "value": "[user.id]" }, { "name": "role_offer ID", "label": "role_offer ID", "value": "[role_offer.id]" }, { "name": "role_offer_user ID", "label": "role_offer_user ID", "value": "[role_offer_user.id]" }, { "name": "payment_user ID", "label": "payment_user ID", "value": "[payment_user.id]" } ], "sorting": [], "grouping": [], "with_media": 0, "with_subaccounts": 0, "file_path": null, "file_type": "xlsx", "status": "queued", "error_message": null, "is_scheduled": 0, "start_date": null, "start_time": null, "end_date": null, "timezone": null, "repeat": null, "meta": [], "last_generated_at": null, "destination_meta": null, "deleted_at": null, "created_at": "2026-06-09T05:36:34.000000Z", "updated_at": "2026-06-09T05:36:34.000000Z" }, "nice": { "rrn": "rrn:local:20101:report:21", "status": "Queued", "columns_preview": "user ID, role_offer ID, role_offer_user ID, payment_user ID" }, "relations": { "report_type": { "object": { "id": 36, "type": "payment_user", "name": "Payment Report", "entities": [ "user", "role_offer", "role_offer_user", "payment_user" ], "only_trashed": 0, "filters": null, "deleted_at": null, "created_at": "2024-08-08T10:32:42.000000Z", "updated_at": "2024-08-08T10:32:42.000000Z" }, "nice": [], "permissions": { "read": true, "update": false, "delete": false } } }, "permissions": { "read": true, "update": true, "delete": true, "share": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Report Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "report_type_id": { "type": "integer", "description": "The kind of data the report extracts, from the report type list. Determines which columns and filters are available. Treat it as fixed once the report exists: the update endpoint accepts the field, but changing the type of an existing report is not supported.", "examples": [ 36 ] }, "user_id": { "type": "integer", "description": "The report owner, who receives the completion notification. Set from the caller on create and ignored if sent; supplying it on update reassigns the report to another user.", "examples": [ 23453473 ] }, "name": { "type": "string", "description": "Display name for the report, up to 255 characters. Also used as the report template name when _options.save_as_template is set on create.", "examples": [ "Payment Report" ] }, "file_type": { "type": "string", "description": "Output format of the generated file: xlsx or csv.", "examples": [ "xlsx" ] }, "filters": { "type": "array", "description": "Conditions restricting which records the report includes, as groups of {attribute, operator, value} objects. Rows missing an attribute or operator are dropped on save rather than rejected, so a report can come back with fewer filters than were sent.", "items": { "type": "object" }, "examples": [ [] ] }, "sorting": { "type": "array", "description": "Order to output rows in, as a list of {field, direction} objects where direction is asc or desc. Only sortable columns of the report's primary entity are applied; anything else is ignored.", "items": { "type": "object" }, "examples": [ [] ] }, "columns": { "type": "array", "description": "The columns to output, in order, as objects carrying at least a value such as \"[user.email]\" plus its name and label. Required, and limited to 60 columns of which at most 55 may be custom fields.", "items": { "type": "object" }, "examples": [ [ { "name": "user ID", "label": "user ID", "value": "[user.id]" }, { "name": "role_offer ID", "label": "role_offer ID", "value": "[role_offer.id]" }, { "name": "role_offer_user ID", "label": "role_offer_user ID", "value": "[role_offer_user.id]" }, { "name": "payment_user ID", "label": "payment_user ID", "value": "[payment_user.id]" } ] ] }, "with_media": { "type": "boolean", "description": "Whether to deliver the report as a zip containing the uploaded files its rows reference, rather than the spreadsheet on its own.", "examples": [ 0 ] }, "with_subaccounts": { "type": "boolean", "description": "Whether to include records belonging to accounts below this one in the hierarchy.", "examples": [ 0 ] }, "is_scheduled": { "type": "boolean", "description": "Whether the report runs on a schedule instead of immediately. Setting it makes the schedule fields required, and is capped by the account's max scheduled report limit. Leaving it false queues the report for generation as soon as the request returns, and clears any schedule already stored.", "examples": [ 0 ] }, "start_date": { "type": "string", "description": "First date the schedule runs, as YYYY-MM-DD. Required when is_scheduled is true.", "examples": [ null ] }, "start_time": { "type": "string", "description": "Time of day the schedule runs, as HH:MM in the report's timezone. Required when is_scheduled is true.", "examples": [ null ] }, "end_date": { "type": "string", "description": "Date the schedule stops running, as YYYY-MM-DD. Required when is_scheduled is true.", "examples": [ null ] }, "timezone": { "type": "string", "description": "Timezone the schedule's dates and times are interpreted in, as a tz database name such as Australia/Melbourne. Required when is_scheduled is true; defaults to the account's timezone.", "examples": [ null ] }, "repeat": { "type": "string", "description": "How often the schedule repeats, as an interval and unit joined by a pipe - \"1|day\", \"2|week\" or \"1|month\". Required when is_scheduled is true.", "examples": [ null ] }, "destination_meta": { "type": "object", "description": "Where a scheduled report delivers its file. source selects the transport, sftp or ftp, and the remaining keys configure it: sftp takes sftp_host, sftp_port, sftp_username, sftp_authentication (password or key), then sftp_password or sftp_privateKey, and an optional sftp_directory; ftp takes ftp_host, ftp_port, ftp_username, ftp_password, ftp_passive and ftp_ssl. Keys that do not belong to the chosen source are stripped on save, the whole object is discarded if is_scheduled is false, and credentials are stored encrypted.", "properties": {}, "examples": [ "{}" ] }, "meta": { "type": "object", "description": "Additional per-report-type options. use_field_value outputs the stored value of a custom field rather than its label. Some report types require their own subkeys - the inventory bundle type requires meta.bundle_template_id.", "properties": {}, "examples": [ [] ] }, "report_category_id": { "type": "integer", "description": "Optional category to file the report under. Reports left uncategorised return null.", "examples": [ 1 ] } } } } } } }, "delete": { "summary": "Delete a report", "operationId": "deleteAReport", "description": "Deletes the report definition, its schedule and the record of any file it has\ngenerated.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "204": { "description": "No content, successful deletion", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Report Module" ] }, "parameters": [ { "in": "path", "name": "id", "description": "The ID of the report.", "required": true, "schema": { "type": "integer", "examples": [ 21 ] } } ] }, "/api/v2/headcount/roleoffer": { "get": { "summary": "List role offers", "operationId": "listRoleOffers", "description": "Returns the account's role offers. Pass a page parameter to receive a paginated\nenvelope; without one, every matching role offer is returned as a flat array.\n\nSet demand_available=1 to return only role offers that still have unfilled\ndemand, which is the usual way to build a list of roles someone can apply for.\n\nThis endpoint does not require authentication, but an anonymous caller only\nreceives results on an account that has public browsing switched on.", "parameters": [ { "in": "query", "name": "demand_available", "description": "Return only role offers with unfilled demand.", "required": false, "schema": { "type": "boolean", "description": "Return only role offers with unfilled demand.", "examples": [ true ] } }, { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "query", "name": "extras", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "required": false, "schema": { "type": "array", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "items": { "type": "string", "enum": [ "demand", "status", "rules", "shift_count" ] }, "examples": [ [ "demand" ] ] } }, { "in": "query", "name": "with", "description": "A list of relations to include in the response. May be single records or collections.\nIt is often more efficient to retrieve this way, to avoid follow-up API calls.", "required": false, "schema": { "type": "array", "description": "A list of relations to include in the response. May be single records or collections.\nIt is often more efficient to retrieve this way, to avoid follow-up API calls.", "items": { "type": "string", "enum": [ "functional_area_type", "location_type", "hasManyDeepFromRelationsWithConstraints", "hasOneDeepFromRelationsWithConstraints", "hasManyDeepFromReverse", "hasOneDeepFromReverse" ] }, "examples": [ [ "functional_area_type" ] ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "headcount_functional_area_job_title_id": { "type": "integer", "examples": [ 1 ] }, "headcount_location_venue_id": { "type": "integer", "examples": [ 10 ] }, "journey_id": { "type": [ "string", "null" ], "examples": [ null ] }, "role_offer_template_id": { "type": [ "string", "null" ], "examples": [ null ] }, "user_type_id": { "type": "integer", "examples": [ 2 ] }, "certificate_id": { "type": [ "string", "null" ], "examples": [ null ] }, "static_demand": { "type": "integer", "examples": [ 12 ] }, "reserve_demand": { "type": "integer", "examples": [ 0 ] }, "waitlist_demand": { "type": "integer", "examples": [ 0 ] }, "confidence_level": { "type": "integer", "examples": [ 0 ] }, "calculate_demand": { "type": "integer", "examples": [ 0 ] }, "refund_on_application_withdraw": { "type": "integer", "examples": [ 0 ] }, "refund_on_role_offer_complete": { "type": "integer", "examples": [ 0 ] }, "user_per_shift": { "type": "integer", "examples": [ 0 ] }, "peak_shift": { "type": "integer", "examples": [ 0 ] }, "min_demand": { "type": "integer", "examples": [ 0 ] }, "number_of_shifts_per_day": { "type": "integer", "examples": [ 0 ] }, "min_number_shift_users": { "type": "integer", "examples": [ 0 ] }, "max_number_shift_users": { "type": "integer", "examples": [ 0 ] }, "start_date": { "type": [ "string", "null" ], "examples": [ null ] }, "end_date": { "type": [ "string", "null" ], "examples": [ null ] }, "role_feedback_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "secondary_assignment_demand": { "type": "integer", "examples": [ 0 ] }, "rules": { "type": "array", "examples": [ [] ] }, "ranking": { "type": [ "string", "null" ], "examples": [ null ] }, "expires_in": { "type": "integer", "examples": [ 0 ] }, "preassign_enabled": { "type": "integer", "examples": [ 1 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "accept_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "reject_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "payment": { "type": [ "string", "null" ], "examples": [ null ] }, "publish": { "type": "integer", "examples": [ 1 ] }, "promoted": { "type": "integer", "examples": [ 0 ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "is_refund_allowed": { "type": "integer", "examples": [ 0 ] }, "created_by": { "type": [ "string", "null" ], "examples": [ null ] }, "grid_image": { "type": [ "string", "null" ], "examples": [ null ] }, "banner_image": { "type": [ "string", "null" ], "examples": [ null ] }, "public": { "type": "integer", "examples": [ 0 ] }, "approval_status": { "type": "string", "examples": [ "approved" ] }, "approval_reason": { "type": [ "string", "null" ], "examples": [ null ] }, "visibility_show_groups": { "type": "array", "examples": [ [] ] }, "visibility_hide_groups": { "type": "array", "examples": [ [] ] }, "can_self_apply": { "type": "integer", "examples": [ 0 ] }, "application_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "withdraw_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "allows_application_withdrawals": { "type": "integer", "examples": [ 0 ] }, "timezone": { "type": [ "string", "null" ], "examples": [ null ] }, "apps_open_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "apps_close_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "withdraw_close_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "applied_status_default": { "type": [ "string", "null" ], "examples": [ null ] }, "withdrawn_status_default": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_complete_status_default": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "strict_applications_enabled": { "type": "integer", "examples": [ 0 ] }, "waitlist_auto_invitation_enabled": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:31.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "description": { "type": "string", "examples": [ "" ] }, "tags": { "type": [ "string", "null" ], "examples": [ null ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:role_offer:1" ] }, "accept_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "accept_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "accept_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "allows_application_withdrawals": { "type": "string", "examples": [ "No" ] }, "application_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "application_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "application_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "applied_status_default": { "type": [ "string", "null" ], "examples": [ null ] }, "applied_status_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "applied_status_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "approval_status": { "type": "string", "examples": [ "Approved" ] }, "approval_status:value": { "type": "string", "examples": [ "approved" ] }, "approval_status:array": { "type": "string", "examples": [ "Approved" ] }, "banner_image": { "type": "string", "examples": [ "" ] }, "calculate_demand": { "type": "string", "examples": [ "No" ] }, "can_self_apply": { "type": "string", "examples": [ "No" ] }, "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "feedback_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "feedback_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "feedback_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "grid_image": { "type": "string", "examples": [ "" ] }, "headcount_functional_area_job_title_id": { "type": "string", "examples": [ "Accreditation > Veterinary Technician" ] }, "headcount_functional_area_job_title_id:value": { "type": "integer", "examples": [ 1 ] }, "headcount_functional_area_job_title_id:array": { "type": "string", "examples": [ "Accreditation > Veterinary Technician" ] }, "headcount_location_venue_id": { "type": "string", "examples": [ "Melbourne > Dot Etcher" ] }, "headcount_location_venue_id:value": { "type": "integer", "examples": [ 10 ] }, "headcount_location_venue_id:array": { "type": "string", "examples": [ "Melbourne > Dot Etcher" ] }, "is_refund_allowed": { "type": "string", "examples": [ "No" ] }, "journey_complete_status_default": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_complete_status_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_complete_status_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_id": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_age": { "type": "string", "examples": [ "" ] }, "preassign_enabled": { "type": "string", "examples": [ "Yes" ] }, "promoted": { "type": "string", "examples": [ "No" ] }, "public": { "type": "string", "examples": [ "No" ] }, "publish": { "type": "string", "examples": [ "Yes" ] }, "reject_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "reject_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "reject_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "tags": { "type": [ "string", "null" ], "examples": [ null ] }, "tags:value": { "type": [ "string", "null" ], "examples": [ null ] }, "tags:array": { "type": [ "string", "null" ], "examples": [ null ] }, "training_ids": { "type": "string", "examples": [ "Paper Goods Machine Operator_EBMsffvoa9Ht" ] }, "training_ids:value": { "type": "string", "examples": [ "" ] }, "training_ids:array": { "type": "array", "items": { "type": "string" }, "examples": [ [ "Paper Goods Machine Operator_EBMsffvoa9Ht" ] ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "user_type_id": { "type": "string", "examples": [ "Default" ] }, "user_type_id:value": { "type": "integer", "examples": [ 2 ] }, "user_type_id:array": { "type": "string", "examples": [ "Default" ] }, "visibility_hide_groups": { "type": "string", "examples": [ "" ] }, "visibility_show_groups": { "type": "string", "examples": [ "" ] }, "withdraw_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "withdraw_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "withdraw_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "withdrawn_status_default": { "type": [ "string", "null" ], "examples": [ null ] }, "withdrawn_status_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "withdrawn_status_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "account_url": { "type": "string", "examples": [ "https://sub.rosterfy2.localhost.com/" ] }, "confidence_level": { "type": "string", "examples": [ "0%" ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "accept": { "type": "boolean", "examples": [ false ] }, "reject": { "type": "boolean", "examples": [ false ] }, "withdraw": { "type": "boolean", "examples": [ false ] }, "apply": { "type": "boolean", "examples": [ false ] }, "apply_error": { "type": "string", "examples": [ "Role offer not accepting applications at this time" ] }, "apply_error_code": { "type": "integer", "examples": [ 1030 ] }, "update_application_form": { "type": "boolean", "examples": [ false ] } } } } }, "examples": [ [ { "object": { "id": 1, "headcount_functional_area_job_title_id": 1, "headcount_location_venue_id": 10, "journey_id": null, "role_offer_template_id": null, "user_type_id": 2, "certificate_id": null, "static_demand": 12, "reserve_demand": 0, "waitlist_demand": 0, "confidence_level": 0, "calculate_demand": 0, "refund_on_application_withdraw": 0, "refund_on_role_offer_complete": 0, "user_per_shift": 0, "peak_shift": 0, "min_demand": 0, "number_of_shifts_per_day": 0, "min_number_shift_users": 0, "max_number_shift_users": 0, "start_date": null, "end_date": null, "role_feedback_form_id": null, "secondary_assignment_demand": 0, "rules": [], "ranking": null, "expires_in": 0, "preassign_enabled": 1, "sort_order": 0, "accept_form_id": null, "reject_form_id": null, "training_ids": [ 1 ], "payment": null, "publish": 1, "promoted": 0, "is_archived": 0, "is_refund_allowed": 0, "created_by": null, "grid_image": null, "banner_image": null, "public": 0, "approval_status": "approved", "approval_reason": null, "visibility_show_groups": [], "visibility_hide_groups": [], "can_self_apply": 0, "application_form_id": null, "withdraw_form_id": null, "allows_application_withdrawals": 0, "timezone": null, "apps_open_timestamp": null, "apps_close_timestamp": null, "withdraw_close_timestamp": null, "minimum_dob": null, "minimum_age": null, "maximum_dob": null, "maximum_age": null, "applied_status_default": null, "withdrawn_status_default": null, "journey_complete_status_default": null, "deleted_at": null, "is_erased": 0, "strict_applications_enabled": 0, "waitlist_auto_invitation_enabled": 0, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:31.000000Z", "deleted_by": null, "description": "", "tags": null }, "nice": { "rrn": "rrn:local:20101:role_offer:1", "accept_form_id": null, "accept_form_id:value": null, "accept_form_id:array": null, "allows_application_withdrawals": "No", "application_form_id": null, "application_form_id:value": null, "application_form_id:array": null, "applied_status_default": null, "applied_status_default:value": null, "applied_status_default:array": null, "approval_status": "Approved", "approval_status:value": "approved", "approval_status:array": "Approved", "banner_image": "", "calculate_demand": "No", "can_self_apply": "No", "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "feedback_form_id": null, "feedback_form_id:value": null, "feedback_form_id:array": null, "grid_image": "", "headcount_functional_area_job_title_id": "Accreditation > Veterinary Technician", "headcount_functional_area_job_title_id:value": 1, "headcount_functional_area_job_title_id:array": "Accreditation > Veterinary Technician", "headcount_location_venue_id": "Melbourne > Dot Etcher", "headcount_location_venue_id:value": 10, "headcount_location_venue_id:array": "Melbourne > Dot Etcher", "is_refund_allowed": "No", "journey_complete_status_default": null, "journey_complete_status_default:value": null, "journey_complete_status_default:array": null, "journey_id": null, "journey_id:value": null, "journey_id:array": null, "minimum_age": "", "preassign_enabled": "Yes", "promoted": "No", "public": "No", "publish": "Yes", "reject_form_id": null, "reject_form_id:value": null, "reject_form_id:array": null, "tags": null, "tags:value": null, "tags:array": null, "training_ids": "Paper Goods Machine Operator_EBMsffvoa9Ht", "training_ids:value": "", "training_ids:array": [ "Paper Goods Machine Operator_EBMsffvoa9Ht" ], "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "user_type_id": "Default", "user_type_id:value": 2, "user_type_id:array": "Default", "visibility_hide_groups": "", "visibility_show_groups": "", "withdraw_form_id": null, "withdraw_form_id:value": null, "withdraw_form_id:array": null, "withdrawn_status_default": null, "withdrawn_status_default:value": null, "withdrawn_status_default:array": null, "account_id": 20101, "account_url": "https://sub.rosterfy2.localhost.com/", "confidence_level": "0%" }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "accept": false, "reject": false, "withdraw": false, "apply": false, "apply_error": "Role offer not accepting applications at this time", "apply_error_code": 1030, "update_application_form": false } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/headcount/roleoffer?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/headcount/roleoffer?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/headcount/roleoffer" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 1, "headcount_functional_area_job_title_id": 1, "headcount_location_venue_id": 10, "journey_id": null, "role_offer_template_id": null, "user_type_id": 2, "certificate_id": null, "static_demand": 12, "reserve_demand": 0, "waitlist_demand": 0, "confidence_level": 0, "calculate_demand": 0, "refund_on_application_withdraw": 0, "refund_on_role_offer_complete": 0, "user_per_shift": 0, "peak_shift": 0, "min_demand": 0, "number_of_shifts_per_day": 0, "min_number_shift_users": 0, "max_number_shift_users": 0, "start_date": null, "end_date": null, "role_feedback_form_id": null, "secondary_assignment_demand": 0, "rules": [], "ranking": null, "expires_in": 0, "preassign_enabled": 1, "sort_order": 0, "accept_form_id": null, "reject_form_id": null, "training_ids": [ 1 ], "payment": null, "publish": 1, "promoted": 0, "is_archived": 0, "is_refund_allowed": 0, "created_by": null, "grid_image": null, "banner_image": null, "public": 0, "approval_status": "approved", "approval_reason": null, "visibility_show_groups": [], "visibility_hide_groups": [], "can_self_apply": 0, "application_form_id": null, "withdraw_form_id": null, "allows_application_withdrawals": 0, "timezone": null, "apps_open_timestamp": null, "apps_close_timestamp": null, "withdraw_close_timestamp": null, "minimum_dob": null, "minimum_age": null, "maximum_dob": null, "maximum_age": null, "applied_status_default": null, "withdrawn_status_default": null, "journey_complete_status_default": null, "deleted_at": null, "is_erased": 0, "strict_applications_enabled": 0, "waitlist_auto_invitation_enabled": 0, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:31.000000Z", "deleted_by": null, "description": "", "tags": null }, "nice": { "rrn": "rrn:local:20101:role_offer:1", "accept_form_id": null, "accept_form_id:value": null, "accept_form_id:array": null, "allows_application_withdrawals": "No", "application_form_id": null, "application_form_id:value": null, "application_form_id:array": null, "applied_status_default": null, "applied_status_default:value": null, "applied_status_default:array": null, "approval_status": "Approved", "approval_status:value": "approved", "approval_status:array": "Approved", "banner_image": "", "calculate_demand": "No", "can_self_apply": "No", "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "feedback_form_id": null, "feedback_form_id:value": null, "feedback_form_id:array": null, "grid_image": "", "headcount_functional_area_job_title_id": "Accreditation > Veterinary Technician", "headcount_functional_area_job_title_id:value": 1, "headcount_functional_area_job_title_id:array": "Accreditation > Veterinary Technician", "headcount_location_venue_id": "Melbourne > Dot Etcher", "headcount_location_venue_id:value": 10, "headcount_location_venue_id:array": "Melbourne > Dot Etcher", "is_refund_allowed": "No", "journey_complete_status_default": null, "journey_complete_status_default:value": null, "journey_complete_status_default:array": null, "journey_id": null, "journey_id:value": null, "journey_id:array": null, "minimum_age": "", "preassign_enabled": "Yes", "promoted": "No", "public": "No", "publish": "Yes", "reject_form_id": null, "reject_form_id:value": null, "reject_form_id:array": null, "tags": null, "tags:value": null, "tags:array": null, "training_ids": "Paper Goods Machine Operator_EBMsffvoa9Ht", "training_ids:value": "", "training_ids:array": [ "Paper Goods Machine Operator_EBMsffvoa9Ht" ], "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "user_type_id": "Default", "user_type_id:value": 2, "user_type_id:array": "Default", "visibility_hide_groups": "", "visibility_show_groups": "", "withdraw_form_id": null, "withdraw_form_id:value": null, "withdraw_form_id:array": null, "withdrawn_status_default": null, "withdrawn_status_default:value": null, "withdrawn_status_default:array": null, "account_id": 20101, "account_url": "https://sub.rosterfy2.localhost.com/", "confidence_level": "0%" }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "accept": false, "reject": false, "withdraw": false, "apply": false, "apply_error": "Role offer not accepting applications at this time", "apply_error_code": 1030, "update_application_form": false } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/headcount/roleoffer?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/headcount/roleoffer?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/headcount/roleoffer", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Role Offer Module" ] }, "post": { "summary": "Create a role offer", "operationId": "createARoleOffer", "description": "Creates a role offer and returns it in the same shape as reading one, so a\nfollow-up read is not needed. A role offer is unique on the combination of job\ntitle and venue; reusing a pair that already has one is refused.\n\nThe account's own attribute configuration takes precedence over the fields\nlisted below. Where an attribute is configured for role offers, its definition\nreplaces the rule documented here, which can change both the accepted format and\nwhether the field is required. The presence flags below reflect what the endpoint\nactually enforces on a default configuration.\n\nSupplying role_offer_template_id copies the template's values over anything sent\nalongside it, so a templated create ignores most of the body. A field can only be\nkept by sending {field}:override=1 next to it, and only by a caller allowed to\noverride template-locked fields.\n\nDemand is expressed one of two ways. With calculate_demand unset or 0, set\nstatic_demand to the number of people needed. With calculate_demand=1, demand is\nderived from user_per_shift, number_of_shifts_per_day, start_date and end_date\ninstead.\n\nInvalid input returns a 422 identifying the fields at fault. Sending both\nminimum_dob and minimum_age is rejected, as they are two ways to say one thing.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "headcount_functional_area_job_title_id": { "type": "integer", "examples": [ 1 ] }, "headcount_location_venue_id": { "type": "integer", "examples": [ 10 ] }, "journey_id": { "type": [ "string", "null" ], "examples": [ null ] }, "role_offer_template_id": { "type": [ "string", "null" ], "examples": [ null ] }, "user_type_id": { "type": "integer", "examples": [ 2 ] }, "certificate_id": { "type": [ "string", "null" ], "examples": [ null ] }, "static_demand": { "type": "integer", "examples": [ 12 ] }, "reserve_demand": { "type": "integer", "examples": [ 0 ] }, "waitlist_demand": { "type": "integer", "examples": [ 0 ] }, "confidence_level": { "type": "integer", "examples": [ 0 ] }, "calculate_demand": { "type": "integer", "examples": [ 0 ] }, "refund_on_application_withdraw": { "type": "integer", "examples": [ 0 ] }, "refund_on_role_offer_complete": { "type": "integer", "examples": [ 0 ] }, "user_per_shift": { "type": "integer", "examples": [ 0 ] }, "peak_shift": { "type": "integer", "examples": [ 0 ] }, "min_demand": { "type": "integer", "examples": [ 0 ] }, "number_of_shifts_per_day": { "type": "integer", "examples": [ 0 ] }, "min_number_shift_users": { "type": "integer", "examples": [ 0 ] }, "max_number_shift_users": { "type": "integer", "examples": [ 0 ] }, "start_date": { "type": [ "string", "null" ], "examples": [ null ] }, "end_date": { "type": [ "string", "null" ], "examples": [ null ] }, "role_feedback_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "secondary_assignment_demand": { "type": "integer", "examples": [ 0 ] }, "rules": { "type": "array", "examples": [ [] ] }, "ranking": { "type": [ "string", "null" ], "examples": [ null ] }, "expires_in": { "type": "integer", "examples": [ 0 ] }, "preassign_enabled": { "type": "integer", "examples": [ 1 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "accept_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "reject_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "payment": { "type": [ "string", "null" ], "examples": [ null ] }, "publish": { "type": "integer", "examples": [ 1 ] }, "promoted": { "type": "integer", "examples": [ 0 ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "is_refund_allowed": { "type": "integer", "examples": [ 0 ] }, "created_by": { "type": [ "string", "null" ], "examples": [ null ] }, "grid_image": { "type": [ "string", "null" ], "examples": [ null ] }, "banner_image": { "type": [ "string", "null" ], "examples": [ null ] }, "public": { "type": "integer", "examples": [ 0 ] }, "approval_status": { "type": "string", "examples": [ "approved" ] }, "approval_reason": { "type": [ "string", "null" ], "examples": [ null ] }, "visibility_show_groups": { "type": "array", "examples": [ [] ] }, "visibility_hide_groups": { "type": "array", "examples": [ [] ] }, "can_self_apply": { "type": "integer", "examples": [ 0 ] }, "application_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "withdraw_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "allows_application_withdrawals": { "type": "integer", "examples": [ 0 ] }, "timezone": { "type": [ "string", "null" ], "examples": [ null ] }, "apps_open_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "apps_close_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "withdraw_close_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "applied_status_default": { "type": [ "string", "null" ], "examples": [ null ] }, "withdrawn_status_default": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_complete_status_default": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "strict_applications_enabled": { "type": "integer", "examples": [ 0 ] }, "waitlist_auto_invitation_enabled": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:31.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "description": { "type": "string", "examples": [ "" ] }, "tags": { "type": [ "string", "null" ], "examples": [ null ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:role_offer:1" ] }, "accept_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "accept_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "accept_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "allows_application_withdrawals": { "type": "string", "examples": [ "No" ] }, "application_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "application_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "application_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "applied_status_default": { "type": [ "string", "null" ], "examples": [ null ] }, "applied_status_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "applied_status_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "approval_status": { "type": "string", "examples": [ "Approved" ] }, "approval_status:value": { "type": "string", "examples": [ "approved" ] }, "approval_status:array": { "type": "string", "examples": [ "Approved" ] }, "banner_image": { "type": "string", "examples": [ "" ] }, "calculate_demand": { "type": "string", "examples": [ "No" ] }, "can_self_apply": { "type": "string", "examples": [ "No" ] }, "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "feedback_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "feedback_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "feedback_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "grid_image": { "type": "string", "examples": [ "" ] }, "headcount_functional_area_job_title_id": { "type": "string", "examples": [ "Accreditation > Veterinary Technician" ] }, "headcount_functional_area_job_title_id:value": { "type": "integer", "examples": [ 1 ] }, "headcount_functional_area_job_title_id:array": { "type": "string", "examples": [ "Accreditation > Veterinary Technician" ] }, "headcount_location_venue_id": { "type": "string", "examples": [ "Melbourne > Dot Etcher" ] }, "headcount_location_venue_id:value": { "type": "integer", "examples": [ 10 ] }, "headcount_location_venue_id:array": { "type": "string", "examples": [ "Melbourne > Dot Etcher" ] }, "is_refund_allowed": { "type": "string", "examples": [ "No" ] }, "journey_complete_status_default": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_complete_status_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_complete_status_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_id": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_age": { "type": "string", "examples": [ "" ] }, "preassign_enabled": { "type": "string", "examples": [ "Yes" ] }, "promoted": { "type": "string", "examples": [ "No" ] }, "public": { "type": "string", "examples": [ "No" ] }, "publish": { "type": "string", "examples": [ "Yes" ] }, "reject_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "reject_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "reject_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "tags": { "type": [ "string", "null" ], "examples": [ null ] }, "tags:value": { "type": [ "string", "null" ], "examples": [ null ] }, "tags:array": { "type": [ "string", "null" ], "examples": [ null ] }, "training_ids": { "type": "string", "examples": [ "Paper Goods Machine Operator_EBMsffvoa9Ht" ] }, "training_ids:value": { "type": "string", "examples": [ "" ] }, "training_ids:array": { "type": "array", "items": { "type": "string" }, "examples": [ [ "Paper Goods Machine Operator_EBMsffvoa9Ht" ] ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "user_type_id": { "type": "string", "examples": [ "Default" ] }, "user_type_id:value": { "type": "integer", "examples": [ 2 ] }, "user_type_id:array": { "type": "string", "examples": [ "Default" ] }, "visibility_hide_groups": { "type": "string", "examples": [ "" ] }, "visibility_show_groups": { "type": "string", "examples": [ "" ] }, "withdraw_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "withdraw_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "withdraw_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "withdrawn_status_default": { "type": [ "string", "null" ], "examples": [ null ] }, "withdrawn_status_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "withdrawn_status_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "account_url": { "type": "string", "examples": [ "https://sub.rosterfy2.localhost.com/" ] }, "confidence_level": { "type": "string", "examples": [ "0%" ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "accept": { "type": "boolean", "examples": [ false ] }, "reject": { "type": "boolean", "examples": [ false ] }, "withdraw": { "type": "boolean", "examples": [ false ] }, "apply": { "type": "boolean", "examples": [ false ] }, "apply_error": { "type": "string", "examples": [ "Role offer not accepting applications at this time" ] }, "apply_error_code": { "type": "integer", "examples": [ 1030 ] }, "update_application_form": { "type": "boolean", "examples": [ false ] } } } }, "examples": [ { "object": { "id": 1, "headcount_functional_area_job_title_id": 1, "headcount_location_venue_id": 10, "journey_id": null, "role_offer_template_id": null, "user_type_id": 2, "certificate_id": null, "static_demand": 12, "reserve_demand": 0, "waitlist_demand": 0, "confidence_level": 0, "calculate_demand": 0, "refund_on_application_withdraw": 0, "refund_on_role_offer_complete": 0, "user_per_shift": 0, "peak_shift": 0, "min_demand": 0, "number_of_shifts_per_day": 0, "min_number_shift_users": 0, "max_number_shift_users": 0, "start_date": null, "end_date": null, "role_feedback_form_id": null, "secondary_assignment_demand": 0, "rules": [], "ranking": null, "expires_in": 0, "preassign_enabled": 1, "sort_order": 0, "accept_form_id": null, "reject_form_id": null, "training_ids": [ 1 ], "payment": null, "publish": 1, "promoted": 0, "is_archived": 0, "is_refund_allowed": 0, "created_by": null, "grid_image": null, "banner_image": null, "public": 0, "approval_status": "approved", "approval_reason": null, "visibility_show_groups": [], "visibility_hide_groups": [], "can_self_apply": 0, "application_form_id": null, "withdraw_form_id": null, "allows_application_withdrawals": 0, "timezone": null, "apps_open_timestamp": null, "apps_close_timestamp": null, "withdraw_close_timestamp": null, "minimum_dob": null, "minimum_age": null, "maximum_dob": null, "maximum_age": null, "applied_status_default": null, "withdrawn_status_default": null, "journey_complete_status_default": null, "deleted_at": null, "is_erased": 0, "strict_applications_enabled": 0, "waitlist_auto_invitation_enabled": 0, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:31.000000Z", "deleted_by": null, "description": "", "tags": null }, "nice": { "rrn": "rrn:local:20101:role_offer:1", "accept_form_id": null, "accept_form_id:value": null, "accept_form_id:array": null, "allows_application_withdrawals": "No", "application_form_id": null, "application_form_id:value": null, "application_form_id:array": null, "applied_status_default": null, "applied_status_default:value": null, "applied_status_default:array": null, "approval_status": "Approved", "approval_status:value": "approved", "approval_status:array": "Approved", "banner_image": "", "calculate_demand": "No", "can_self_apply": "No", "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "feedback_form_id": null, "feedback_form_id:value": null, "feedback_form_id:array": null, "grid_image": "", "headcount_functional_area_job_title_id": "Accreditation > Veterinary Technician", "headcount_functional_area_job_title_id:value": 1, "headcount_functional_area_job_title_id:array": "Accreditation > Veterinary Technician", "headcount_location_venue_id": "Melbourne > Dot Etcher", "headcount_location_venue_id:value": 10, "headcount_location_venue_id:array": "Melbourne > Dot Etcher", "is_refund_allowed": "No", "journey_complete_status_default": null, "journey_complete_status_default:value": null, "journey_complete_status_default:array": null, "journey_id": null, "journey_id:value": null, "journey_id:array": null, "minimum_age": "", "preassign_enabled": "Yes", "promoted": "No", "public": "No", "publish": "Yes", "reject_form_id": null, "reject_form_id:value": null, "reject_form_id:array": null, "tags": null, "tags:value": null, "tags:array": null, "training_ids": "Paper Goods Machine Operator_EBMsffvoa9Ht", "training_ids:value": "", "training_ids:array": [ "Paper Goods Machine Operator_EBMsffvoa9Ht" ], "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "user_type_id": "Default", "user_type_id:value": 2, "user_type_id:array": "Default", "visibility_hide_groups": "", "visibility_show_groups": "", "withdraw_form_id": null, "withdraw_form_id:value": null, "withdraw_form_id:array": null, "withdrawn_status_default": null, "withdrawn_status_default:value": null, "withdrawn_status_default:array": null, "account_id": 20101, "account_url": "https://sub.rosterfy2.localhost.com/", "confidence_level": "0%" }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "accept": false, "reject": false, "withdraw": false, "apply": false, "apply_error": "Role offer not accepting applications at this time", "apply_error_code": 1030, "update_application_form": false } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Role Offer Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "headcount_functional_area_job_title_id": { "type": "integer", "description": "The job title being recruited for. A role offer is unique on the combination of job title and venue.", "examples": [ 1 ] }, "headcount_location_venue_id": { "type": "integer", "description": "The venue the role is worked at. A role offer is unique on the combination of job title and venue.", "examples": [ 10 ] }, "user_type_id": { "type": "integer", "description": "The type of person the role is offered to, which governs how many shifts one of them can be rostered onto.", "examples": [ 2 ] }, "role_offer_template_id": { "type": "integer", "description": "A template to build the role offer from. The template's values are copied over anything sent alongside it, so most other fields are ignored when this is set. Create only.", "examples": [ 1 ] }, "description": { "type": "string", "description": "Description of the role, shown to applicants in the portal. Accepts HTML.", "examples": [ "" ] }, "static_demand": { "type": "integer", "description": "The number of people needed. Use this when demand is set directly; it is ignored when calculate_demand is 1.", "examples": [ 12 ] }, "min_demand": { "type": "integer", "description": "The minimum number of accepted people the role needs to be considered viable. Used for reporting; it does not stop applications.", "examples": [ 0 ] }, "calculate_demand": { "type": "boolean", "description": "Set to 1 to derive demand from the shift pattern instead of setting it directly, in which case user_per_shift, number_of_shifts_per_day, start_date and end_date are used and static_demand is ignored. Defaults to 0.", "examples": [ 0 ] }, "waitlist_demand": { "type": "integer", "description": "How many people may join a waitlist once the role is full. Send enable_waitlist alongside it on update, or the waitlist is switched off.", "examples": [ 0 ] }, "waitlist_auto_invitation_enabled": { "type": "boolean", "description": "Set to 1 to invite waitlisted people to apply automatically as places free up. Ignored unless waitlist_demand is set.", "examples": [ 0 ] }, "confidence_level": { "type": "integer", "description": "How far over demand the role may be filled, as a percentage between 0 and 100, to allow for people dropping out.", "examples": [ 0 ] }, "user_per_shift": { "type": "integer", "description": "How many people each shift needs. Only used when calculate_demand is 1.", "examples": [ 0 ] }, "peak_shift": { "type": "integer", "description": "The largest number of concurrent shifts to plan for. Only used when calculate_demand is 1.", "examples": [ 0 ] }, "number_of_shifts_per_day": { "type": "integer", "description": "How many shifts run per day. Only used when calculate_demand is 1.", "examples": [ 0 ] }, "start_date": { "type": "string", "description": "First day demand is calculated across, as YYYY-MM-DD. Only used when calculate_demand is 1.", "examples": [ null ] }, "end_date": { "type": "string", "description": "Last day demand is calculated across, as YYYY-MM-DD. Must not be before start_date. Only used when calculate_demand is 1.", "examples": [ null ] }, "role_feedback_form_id": { "type": "integer", "description": "A form the person is offered on their dashboard once the role is complete.", "examples": [ 1 ] }, "secondary_assignment_demand": { "type": "integer", "description": "How many people may take the role as a second assignment, which does not count towards the number of roles they hold. Cannot exceed the role's demand, and is ignored when calculate_demand is 1.", "examples": [ 0 ] }, "publish": { "type": "boolean", "description": "Set to 1 to make the role offer live. An unpublished role offer is not visible to applicants.", "examples": [ 1 ] }, "promoted": { "type": "boolean", "description": "Set to 1 to feature the role on the portal dashboard.", "examples": [ 0 ] }, "sort_order": { "type": "integer", "description": "Position of the role in listings. Lower sorts first.", "examples": [ 0 ] }, "rules": { "type": "array", "description": "Conditions that govern who may apply and what applying costs. Omitting this on update clears the role's existing rules. A rule missing a required part is dropped rather than rejected, so the role can come back with fewer rules than were sent.", "items": { "type": "object" }, "examples": [ [] ] }, "expires_in": { "type": "integer", "description": "How many days an unanswered offer stays open before it expires. Send expires_in_enable alongside it, or expiry is switched off and this resets to 0.", "examples": [ 0 ] }, "certificate_id": { "type": "integer", "description": "A certificate awarded once someone completes the role.", "examples": [ 1 ] }, "accept_form_id": { "type": "integer", "description": "A form shown when someone accepts the role.", "examples": [ 1 ] }, "reject_form_id": { "type": "integer", "description": "A form shown when someone rejects the role.", "examples": [ 1 ] }, "training_ids": { "type": "array", "description": "Training modules assigned to everyone who takes the role.", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "preassign_enabled": { "type": "boolean", "description": "Set to 1 to allow people to be pre-assigned to the role before applications open.", "examples": [ 1 ] }, "banner_image": { "type": "string", "description": "Banner shown at the top of the role's page. Either an uploaded image or the URL of one.", "examples": [ null ] }, "grid_image": { "type": "string", "description": "Thumbnail shown wherever the role appears in a grid listing. Either an uploaded image or the URL of one.", "examples": [ null ] }, "public": { "type": "boolean", "description": "Set to 1 to make the role visible without signing in, on the public listing.", "examples": [ 0 ] }, "can_self_apply": { "type": "boolean", "description": "Set to 1 to let people apply themselves rather than having the role assigned to them. Setting it to 0 clears the role's tags.", "examples": [ 0 ] }, "timezone": { "type": "string", "description": "The timezone the role's dates and times are interpreted in. Defaults to the account's timezone.", "examples": [ null ] }, "apps_open_timestamp": { "type": "string", "description": "When applications open, as YYYY-MM-DD HH:MM:SS. Nobody can apply before it.", "examples": [ null ] }, "apps_close_timestamp": { "type": "string", "description": "When applications close, as YYYY-MM-DD HH:MM:SS. Nobody can apply after it, and it must be later than apps_open_timestamp.", "examples": [ null ] }, "minimum_dob": { "type": "string", "description": "The latest date of birth allowed, as YYYY-MM-DD. Someone born after it cannot apply from the portal. Cannot be combined with minimum_age.", "examples": [ null ] }, "minimum_age": { "type": "string", "description": "The youngest age allowed, as years and months separated by a colon, for example \"18:0\". Cannot be combined with minimum_dob.", "examples": [ null ] }, "maximum_dob": { "type": "string", "description": "The earliest date of birth allowed, as YYYY-MM-DD. Someone born before it cannot apply from the portal.", "examples": [ null ] }, "maximum_age": { "type": "string", "description": "The oldest age allowed, as years and months separated by a colon, for example \"65:0\".", "examples": [ null ] }, "applied_status_default": { "type": "integer", "description": "The status given to someone when they apply for the role. Defaults to the account's applied status.", "examples": [ 1 ] }, "withdrawn_status_default": { "type": "integer", "description": "The status given to someone when they withdraw from the role. Defaults to the account's withdrawn status.", "examples": [ 1 ] }, "application_form_id": { "type": "integer", "description": "A form that must be completed before applying for the role.", "examples": [ 1 ] }, "allows_application_withdrawals": { "type": "boolean", "description": "Set to 1 to let people withdraw after applying. Switched off automatically for a role that is neither part of a journey nor self-apply.", "examples": [ 0 ] }, "withdraw_form_id": { "type": "string", "description": "A form that must be completed before withdrawing from the role.", "examples": [ null ] }, "payment": { "type": "object", "description": "What applying to the role costs, and how it is charged.", "properties": {}, "examples": [ "{}" ] }, "is_refund_allowed": { "type": "boolean", "description": "Set to 1 to permit refunds of an application fee for this role.", "examples": [ 0 ] }, "withdraw_close_timestamp": { "type": "string", "description": "After this point people can no longer withdraw, as YYYY-MM-DD HH:MM:SS.", "examples": [ null ] }, "refund_on_application_withdraw": { "type": "boolean", "description": "Set to 1 to refund the application fee automatically when someone withdraws.", "examples": [ 0 ] }, "refund_on_role_offer_complete": { "type": "boolean", "description": "Set to 1 to refund the application fee automatically once the role is complete.", "examples": [ 0 ] }, "strict_applications_enabled": { "type": "boolean", "description": "Set to 1 to stop accepting applications once demand is met.", "examples": [ 0 ] }, "reserve_demand": { "type": "integer", "description": "How many of the places are held back rather than opened to applicants. Cannot exceed static_demand.", "examples": [ 0 ] }, "custom_*": { "type": "string", "description": "A custom attribute, named by its code - custom_shirt_size, for example. The value follows the attribute's own type, so it may be a string, a number, a boolean or a list. See the custom attributes documentation.", "examples": [ null ] } }, "required": [ "headcount_functional_area_job_title_id", "headcount_location_venue_id", "user_type_id", "static_demand", "publish" ] } } } } } }, "/api/v2/headcount/roleoffer/{id}": { "get": { "summary": "Read a role offer", "operationId": "readARoleOffer", "description": "Returns one role offer's configuration, the human-readable form of each of its\nvalues, and what the calling user is permitted to do with it.\n\npermissions.apply says whether the caller can apply right now. When it is false,\npermissions.apply_error and permissions.apply_code give the reason, which is the\nvalue to surface rather than a generic message.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "headcount_functional_area_job_title_id": { "type": "integer", "examples": [ 1 ] }, "headcount_location_venue_id": { "type": "integer", "examples": [ 10 ] }, "journey_id": { "type": [ "string", "null" ], "examples": [ null ] }, "role_offer_template_id": { "type": [ "string", "null" ], "examples": [ null ] }, "user_type_id": { "type": "integer", "examples": [ 2 ] }, "certificate_id": { "type": [ "string", "null" ], "examples": [ null ] }, "static_demand": { "type": "integer", "examples": [ 12 ] }, "reserve_demand": { "type": "integer", "examples": [ 0 ] }, "waitlist_demand": { "type": "integer", "examples": [ 0 ] }, "confidence_level": { "type": "integer", "examples": [ 0 ] }, "calculate_demand": { "type": "integer", "examples": [ 0 ] }, "refund_on_application_withdraw": { "type": "integer", "examples": [ 0 ] }, "refund_on_role_offer_complete": { "type": "integer", "examples": [ 0 ] }, "user_per_shift": { "type": "integer", "examples": [ 0 ] }, "peak_shift": { "type": "integer", "examples": [ 0 ] }, "min_demand": { "type": "integer", "examples": [ 0 ] }, "number_of_shifts_per_day": { "type": "integer", "examples": [ 0 ] }, "min_number_shift_users": { "type": "integer", "examples": [ 0 ] }, "max_number_shift_users": { "type": "integer", "examples": [ 0 ] }, "start_date": { "type": [ "string", "null" ], "examples": [ null ] }, "end_date": { "type": [ "string", "null" ], "examples": [ null ] }, "role_feedback_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "secondary_assignment_demand": { "type": "integer", "examples": [ 0 ] }, "rules": { "type": "array", "examples": [ [] ] }, "ranking": { "type": [ "string", "null" ], "examples": [ null ] }, "expires_in": { "type": "integer", "examples": [ 0 ] }, "preassign_enabled": { "type": "integer", "examples": [ 1 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "accept_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "reject_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "payment": { "type": [ "string", "null" ], "examples": [ null ] }, "publish": { "type": "integer", "examples": [ 1 ] }, "promoted": { "type": "integer", "examples": [ 0 ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "is_refund_allowed": { "type": "integer", "examples": [ 0 ] }, "created_by": { "type": [ "string", "null" ], "examples": [ null ] }, "grid_image": { "type": [ "string", "null" ], "examples": [ null ] }, "banner_image": { "type": [ "string", "null" ], "examples": [ null ] }, "public": { "type": "integer", "examples": [ 0 ] }, "approval_status": { "type": "string", "examples": [ "approved" ] }, "approval_reason": { "type": [ "string", "null" ], "examples": [ null ] }, "visibility_show_groups": { "type": "array", "examples": [ [] ] }, "visibility_hide_groups": { "type": "array", "examples": [ [] ] }, "can_self_apply": { "type": "integer", "examples": [ 0 ] }, "application_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "withdraw_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "allows_application_withdrawals": { "type": "integer", "examples": [ 0 ] }, "timezone": { "type": [ "string", "null" ], "examples": [ null ] }, "apps_open_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "apps_close_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "withdraw_close_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "applied_status_default": { "type": [ "string", "null" ], "examples": [ null ] }, "withdrawn_status_default": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_complete_status_default": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "strict_applications_enabled": { "type": "integer", "examples": [ 0 ] }, "waitlist_auto_invitation_enabled": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:31.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "description": { "type": "string", "examples": [ "" ] }, "tags": { "type": [ "string", "null" ], "examples": [ null ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:role_offer:1" ] }, "accept_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "accept_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "accept_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "allows_application_withdrawals": { "type": "string", "examples": [ "No" ] }, "application_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "application_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "application_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "applied_status_default": { "type": [ "string", "null" ], "examples": [ null ] }, "applied_status_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "applied_status_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "approval_status": { "type": "string", "examples": [ "Approved" ] }, "approval_status:value": { "type": "string", "examples": [ "approved" ] }, "approval_status:array": { "type": "string", "examples": [ "Approved" ] }, "banner_image": { "type": "string", "examples": [ "" ] }, "calculate_demand": { "type": "string", "examples": [ "No" ] }, "can_self_apply": { "type": "string", "examples": [ "No" ] }, "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "feedback_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "feedback_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "feedback_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "grid_image": { "type": "string", "examples": [ "" ] }, "headcount_functional_area_job_title_id": { "type": "string", "examples": [ "Accreditation > Veterinary Technician" ] }, "headcount_functional_area_job_title_id:value": { "type": "integer", "examples": [ 1 ] }, "headcount_functional_area_job_title_id:array": { "type": "string", "examples": [ "Accreditation > Veterinary Technician" ] }, "headcount_location_venue_id": { "type": "string", "examples": [ "Melbourne > Dot Etcher" ] }, "headcount_location_venue_id:value": { "type": "integer", "examples": [ 10 ] }, "headcount_location_venue_id:array": { "type": "string", "examples": [ "Melbourne > Dot Etcher" ] }, "is_refund_allowed": { "type": "string", "examples": [ "No" ] }, "journey_complete_status_default": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_complete_status_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_complete_status_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_id": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_age": { "type": "string", "examples": [ "" ] }, "preassign_enabled": { "type": "string", "examples": [ "Yes" ] }, "promoted": { "type": "string", "examples": [ "No" ] }, "public": { "type": "string", "examples": [ "No" ] }, "publish": { "type": "string", "examples": [ "Yes" ] }, "reject_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "reject_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "reject_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "tags": { "type": [ "string", "null" ], "examples": [ null ] }, "tags:value": { "type": [ "string", "null" ], "examples": [ null ] }, "tags:array": { "type": [ "string", "null" ], "examples": [ null ] }, "training_ids": { "type": "string", "examples": [ "Paper Goods Machine Operator_EBMsffvoa9Ht" ] }, "training_ids:value": { "type": "string", "examples": [ "" ] }, "training_ids:array": { "type": "array", "items": { "type": "string" }, "examples": [ [ "Paper Goods Machine Operator_EBMsffvoa9Ht" ] ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "user_type_id": { "type": "string", "examples": [ "Default" ] }, "user_type_id:value": { "type": "integer", "examples": [ 2 ] }, "user_type_id:array": { "type": "string", "examples": [ "Default" ] }, "visibility_hide_groups": { "type": "string", "examples": [ "" ] }, "visibility_show_groups": { "type": "string", "examples": [ "" ] }, "withdraw_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "withdraw_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "withdraw_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "withdrawn_status_default": { "type": [ "string", "null" ], "examples": [ null ] }, "withdrawn_status_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "withdrawn_status_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "account_url": { "type": "string", "examples": [ "https://sub.rosterfy2.localhost.com/" ] }, "confidence_level": { "type": "string", "examples": [ "0%" ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "accept": { "type": "boolean", "examples": [ false ] }, "reject": { "type": "boolean", "examples": [ false ] }, "withdraw": { "type": "boolean", "examples": [ false ] }, "apply": { "type": "boolean", "examples": [ false ] }, "apply_error": { "type": "string", "examples": [ "Role offer not accepting applications at this time" ] }, "apply_error_code": { "type": "integer", "examples": [ 1030 ] }, "update_application_form": { "type": "boolean", "examples": [ false ] } } } }, "examples": [ { "object": { "id": 1, "headcount_functional_area_job_title_id": 1, "headcount_location_venue_id": 10, "journey_id": null, "role_offer_template_id": null, "user_type_id": 2, "certificate_id": null, "static_demand": 12, "reserve_demand": 0, "waitlist_demand": 0, "confidence_level": 0, "calculate_demand": 0, "refund_on_application_withdraw": 0, "refund_on_role_offer_complete": 0, "user_per_shift": 0, "peak_shift": 0, "min_demand": 0, "number_of_shifts_per_day": 0, "min_number_shift_users": 0, "max_number_shift_users": 0, "start_date": null, "end_date": null, "role_feedback_form_id": null, "secondary_assignment_demand": 0, "rules": [], "ranking": null, "expires_in": 0, "preassign_enabled": 1, "sort_order": 0, "accept_form_id": null, "reject_form_id": null, "training_ids": [ 1 ], "payment": null, "publish": 1, "promoted": 0, "is_archived": 0, "is_refund_allowed": 0, "created_by": null, "grid_image": null, "banner_image": null, "public": 0, "approval_status": "approved", "approval_reason": null, "visibility_show_groups": [], "visibility_hide_groups": [], "can_self_apply": 0, "application_form_id": null, "withdraw_form_id": null, "allows_application_withdrawals": 0, "timezone": null, "apps_open_timestamp": null, "apps_close_timestamp": null, "withdraw_close_timestamp": null, "minimum_dob": null, "minimum_age": null, "maximum_dob": null, "maximum_age": null, "applied_status_default": null, "withdrawn_status_default": null, "journey_complete_status_default": null, "deleted_at": null, "is_erased": 0, "strict_applications_enabled": 0, "waitlist_auto_invitation_enabled": 0, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:31.000000Z", "deleted_by": null, "description": "", "tags": null }, "nice": { "rrn": "rrn:local:20101:role_offer:1", "accept_form_id": null, "accept_form_id:value": null, "accept_form_id:array": null, "allows_application_withdrawals": "No", "application_form_id": null, "application_form_id:value": null, "application_form_id:array": null, "applied_status_default": null, "applied_status_default:value": null, "applied_status_default:array": null, "approval_status": "Approved", "approval_status:value": "approved", "approval_status:array": "Approved", "banner_image": "", "calculate_demand": "No", "can_self_apply": "No", "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "feedback_form_id": null, "feedback_form_id:value": null, "feedback_form_id:array": null, "grid_image": "", "headcount_functional_area_job_title_id": "Accreditation > Veterinary Technician", "headcount_functional_area_job_title_id:value": 1, "headcount_functional_area_job_title_id:array": "Accreditation > Veterinary Technician", "headcount_location_venue_id": "Melbourne > Dot Etcher", "headcount_location_venue_id:value": 10, "headcount_location_venue_id:array": "Melbourne > Dot Etcher", "is_refund_allowed": "No", "journey_complete_status_default": null, "journey_complete_status_default:value": null, "journey_complete_status_default:array": null, "journey_id": null, "journey_id:value": null, "journey_id:array": null, "minimum_age": "", "preassign_enabled": "Yes", "promoted": "No", "public": "No", "publish": "Yes", "reject_form_id": null, "reject_form_id:value": null, "reject_form_id:array": null, "tags": null, "tags:value": null, "tags:array": null, "training_ids": "Paper Goods Machine Operator_EBMsffvoa9Ht", "training_ids:value": "", "training_ids:array": [ "Paper Goods Machine Operator_EBMsffvoa9Ht" ], "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "user_type_id": "Default", "user_type_id:value": 2, "user_type_id:array": "Default", "visibility_hide_groups": "", "visibility_show_groups": "", "withdraw_form_id": null, "withdraw_form_id:value": null, "withdraw_form_id:array": null, "withdrawn_status_default": null, "withdrawn_status_default:value": null, "withdrawn_status_default:array": null, "account_id": 20101, "account_url": "https://sub.rosterfy2.localhost.com/", "confidence_level": "0%" }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "accept": false, "reject": false, "withdraw": false, "apply": false, "apply_error": "Role offer not accepting applications at this time", "apply_error_code": 1030, "update_application_form": false } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Role Offer Module" ] }, "put": { "summary": "Update a role offer", "operationId": "updateARoleOffer", "description": "Updates a role offer and returns it in the same shape as reading one. Every field\nis optional; only the fields sent are changed, with the exceptions below.\n\nThe account's own attribute configuration takes precedence over the fields listed\nbelow, exactly as it does on create.\n\nFour fields are reset rather than left alone when their enabling field is absent\nfrom the request. Send expires_in_enable alongside expires_in to keep it,\nenable_waitlist alongside waitlist_demand and waitlist_auto_invitation_enabled,\nand has_age_limit alongside minimum_dob and minimum_age. Omitting the enabling\nfield clears the value it guards. Omitting rules clears the role offer's rules.\n\nWhere the role offer was created from a template, values the template locks are\ndropped from the request and the update still returns a 200. A locked field can\nonly be changed by sending {field}:override=1 next to it, and only by a caller\nallowed to override template-locked fields. The journey a role offer belongs to\ncan never be changed after creation.\n\nInvalid input returns a 422 identifying the fields at fault. Reducing demand below\nwhat is already filled, exceeding the account's confidence level, or removing a\npayment requirement that applications depend on are all reported this way.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "headcount_functional_area_job_title_id": { "type": "integer", "examples": [ 1 ] }, "headcount_location_venue_id": { "type": "integer", "examples": [ 10 ] }, "journey_id": { "type": [ "string", "null" ], "examples": [ null ] }, "role_offer_template_id": { "type": [ "string", "null" ], "examples": [ null ] }, "user_type_id": { "type": "integer", "examples": [ 2 ] }, "certificate_id": { "type": [ "string", "null" ], "examples": [ null ] }, "static_demand": { "type": "integer", "examples": [ 12 ] }, "reserve_demand": { "type": "integer", "examples": [ 0 ] }, "waitlist_demand": { "type": "integer", "examples": [ 0 ] }, "confidence_level": { "type": "integer", "examples": [ 0 ] }, "calculate_demand": { "type": "integer", "examples": [ 0 ] }, "refund_on_application_withdraw": { "type": "integer", "examples": [ 0 ] }, "refund_on_role_offer_complete": { "type": "integer", "examples": [ 0 ] }, "user_per_shift": { "type": "integer", "examples": [ 0 ] }, "peak_shift": { "type": "integer", "examples": [ 0 ] }, "min_demand": { "type": "integer", "examples": [ 0 ] }, "number_of_shifts_per_day": { "type": "integer", "examples": [ 0 ] }, "min_number_shift_users": { "type": "integer", "examples": [ 0 ] }, "max_number_shift_users": { "type": "integer", "examples": [ 0 ] }, "start_date": { "type": [ "string", "null" ], "examples": [ null ] }, "end_date": { "type": [ "string", "null" ], "examples": [ null ] }, "role_feedback_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "secondary_assignment_demand": { "type": "integer", "examples": [ 0 ] }, "rules": { "type": "array", "examples": [ [] ] }, "ranking": { "type": [ "string", "null" ], "examples": [ null ] }, "expires_in": { "type": "integer", "examples": [ 0 ] }, "preassign_enabled": { "type": "integer", "examples": [ 1 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "accept_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "reject_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "training_ids": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "payment": { "type": [ "string", "null" ], "examples": [ null ] }, "publish": { "type": "integer", "examples": [ 1 ] }, "promoted": { "type": "integer", "examples": [ 0 ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "is_refund_allowed": { "type": "integer", "examples": [ 0 ] }, "created_by": { "type": [ "string", "null" ], "examples": [ null ] }, "grid_image": { "type": [ "string", "null" ], "examples": [ null ] }, "banner_image": { "type": [ "string", "null" ], "examples": [ null ] }, "public": { "type": "integer", "examples": [ 0 ] }, "approval_status": { "type": "string", "examples": [ "approved" ] }, "approval_reason": { "type": [ "string", "null" ], "examples": [ null ] }, "visibility_show_groups": { "type": "array", "examples": [ [] ] }, "visibility_hide_groups": { "type": "array", "examples": [ [] ] }, "can_self_apply": { "type": "integer", "examples": [ 0 ] }, "application_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "withdraw_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "allows_application_withdrawals": { "type": "integer", "examples": [ 0 ] }, "timezone": { "type": [ "string", "null" ], "examples": [ null ] }, "apps_open_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "apps_close_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "withdraw_close_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "applied_status_default": { "type": [ "string", "null" ], "examples": [ null ] }, "withdrawn_status_default": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_complete_status_default": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "strict_applications_enabled": { "type": "integer", "examples": [ 0 ] }, "waitlist_auto_invitation_enabled": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:16.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:31.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "description": { "type": "string", "examples": [ "" ] }, "tags": { "type": [ "string", "null" ], "examples": [ null ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:role_offer:1" ] }, "accept_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "accept_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "accept_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "allows_application_withdrawals": { "type": "string", "examples": [ "No" ] }, "application_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "application_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "application_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "applied_status_default": { "type": [ "string", "null" ], "examples": [ null ] }, "applied_status_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "applied_status_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "approval_status": { "type": "string", "examples": [ "Approved" ] }, "approval_status:value": { "type": "string", "examples": [ "approved" ] }, "approval_status:array": { "type": "string", "examples": [ "Approved" ] }, "banner_image": { "type": "string", "examples": [ "" ] }, "calculate_demand": { "type": "string", "examples": [ "No" ] }, "can_self_apply": { "type": "string", "examples": [ "No" ] }, "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "feedback_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "feedback_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "feedback_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "grid_image": { "type": "string", "examples": [ "" ] }, "headcount_functional_area_job_title_id": { "type": "string", "examples": [ "Accreditation > Veterinary Technician" ] }, "headcount_functional_area_job_title_id:value": { "type": "integer", "examples": [ 1 ] }, "headcount_functional_area_job_title_id:array": { "type": "string", "examples": [ "Accreditation > Veterinary Technician" ] }, "headcount_location_venue_id": { "type": "string", "examples": [ "Melbourne > Dot Etcher" ] }, "headcount_location_venue_id:value": { "type": "integer", "examples": [ 10 ] }, "headcount_location_venue_id:array": { "type": "string", "examples": [ "Melbourne > Dot Etcher" ] }, "is_refund_allowed": { "type": "string", "examples": [ "No" ] }, "journey_complete_status_default": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_complete_status_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_complete_status_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_id": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_age": { "type": "string", "examples": [ "" ] }, "preassign_enabled": { "type": "string", "examples": [ "Yes" ] }, "promoted": { "type": "string", "examples": [ "No" ] }, "public": { "type": "string", "examples": [ "No" ] }, "publish": { "type": "string", "examples": [ "Yes" ] }, "reject_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "reject_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "reject_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "tags": { "type": [ "string", "null" ], "examples": [ null ] }, "tags:value": { "type": [ "string", "null" ], "examples": [ null ] }, "tags:array": { "type": [ "string", "null" ], "examples": [ null ] }, "training_ids": { "type": "string", "examples": [ "Paper Goods Machine Operator_EBMsffvoa9Ht" ] }, "training_ids:value": { "type": "string", "examples": [ "" ] }, "training_ids:array": { "type": "array", "items": { "type": "string" }, "examples": [ [ "Paper Goods Machine Operator_EBMsffvoa9Ht" ] ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "user_type_id": { "type": "string", "examples": [ "Default" ] }, "user_type_id:value": { "type": "integer", "examples": [ 2 ] }, "user_type_id:array": { "type": "string", "examples": [ "Default" ] }, "visibility_hide_groups": { "type": "string", "examples": [ "" ] }, "visibility_show_groups": { "type": "string", "examples": [ "" ] }, "withdraw_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "withdraw_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "withdraw_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "withdrawn_status_default": { "type": [ "string", "null" ], "examples": [ null ] }, "withdrawn_status_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "withdrawn_status_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "account_url": { "type": "string", "examples": [ "https://sub.rosterfy2.localhost.com/" ] }, "confidence_level": { "type": "string", "examples": [ "0%" ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "accept": { "type": "boolean", "examples": [ false ] }, "reject": { "type": "boolean", "examples": [ false ] }, "withdraw": { "type": "boolean", "examples": [ false ] }, "apply": { "type": "boolean", "examples": [ false ] }, "apply_error": { "type": "string", "examples": [ "Role offer not accepting applications at this time" ] }, "apply_error_code": { "type": "integer", "examples": [ 1030 ] }, "update_application_form": { "type": "boolean", "examples": [ false ] } } } }, "examples": [ { "object": { "id": 1, "headcount_functional_area_job_title_id": 1, "headcount_location_venue_id": 10, "journey_id": null, "role_offer_template_id": null, "user_type_id": 2, "certificate_id": null, "static_demand": 12, "reserve_demand": 0, "waitlist_demand": 0, "confidence_level": 0, "calculate_demand": 0, "refund_on_application_withdraw": 0, "refund_on_role_offer_complete": 0, "user_per_shift": 0, "peak_shift": 0, "min_demand": 0, "number_of_shifts_per_day": 0, "min_number_shift_users": 0, "max_number_shift_users": 0, "start_date": null, "end_date": null, "role_feedback_form_id": null, "secondary_assignment_demand": 0, "rules": [], "ranking": null, "expires_in": 0, "preassign_enabled": 1, "sort_order": 0, "accept_form_id": null, "reject_form_id": null, "training_ids": [ 1 ], "payment": null, "publish": 1, "promoted": 0, "is_archived": 0, "is_refund_allowed": 0, "created_by": null, "grid_image": null, "banner_image": null, "public": 0, "approval_status": "approved", "approval_reason": null, "visibility_show_groups": [], "visibility_hide_groups": [], "can_self_apply": 0, "application_form_id": null, "withdraw_form_id": null, "allows_application_withdrawals": 0, "timezone": null, "apps_open_timestamp": null, "apps_close_timestamp": null, "withdraw_close_timestamp": null, "minimum_dob": null, "minimum_age": null, "maximum_dob": null, "maximum_age": null, "applied_status_default": null, "withdrawn_status_default": null, "journey_complete_status_default": null, "deleted_at": null, "is_erased": 0, "strict_applications_enabled": 0, "waitlist_auto_invitation_enabled": 0, "created_at": "2026-06-09T05:36:16.000000Z", "updated_at": "2026-06-09T05:36:31.000000Z", "deleted_by": null, "description": "", "tags": null }, "nice": { "rrn": "rrn:local:20101:role_offer:1", "accept_form_id": null, "accept_form_id:value": null, "accept_form_id:array": null, "allows_application_withdrawals": "No", "application_form_id": null, "application_form_id:value": null, "application_form_id:array": null, "applied_status_default": null, "applied_status_default:value": null, "applied_status_default:array": null, "approval_status": "Approved", "approval_status:value": "approved", "approval_status:array": "Approved", "banner_image": "", "calculate_demand": "No", "can_self_apply": "No", "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "feedback_form_id": null, "feedback_form_id:value": null, "feedback_form_id:array": null, "grid_image": "", "headcount_functional_area_job_title_id": "Accreditation > Veterinary Technician", "headcount_functional_area_job_title_id:value": 1, "headcount_functional_area_job_title_id:array": "Accreditation > Veterinary Technician", "headcount_location_venue_id": "Melbourne > Dot Etcher", "headcount_location_venue_id:value": 10, "headcount_location_venue_id:array": "Melbourne > Dot Etcher", "is_refund_allowed": "No", "journey_complete_status_default": null, "journey_complete_status_default:value": null, "journey_complete_status_default:array": null, "journey_id": null, "journey_id:value": null, "journey_id:array": null, "minimum_age": "", "preassign_enabled": "Yes", "promoted": "No", "public": "No", "publish": "Yes", "reject_form_id": null, "reject_form_id:value": null, "reject_form_id:array": null, "tags": null, "tags:value": null, "tags:array": null, "training_ids": "Paper Goods Machine Operator_EBMsffvoa9Ht", "training_ids:value": "", "training_ids:array": [ "Paper Goods Machine Operator_EBMsffvoa9Ht" ], "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "user_type_id": "Default", "user_type_id:value": 2, "user_type_id:array": "Default", "visibility_hide_groups": "", "visibility_show_groups": "", "withdraw_form_id": null, "withdraw_form_id:value": null, "withdraw_form_id:array": null, "withdrawn_status_default": null, "withdrawn_status_default:value": null, "withdrawn_status_default:array": null, "account_id": 20101, "account_url": "https://sub.rosterfy2.localhost.com/", "confidence_level": "0%" }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "accept": false, "reject": false, "withdraw": false, "apply": false, "apply_error": "Role offer not accepting applications at this time", "apply_error_code": 1030, "update_application_form": false } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Role Offer Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "headcount_functional_area_job_title_id": { "type": "integer", "description": "The job title being recruited for. A role offer is unique on the combination of job title and venue.", "examples": [ 1 ] }, "headcount_location_venue_id": { "type": "integer", "description": "The venue the role is worked at. A role offer is unique on the combination of job title and venue.", "examples": [ 10 ] }, "user_type_id": { "type": "integer", "description": "The type of person the role is offered to, which governs how many shifts one of them can be rostered onto.", "examples": [ 2 ] }, "static_demand": { "type": "integer", "description": "The number of people needed. Use this when demand is set directly; it is ignored when calculate_demand is 1.", "examples": [ 12 ] }, "min_demand": { "type": "integer", "description": "The minimum number of accepted people the role needs to be considered viable. Used for reporting; it does not stop applications.", "examples": [ 0 ] }, "calculate_demand": { "type": "boolean", "description": "Set to 1 to derive demand from the shift pattern instead of setting it directly, in which case user_per_shift, number_of_shifts_per_day, start_date and end_date are used and static_demand is ignored. Defaults to 0.", "examples": [ 0 ] }, "waitlist_demand": { "type": "integer", "description": "How many people may join a waitlist once the role is full. Send enable_waitlist alongside it on update, or the waitlist is switched off.", "examples": [ 0 ] }, "waitlist_auto_invitation_enabled": { "type": "boolean", "description": "Set to 1 to invite waitlisted people to apply automatically as places free up. Ignored unless waitlist_demand is set.", "examples": [ 0 ] }, "user_per_shift": { "type": "integer", "description": "How many people each shift needs. Only used when calculate_demand is 1.", "examples": [ 0 ] }, "peak_shift": { "type": "integer", "description": "The largest number of concurrent shifts to plan for. Only used when calculate_demand is 1.", "examples": [ 0 ] }, "number_of_shifts_per_day": { "type": "integer", "description": "How many shifts run per day. Only used when calculate_demand is 1.", "examples": [ 0 ] }, "start_date": { "type": "string", "description": "First day demand is calculated across, as YYYY-MM-DD. Only used when calculate_demand is 1.", "examples": [ null ] }, "end_date": { "type": "string", "description": "Last day demand is calculated across, as YYYY-MM-DD. Must not be before start_date. Only used when calculate_demand is 1.", "examples": [ null ] }, "role_feedback_form_id": { "type": "integer", "description": "A form the person is offered on their dashboard once the role is complete.", "examples": [ 1 ] }, "publish": { "type": "boolean", "description": "Set to 1 to make the role offer live. An unpublished role offer is not visible to applicants.", "examples": [ 1 ] }, "promoted": { "type": "boolean", "description": "Set to 1 to feature the role on the portal dashboard.", "examples": [ 0 ] }, "secondary_assignment_demand": { "type": "integer", "description": "How many people may take the role as a second assignment, which does not count towards the number of roles they hold. Cannot exceed the role's demand, and is ignored when calculate_demand is 1.", "examples": [ 0 ] }, "confidence_level": { "type": "integer", "description": "How far over demand the role may be filled, as a percentage between 0 and 100, to allow for people dropping out.", "examples": [ 0 ] }, "rules": { "type": "array", "description": "Conditions that govern who may apply and what applying costs. Omitting this on update clears the role's existing rules. A rule missing a required part is dropped rather than rejected, so the role can come back with fewer rules than were sent.", "items": { "type": "object" }, "examples": [ [] ] }, "ranking": { "type": "array", "description": "Ranking bands used to order applicants. Update only.", "items": { "type": "object" }, "examples": [ [] ] }, "sort_order": { "type": "integer", "description": "Position of the role in listings. Lower sorts first.", "examples": [ 0 ] }, "expires_in": { "type": "integer", "description": "How many days an unanswered offer stays open before it expires. Send expires_in_enable alongside it, or expiry is switched off and this resets to 0.", "examples": [ 0 ] }, "certificate_id": { "type": "integer", "description": "A certificate awarded once someone completes the role.", "examples": [ 1 ] }, "accept_form_id": { "type": "integer", "description": "A form shown when someone accepts the role.", "examples": [ 1 ] }, "reject_form_id": { "type": "integer", "description": "A form shown when someone rejects the role.", "examples": [ 1 ] }, "training_ids": { "type": "array", "description": "Training modules assigned to everyone who takes the role.", "items": { "type": "integer" }, "examples": [ [ 1 ] ] }, "is_archived": { "type": "string", "description": "Set to 1 to archive the role offer, hiding it from the default listing without deleting it. Update only.", "examples": [ 0 ] }, "preassign_enabled": { "type": "boolean", "description": "Set to 1 to allow people to be pre-assigned to the role before applications open.", "examples": [ 1 ] }, "banner_image": { "type": "string", "description": "Banner shown at the top of the role's page. Either an uploaded image or the URL of one.", "examples": [ null ] }, "grid_image": { "type": "string", "description": "Thumbnail shown wherever the role appears in a grid listing. Either an uploaded image or the URL of one.", "examples": [ null ] }, "public": { "type": "boolean", "description": "Set to 1 to make the role visible without signing in, on the public listing.", "examples": [ 0 ] }, "can_self_apply": { "type": "boolean", "description": "Set to 1 to let people apply themselves rather than having the role assigned to them. Setting it to 0 clears the role's tags.", "examples": [ 0 ] }, "timezone": { "type": "string", "description": "The timezone the role's dates and times are interpreted in. Defaults to the account's timezone.", "examples": [ null ] }, "apps_open_timestamp": { "type": "string", "description": "When applications open, as YYYY-MM-DD HH:MM:SS. Nobody can apply before it.", "examples": [ null ] }, "apps_close_timestamp": { "type": "string", "description": "When applications close, as YYYY-MM-DD HH:MM:SS. Nobody can apply after it, and it must be later than apps_open_timestamp.", "examples": [ null ] }, "minimum_dob": { "type": "string", "description": "The latest date of birth allowed, as YYYY-MM-DD. Someone born after it cannot apply from the portal. Cannot be combined with minimum_age.", "examples": [ null ] }, "minimum_age": { "type": "string", "description": "The youngest age allowed, as years and months separated by a colon, for example \"18:0\". Cannot be combined with minimum_dob.", "examples": [ null ] }, "maximum_dob": { "type": "string", "description": "The earliest date of birth allowed, as YYYY-MM-DD. Someone born before it cannot apply from the portal.", "examples": [ null ] }, "maximum_age": { "type": "string", "description": "The oldest age allowed, as years and months separated by a colon, for example \"65:0\".", "examples": [ null ] }, "applied_status_default": { "type": "integer", "description": "The status given to someone when they apply for the role. Defaults to the account's applied status.", "examples": [ 1 ] }, "withdrawn_status_default": { "type": "integer", "description": "The status given to someone when they withdraw from the role. Defaults to the account's withdrawn status.", "examples": [ 1 ] }, "application_form_id": { "type": "integer", "description": "A form that must be completed before applying for the role.", "examples": [ 1 ] }, "approval_status": { "type": "string", "description": "Where the role offer sits in the approval process. On an account that requires approval, a caller who cannot approve may only submit it for approval. Update only.", "examples": [ "approved" ] }, "approval_reason": { "type": "string", "description": "Note recorded against the current approval decision. Update only.", "examples": [ null ] }, "allows_application_withdrawals": { "type": "boolean", "description": "Set to 1 to let people withdraw after applying. Switched off automatically for a role that is neither part of a journey nor self-apply.", "examples": [ 0 ] }, "withdraw_form_id": { "type": "string", "description": "A form that must be completed before withdrawing from the role.", "examples": [ null ] }, "payment": { "type": "object", "description": "What applying to the role costs, and how it is charged.", "properties": {}, "examples": [ "{}" ] }, "is_refund_allowed": { "type": "boolean", "description": "Set to 1 to permit refunds of an application fee for this role.", "examples": [ 0 ] }, "withdraw_close_timestamp": { "type": "string", "description": "After this point people can no longer withdraw, as YYYY-MM-DD HH:MM:SS.", "examples": [ null ] }, "refund_on_application_withdraw": { "type": "boolean", "description": "Set to 1 to refund the application fee automatically when someone withdraws.", "examples": [ 0 ] }, "refund_on_role_offer_complete": { "type": "boolean", "description": "Set to 1 to refund the application fee automatically once the role is complete.", "examples": [ 0 ] }, "strict_applications_enabled": { "type": "boolean", "description": "Set to 1 to stop accepting applications once demand is met.", "examples": [ 0 ] }, "reserve_demand": { "type": "integer", "description": "How many of the places are held back rather than opened to applicants. Cannot exceed static_demand.", "examples": [ 0 ] }, "custom_*": { "type": "string", "description": "A custom attribute, named by its code - custom_shirt_size, for example. The value follows the attribute's own type, so it may be a string, a number, a boolean or a list. See the custom attributes documentation.", "examples": [ null ] } } } } } } }, "delete": { "summary": "Delete a role offer", "operationId": "deleteARoleOffer", "description": "Deletes a role offer. Unlike most deletes this returns 200 with a messages body\nrather than an empty 204; messages is null when there was nothing to report.\n\nDeleting a role offer that people are still assigned to has to be acknowledged\nfirst. The initial attempt is refused with a warning saying how many are affected,\nand the response names the key to acknowledge; send that key back in override to\ngo ahead. Not every caller is permitted to, in which case the delete stays refused.", "parameters": [ { "in": "query", "name": "override", "description": "Warning keys to acknowledge.", "required": false, "schema": { "type": "array", "description": "Warning keys to acknowledge.", "items": { "type": "string" }, "examples": [ [ "headcount.roleoffer.delete.demand" ] ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": [ "string", "null" ], "examples": [ null ] } }, "examples": [ { "messages": null } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Role Offer Module" ] }, "parameters": [ { "in": "path", "name": "id", "description": "The ID of the role offer.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/headcount/roleoffer/{roleoffer_id}/user": { "get": { "summary": "List a role offer's applications", "operationId": "listARoleOffersApplications", "description": "Returns the people who have applied to, or been added to, the role offer in\nthe URL - one row per application, carrying the status each is at.\n\nApplications whose user has since been deleted are **included**, unlike most\nlistings in the API, so the count here matches what the role offer's demand is\nmeasured against.\n\nThe response is only wrapped in a paginated envelope when a `page` parameter is\nsent. Without one, every match comes back as a flat array. Note that the\nenvelope carries no `total` and no `last_page` - page until `next_page_url` is\nnull rather than counting pages up front.\n\nRelated records are not included unless asked for. Requesting the `user`\nrelation returns that person's full profile, so ask for it only when the\nprofile is what you need - the application already carries `user_id`.", "parameters": [ { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "query", "name": "extras", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "required": false, "schema": { "type": "array", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "items": { "type": "string", "enum": [ "stats", "waitlist_duration" ] }, "examples": [ [ "stats" ] ] } }, { "in": "query", "name": "with", "description": "A list of relations to include in the response. May be single records or collections.\nIt is often more efficient to retrieve this way, to avoid follow-up API calls.", "required": false, "schema": { "type": "array", "description": "A list of relations to include in the response. May be single records or collections.\nIt is often more efficient to retrieve this way, to avoid follow-up API calls.", "items": { "type": "string", "enum": [ "status_log", "hasManyDeepFromRelationsWithConstraints", "hasOneDeepFromRelationsWithConstraints", "hasManyDeepFromReverse", "hasOneDeepFromReverse" ] }, "examples": [ [ "status_log" ] ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "role_offer_id": { "type": "integer", "examples": [ 1 ] }, "user_id": { "type": "integer", "examples": [ 1234 ] }, "status_id": { "type": "integer", "examples": [ 13 ] }, "ranking": { "type": "integer", "examples": [ 0 ] }, "role_offer_feedback_form_completed_at": { "type": [ "string", "null" ], "examples": [ null ] }, "secondary_assignment": { "type": "integer", "examples": [ 0 ] }, "expires_at": { "type": [ "string", "null" ], "examples": [ null ] }, "feedback": { "type": [ "string", "null" ], "examples": [ null ] }, "status_update_at": { "type": "string", "examples": [ "2026-05-30 14:28:24" ] }, "application_form_completed_at": { "type": "string", "examples": [ "2026-05-30 14:28:24" ] }, "application_withdrawn_at": { "type": [ "string", "null" ], "examples": [ null ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "waitlist_invitation_email_sent_at": { "type": [ "string", "null" ], "examples": [ null ] }, "waitlist_reminder_email_sent_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_reserved": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-05-30T14:28:24.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-05-30T14:28:24.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:role_offer_user:1" ] }, "journey_step": { "type": "string", "examples": [ "Application review" ] }, "journey_step_category": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "May 30, 2026, 2:28 PM" ] }, "created_at__date": { "type": "string", "examples": [ "May 30, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "2:28 PM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Saturday" ] }, "feedback": { "type": "string", "examples": [ "" ] }, "status_id": { "type": "string", "examples": [ "Applied" ] }, "status_id:value": { "type": "integer", "examples": [ 13 ] }, "status_id:array": { "type": "string", "examples": [ "Applied" ] }, "status_update_at": { "type": "string", "examples": [ "May 30, 2026, 2:28 PM" ] }, "status_update_at__date": { "type": "string", "examples": [ "May 30, 2026" ] }, "status_update_at__time": { "type": "string", "examples": [ "2:28 PM" ] }, "status_update_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "status_update_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "status_update_at__dayofweek": { "type": "string", "examples": [ "Saturday" ] }, "updated_at": { "type": "string", "examples": [ "May 30, 2026, 2:28 PM" ] }, "updated_at__date": { "type": "string", "examples": [ "May 30, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "2:28 PM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Saturday" ] }, "status": { "type": "string", "examples": [ "Applied" ] }, "status_is_public": { "type": "boolean", "examples": [ true ] }, "status_type": { "type": "string", "examples": [ "applied" ] }, "user_name": { "type": "string", "examples": [ "Example Applicant" ] }, "has_received_invitation": { "type": "boolean", "examples": [ false ] }, "status_color": { "type": "string", "examples": [ "#6c757d" ] }, "status_lightness": { "type": "integer", "examples": [ 0 ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "status_update": { "type": "boolean", "examples": [ false ] }, "downloadCertificate": { "type": "boolean", "examples": [ false ] } } } } }, "examples": [ [ { "object": { "id": 1, "role_offer_id": 1, "user_id": 1234, "status_id": 13, "ranking": 0, "role_offer_feedback_form_completed_at": null, "secondary_assignment": 0, "expires_at": null, "feedback": null, "status_update_at": "2026-05-30 14:28:24", "application_form_completed_at": "2026-05-30 14:28:24", "application_withdrawn_at": null, "sort_order": 0, "waitlist_invitation_email_sent_at": null, "waitlist_reminder_email_sent_at": null, "is_reserved": 0, "deleted_at": null, "is_erased": 0, "created_at": "2026-05-30T14:28:24.000000Z", "updated_at": "2026-05-30T14:28:24.000000Z", "deleted_by": null }, "nice": { "rrn": "rrn:local:20101:role_offer_user:1", "journey_step": "Application review", "journey_step_category": null, "created_at": "May 30, 2026, 2:28 PM", "created_at__date": "May 30, 2026", "created_at__time": "2:28 PM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Saturday", "feedback": "", "status_id": "Applied", "status_id:value": 13, "status_id:array": "Applied", "status_update_at": "May 30, 2026, 2:28 PM", "status_update_at__date": "May 30, 2026", "status_update_at__time": "2:28 PM", "status_update_at__offset": " (+00:00 UTC)", "status_update_at__offset_minutes": 0, "status_update_at__dayofweek": "Saturday", "updated_at": "May 30, 2026, 2:28 PM", "updated_at__date": "May 30, 2026", "updated_at__time": "2:28 PM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Saturday", "status": "Applied", "status_is_public": true, "status_type": "applied", "user_name": "Example Applicant", "has_received_invitation": false, "status_color": "#6c757d", "status_lightness": 0 }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "status_update": false, "downloadCertificate": false } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/headcount/roleoffer/{roleoffer}/user?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/headcount/roleoffer/{roleoffer}/user?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/headcount/roleoffer/{roleoffer}/user" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 1, "role_offer_id": 1, "user_id": 1234, "status_id": 13, "ranking": 0, "role_offer_feedback_form_completed_at": null, "secondary_assignment": 0, "expires_at": null, "feedback": null, "status_update_at": "2026-05-30 14:28:24", "application_form_completed_at": "2026-05-30 14:28:24", "application_withdrawn_at": null, "sort_order": 0, "waitlist_invitation_email_sent_at": null, "waitlist_reminder_email_sent_at": null, "is_reserved": 0, "deleted_at": null, "is_erased": 0, "created_at": "2026-05-30T14:28:24.000000Z", "updated_at": "2026-05-30T14:28:24.000000Z", "deleted_by": null }, "nice": { "rrn": "rrn:local:20101:role_offer_user:1", "journey_step": "Application review", "journey_step_category": null, "created_at": "May 30, 2026, 2:28 PM", "created_at__date": "May 30, 2026", "created_at__time": "2:28 PM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Saturday", "feedback": "", "status_id": "Applied", "status_id:value": 13, "status_id:array": "Applied", "status_update_at": "May 30, 2026, 2:28 PM", "status_update_at__date": "May 30, 2026", "status_update_at__time": "2:28 PM", "status_update_at__offset": " (+00:00 UTC)", "status_update_at__offset_minutes": 0, "status_update_at__dayofweek": "Saturday", "updated_at": "May 30, 2026, 2:28 PM", "updated_at__date": "May 30, 2026", "updated_at__time": "2:28 PM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Saturday", "status": "Applied", "status_is_public": true, "status_type": "applied", "user_name": "Example Applicant", "has_received_invitation": false, "status_color": "#6c757d", "status_lightness": 0 }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "status_update": false, "downloadCertificate": false } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/headcount/roleoffer/{roleoffer}/user?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/headcount/roleoffer/{roleoffer}/user?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/headcount/roleoffer/{roleoffer}/user", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Role Offer Module" ] }, "post": { "summary": "Add a user to a role offer", "operationId": "addAUserToARoleOffer", "description": "Creates an application for one person against the role offer in the URL, at the\nstatus you name, and returns it.\n\nThe created record carries only the fields the create set - the rest of an\napplication's fields are filled in as it progresses - so read it back if you\nneed the full shape.\n\nA person can hold only one live application per role offer. A second one comes\nback as a **422** naming `user_id`; delete the existing application first if you\nmean to start over.\n\n**Three business rules can refuse an otherwise valid create, each with a `403`\nand a message saying which:**\n\n- the role offer has no places left at that status, either on its main demand,\n its waitlist, its reserve list or its secondary allowance;\n- the person already holds as many roles as the account permits;\n- the account does not allow an application to start at that status.\n\n**A fourth returns a `405`**, because it is a limit an authorised caller may\nchoose to pass: adding this person would take the role offer past its confidence\nlevel. The body carries a `reference`, and a caller holding the matching\npermission can repeat the request with that key in an `override` **query\nparameter** - `?override[]=headcount.roleoffer.confidence_level` - to go ahead.\nSending `override` in the JSON body does not work.\n\nBeyond the fields listed here the endpoint also accepts the account's own\nconfigured attributes for an application. Invalid input returns a 422 naming the\nfields at fault.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 2 ] }, "role_offer_id": { "type": "integer", "examples": [ 1 ] }, "user_id": { "type": "integer", "examples": [ 1235 ] }, "status_id": { "type": "integer", "examples": [ 2 ] }, "status_update_at": { "type": "string", "examples": [ "2026-05-30T14:28:24.000000Z" ] }, "created_at": { "type": "string", "examples": [ "2026-05-30T14:28:24.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-05-30T14:28:24.000000Z" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:role_offer_user:2" ] }, "journey_step": { "type": "string", "examples": [ "" ] }, "journey_step_category": { "type": "string", "examples": [ "" ] }, "created_at": { "type": "string", "examples": [ "May 30, 2026, 2:28 PM" ] }, "created_at__date": { "type": "string", "examples": [ "May 30, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "2:28 PM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Saturday" ] }, "feedback": { "type": "string", "examples": [ "" ] }, "status_id": { "type": "string", "examples": [ "Pending" ] }, "status_id:value": { "type": "integer", "examples": [ 2 ] }, "status_id:array": { "type": "string", "examples": [ "Pending" ] }, "status_update_at": { "type": "string", "examples": [ "May 30, 2026, 2:28 PM" ] }, "status_update_at__date": { "type": "string", "examples": [ "May 30, 2026" ] }, "status_update_at__time": { "type": "string", "examples": [ "2:28 PM" ] }, "status_update_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "status_update_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "status_update_at__dayofweek": { "type": "string", "examples": [ "Saturday" ] }, "updated_at": { "type": "string", "examples": [ "May 30, 2026, 2:28 PM" ] }, "updated_at__date": { "type": "string", "examples": [ "May 30, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "2:28 PM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Saturday" ] }, "status": { "type": "string", "examples": [ "Pending" ] }, "status_is_public": { "type": "boolean", "examples": [ true ] }, "status_type": { "type": "string", "examples": [ "pending" ] }, "user_name": { "type": "string", "examples": [ "Example Applicant" ] }, "has_received_invitation": { "type": "boolean", "examples": [ false ] }, "status_color": { "type": "string", "examples": [ "#6c757d" ] }, "status_lightness": { "type": "integer", "examples": [ 0 ] } } }, "relations": { "type": "object", "properties": {} }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "status_update": { "type": "boolean", "examples": [ true ] }, "downloadCertificate": { "type": "boolean", "examples": [ false ] } } } }, "examples": [ { "object": { "id": 2, "role_offer_id": 1, "user_id": 1235, "status_id": 2, "status_update_at": "2026-05-30T14:28:24.000000Z", "created_at": "2026-05-30T14:28:24.000000Z", "updated_at": "2026-05-30T14:28:24.000000Z" }, "nice": { "rrn": "rrn:local:20101:role_offer_user:2", "journey_step": "", "journey_step_category": "", "created_at": "May 30, 2026, 2:28 PM", "created_at__date": "May 30, 2026", "created_at__time": "2:28 PM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Saturday", "feedback": "", "status_id": "Pending", "status_id:value": 2, "status_id:array": "Pending", "status_update_at": "May 30, 2026, 2:28 PM", "status_update_at__date": "May 30, 2026", "status_update_at__time": "2:28 PM", "status_update_at__offset": " (+00:00 UTC)", "status_update_at__offset_minutes": 0, "status_update_at__dayofweek": "Saturday", "updated_at": "May 30, 2026, 2:28 PM", "updated_at__date": "May 30, 2026", "updated_at__time": "2:28 PM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Saturday", "status": "Pending", "status_is_public": true, "status_type": "pending", "user_name": "Example Applicant", "has_received_invitation": false, "status_color": "#6c757d", "status_lightness": 0 }, "relations": {}, "permissions": { "read": true, "update": true, "delete": true, "status_update": true, "downloadCertificate": false } } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Role offer demand exceeded" ] } }, "examples": [ { "message": "Role offer demand exceeded" } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } }, "405": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "This will exceed the confidence level of this Role offer" ] }, "reference": { "type": "string", "examples": [ "override_system_limits.headcount.roleoffer.confidence_level" ] } }, "examples": [ { "message": "This will exceed the confidence level of this Role offer", "reference": "override_system_limits.headcount.roleoffer.confidence_level" } ] } } } } }, "tags": [ "Role Offer Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status_id": { "type": "integer", "description": "Where the application stands. Read the available statuses, and the id of each, from the status option set - they are configured per account, so do not hard-code ids. Changing this is the main thing an update does, and it is what sets off whatever the account has configured to follow a status change. An account may also restrict which statuses can follow which, in which case a move it does not allow is refused.", "examples": [ 13 ] }, "user_id": { "type": "integer", "description": "The user to add to the role offer. A user can hold only one live application per role offer; a second one is rejected. Cannot be changed afterwards - to move someone to a different role offer, delete this application and create another.", "examples": [ 1234 ] }, "secondary_assignment": { "type": "boolean", "description": "Mark the application as a secondary one. Secondary applications do not count towards the limit on how many roles a person may hold, and are counted against the role offer's separate secondary allowance rather than its main demand.", "examples": [ 0 ] }, "is_reserved": { "type": "boolean", "description": "Place the person in the role offer's reserve list, taking up one of its reserved places rather than one of its main ones. Only meaningful on a role offer that has reserved places configured; on one that does not, the request is refused because the reserve list has no room.", "examples": [ 0 ] }, "custom_*": { "type": "string", "description": "A custom attribute, named by its code - custom_shirt_size, for example. The value follows the attribute's own type, so it may be a string, a number, a boolean or a list. See the custom attributes documentation.", "examples": [ null ] } }, "required": [ "status_id", "user_id" ] } } } } }, "put": { "summary": "Add many users to a role offer", "operationId": "addManyUsersToARoleOffer", "description": "Adds a set of people to the role offer in the URL at once.\n\n**This write is queued.** The response does not contain the applications and\ndoes not mean they exist yet - it means the request was accepted and the work is\nrunning in the background. The payload is a single `queue` field holding an\nidentifier for that work. There is no endpoint that resolves the identifier, so\nconfirm the outcome by listing the role offer's applications.\n\nChoose the people either way round:\n\n- Send `applyTo` as `selected` with `selected` holding the user IDs to add.\n- Send any other `applyTo` value to add every user the caller can see, narrowed\n by an optional `filter` in the same form the user listing accepts.\n\nPeople who already hold an application on this role offer are skipped, so the\nsame request can be repeated safely.\n\nThe same demand, allowance and transition limits the single create is subject to\napply to each person here, but because the work is queued they cannot be reported\nback: a person the limits refuse is skipped and the request still returns a queue\ntoken. **A request whose fields are all valid therefore always succeeds, whether\nor not anybody is added.** Only malformed input is refused, with a 422 before\nanything is queued.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "queue": { "type": "string", "examples": [ "mTsVQ1NCLS3vg7WwP5kG1Vbt" ] } }, "examples": [ { "queue": "mTsVQ1NCLS3vg7WwP5kG1Vbt" } ] } } } } }, "tags": [ "Role Offer Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "applyTo": { "type": "string", "description": "Send `selected` to add only the users named in `selected`. Any other value adds every user the caller can see, narrowed by `filter` if one is sent. The value is not checked against a list, so a typo is accepted and treated as \"everyone\".", "examples": [ null ] }, "selected": { "type": "array", "description": "The IDs of the users to add. Required in practice when `applyTo` is `selected` and ignored otherwise, but nothing validates that: omitting it still returns a queue token, and the background work then adds nobody.", "items": { "type": "integer" }, "examples": [ [] ] }, "status_id": { "type": "integer", "description": "The status to start each new application on. Defaults to the account's own default applied status. Not validated here, so an id that does not exist is accepted and the background work fails rather than the request.", "examples": [ 1 ] } }, "required": [ "applyTo" ] } } } } }, "parameters": [ { "in": "path", "name": "roleoffer_id", "description": "The ID of the role offer.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/headcount/roleoffer/{roleoffer_id}/user/{id}": { "get": { "summary": "Read an application", "operationId": "readAnApplication", "description": "Returns one person's application to a role offer: the status it is at, when\nthat status last changed, whether it is a secondary or a reserved place, and\nany note recorded against it.\n\n`nice` carries the readable form of the same record - the status as a label,\nits type, the colour the portal shows it in, and the name of the journey step\nthe person is on if the role offer has a journey attached. `status_type` is the\nvalue to branch on: `status_id` and the label are configured per account, but\nthe type behind them is not.\n\nThe application must belong to the role offer in the URL; a mismatched pair\nreturns a 404.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "role_offer_id": { "type": "integer", "examples": [ 1 ] }, "user_id": { "type": "integer", "examples": [ 1234 ] }, "status_id": { "type": "integer", "examples": [ 13 ] }, "ranking": { "type": "integer", "examples": [ 0 ] }, "role_offer_feedback_form_completed_at": { "type": [ "string", "null" ], "examples": [ null ] }, "secondary_assignment": { "type": "integer", "examples": [ 0 ] }, "expires_at": { "type": [ "string", "null" ], "examples": [ null ] }, "feedback": { "type": [ "string", "null" ], "examples": [ null ] }, "status_update_at": { "type": "string", "examples": [ "2026-05-30 14:28:24" ] }, "application_form_completed_at": { "type": "string", "examples": [ "2026-05-30 14:28:24" ] }, "application_withdrawn_at": { "type": [ "string", "null" ], "examples": [ null ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "waitlist_invitation_email_sent_at": { "type": [ "string", "null" ], "examples": [ null ] }, "waitlist_reminder_email_sent_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_reserved": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-05-30T14:28:24.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-05-30T14:28:24.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:role_offer_user:1" ] }, "journey_step": { "type": "string", "examples": [ "Application review" ] }, "journey_step_category": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "May 30, 2026, 2:28 PM" ] }, "created_at__date": { "type": "string", "examples": [ "May 30, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "2:28 PM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Saturday" ] }, "feedback": { "type": "string", "examples": [ "" ] }, "status_id": { "type": "string", "examples": [ "Applied" ] }, "status_id:value": { "type": "integer", "examples": [ 13 ] }, "status_id:array": { "type": "string", "examples": [ "Applied" ] }, "status_update_at": { "type": "string", "examples": [ "May 30, 2026, 2:28 PM" ] }, "status_update_at__date": { "type": "string", "examples": [ "May 30, 2026" ] }, "status_update_at__time": { "type": "string", "examples": [ "2:28 PM" ] }, "status_update_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "status_update_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "status_update_at__dayofweek": { "type": "string", "examples": [ "Saturday" ] }, "updated_at": { "type": "string", "examples": [ "May 30, 2026, 2:28 PM" ] }, "updated_at__date": { "type": "string", "examples": [ "May 30, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "2:28 PM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Saturday" ] }, "status": { "type": "string", "examples": [ "Applied" ] }, "status_is_public": { "type": "boolean", "examples": [ true ] }, "status_type": { "type": "string", "examples": [ "applied" ] }, "user_name": { "type": "string", "examples": [ "Example Applicant" ] }, "has_received_invitation": { "type": "boolean", "examples": [ false ] }, "status_color": { "type": "string", "examples": [ "#6c757d" ] }, "status_lightness": { "type": "integer", "examples": [ 0 ] } } }, "relations": { "type": "object", "properties": {} }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "status_update": { "type": "boolean", "examples": [ false ] }, "downloadCertificate": { "type": "boolean", "examples": [ false ] } } } }, "examples": [ { "object": { "id": 1, "role_offer_id": 1, "user_id": 1234, "status_id": 13, "ranking": 0, "role_offer_feedback_form_completed_at": null, "secondary_assignment": 0, "expires_at": null, "feedback": null, "status_update_at": "2026-05-30 14:28:24", "application_form_completed_at": "2026-05-30 14:28:24", "application_withdrawn_at": null, "sort_order": 0, "waitlist_invitation_email_sent_at": null, "waitlist_reminder_email_sent_at": null, "is_reserved": 0, "deleted_at": null, "is_erased": 0, "created_at": "2026-05-30T14:28:24.000000Z", "updated_at": "2026-05-30T14:28:24.000000Z", "deleted_by": null }, "nice": { "rrn": "rrn:local:20101:role_offer_user:1", "journey_step": "Application review", "journey_step_category": null, "created_at": "May 30, 2026, 2:28 PM", "created_at__date": "May 30, 2026", "created_at__time": "2:28 PM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Saturday", "feedback": "", "status_id": "Applied", "status_id:value": 13, "status_id:array": "Applied", "status_update_at": "May 30, 2026, 2:28 PM", "status_update_at__date": "May 30, 2026", "status_update_at__time": "2:28 PM", "status_update_at__offset": " (+00:00 UTC)", "status_update_at__offset_minutes": 0, "status_update_at__dayofweek": "Saturday", "updated_at": "May 30, 2026, 2:28 PM", "updated_at__date": "May 30, 2026", "updated_at__time": "2:28 PM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Saturday", "status": "Applied", "status_is_public": true, "status_type": "applied", "user_name": "Example Applicant", "has_received_invitation": false, "status_color": "#6c757d", "status_lightness": 0 }, "relations": {}, "permissions": { "read": true, "update": true, "delete": true, "status_update": false, "downloadCertificate": false } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Role Offer Module" ] }, "put": { "summary": "Update an application", "operationId": "updateAnApplication", "description": "Moves an application to a new status, and optionally records a note or changes\nwhether it is a secondary or a reserved place. Returns the application in the\nsame shape as reading it.\n\n**`status_id` is required on every update**, so unlike most updates in this API\nan empty body is a 422 rather than a no-op. Send the status the application\nshould now be at, even if it is the one it is already at. If you do not know the\naccount's status ids, send `status_type` instead and the matching status is\nresolved for you.\n\nChanging the status is what sets off everything the account has configured to\nfollow it - emails, journey steps, certificates. It is also the point at which\nthe same limits the create is subject to are re-checked, so an update can come\nback as a **403** naming the demand, allowance or transition rule that refused\nit, or a **405** for the confidence level - see the create for how to pass that\none.\n\nTwo behaviours worth knowing:\n\n- Moving an application off a waitlist reorders the rest of that waitlist, so\n other applications on the same role offer change as a side effect of this one.\n- Where the account withdraws people from future shifts when they leave a role,\n moving an application to a status that counts as declined does that too.\n\n`user_id` and `role_offer_id` are accepted and ignored: an application cannot be\nmoved to another person or another role offer. Beyond the fields listed here the\nendpoint also accepts the account's own configured attributes for an\napplication.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "role_offer_id": { "type": "integer", "examples": [ 1 ] }, "user_id": { "type": "integer", "examples": [ 1234 ] }, "status_id": { "type": "integer", "examples": [ 13 ] }, "ranking": { "type": "integer", "examples": [ 0 ] }, "role_offer_feedback_form_completed_at": { "type": [ "string", "null" ], "examples": [ null ] }, "secondary_assignment": { "type": "integer", "examples": [ 0 ] }, "expires_at": { "type": [ "string", "null" ], "examples": [ null ] }, "feedback": { "type": [ "string", "null" ], "examples": [ null ] }, "status_update_at": { "type": "string", "examples": [ "2026-05-30 14:28:24" ] }, "application_form_completed_at": { "type": "string", "examples": [ "2026-05-30 14:28:24" ] }, "application_withdrawn_at": { "type": [ "string", "null" ], "examples": [ null ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "waitlist_invitation_email_sent_at": { "type": [ "string", "null" ], "examples": [ null ] }, "waitlist_reminder_email_sent_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_reserved": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-05-30T14:28:24.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-05-30T14:28:24.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:role_offer_user:1" ] }, "journey_step": { "type": "string", "examples": [ "Application review" ] }, "journey_step_category": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "May 30, 2026, 2:28 PM" ] }, "created_at__date": { "type": "string", "examples": [ "May 30, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "2:28 PM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Saturday" ] }, "feedback": { "type": "string", "examples": [ "" ] }, "status_id": { "type": "string", "examples": [ "Applied" ] }, "status_id:value": { "type": "integer", "examples": [ 13 ] }, "status_id:array": { "type": "string", "examples": [ "Applied" ] }, "status_update_at": { "type": "string", "examples": [ "May 30, 2026, 2:28 PM" ] }, "status_update_at__date": { "type": "string", "examples": [ "May 30, 2026" ] }, "status_update_at__time": { "type": "string", "examples": [ "2:28 PM" ] }, "status_update_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "status_update_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "status_update_at__dayofweek": { "type": "string", "examples": [ "Saturday" ] }, "updated_at": { "type": "string", "examples": [ "May 30, 2026, 2:28 PM" ] }, "updated_at__date": { "type": "string", "examples": [ "May 30, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "2:28 PM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Saturday" ] }, "status": { "type": "string", "examples": [ "Applied" ] }, "status_is_public": { "type": "boolean", "examples": [ true ] }, "status_type": { "type": "string", "examples": [ "applied" ] }, "user_name": { "type": "string", "examples": [ "Example Applicant" ] }, "has_received_invitation": { "type": "boolean", "examples": [ false ] }, "status_color": { "type": "string", "examples": [ "#6c757d" ] }, "status_lightness": { "type": "integer", "examples": [ 0 ] } } }, "relations": { "type": "object", "properties": {} }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "status_update": { "type": "boolean", "examples": [ false ] }, "downloadCertificate": { "type": "boolean", "examples": [ false ] } } } }, "examples": [ { "object": { "id": 1, "role_offer_id": 1, "user_id": 1234, "status_id": 13, "ranking": 0, "role_offer_feedback_form_completed_at": null, "secondary_assignment": 0, "expires_at": null, "feedback": null, "status_update_at": "2026-05-30 14:28:24", "application_form_completed_at": "2026-05-30 14:28:24", "application_withdrawn_at": null, "sort_order": 0, "waitlist_invitation_email_sent_at": null, "waitlist_reminder_email_sent_at": null, "is_reserved": 0, "deleted_at": null, "is_erased": 0, "created_at": "2026-05-30T14:28:24.000000Z", "updated_at": "2026-05-30T14:28:24.000000Z", "deleted_by": null }, "nice": { "rrn": "rrn:local:20101:role_offer_user:1", "journey_step": "Application review", "journey_step_category": null, "created_at": "May 30, 2026, 2:28 PM", "created_at__date": "May 30, 2026", "created_at__time": "2:28 PM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Saturday", "feedback": "", "status_id": "Applied", "status_id:value": 13, "status_id:array": "Applied", "status_update_at": "May 30, 2026, 2:28 PM", "status_update_at__date": "May 30, 2026", "status_update_at__time": "2:28 PM", "status_update_at__offset": " (+00:00 UTC)", "status_update_at__offset_minutes": 0, "status_update_at__dayofweek": "Saturday", "updated_at": "May 30, 2026, 2:28 PM", "updated_at__date": "May 30, 2026", "updated_at__time": "2:28 PM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Saturday", "status": "Applied", "status_is_public": true, "status_type": "applied", "user_name": "Example Applicant", "has_received_invitation": false, "status_color": "#6c757d", "status_lightness": 0 }, "relations": {}, "permissions": { "read": true, "update": true, "delete": true, "status_update": false, "downloadCertificate": false } } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Cannot move between those statuses" ] } }, "examples": [ { "message": "Cannot move between those statuses" } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } }, "405": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "This will exceed the confidence level of this Role offer" ] }, "reference": { "type": "string", "examples": [ "override_system_limits.headcount.roleoffer.confidence_level" ] } }, "examples": [ { "message": "This will exceed the confidence level of this Role offer", "reference": "override_system_limits.headcount.roleoffer.confidence_level" } ] } } } } }, "tags": [ "Role Offer Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status_id": { "type": "integer", "description": "Where the application stands. Read the available statuses, and the id of each, from the status option set - they are configured per account, so do not hard-code ids. Changing this is the main thing an update does, and it is what sets off whatever the account has configured to follow a status change. An account may also restrict which statuses can follow which, in which case a move it does not allow is refused.", "examples": [ 13 ] }, "feedback": { "type": "string", "description": "Free-text note recorded against the application. Not shown to the person the application belongs to.", "examples": [ null ] }, "secondary_assignment": { "type": "boolean", "description": "Mark the application as a secondary one. Secondary applications do not count towards the limit on how many roles a person may hold, and are counted against the role offer's separate secondary allowance rather than its main demand.", "examples": [ 0 ] }, "is_reserved": { "type": "boolean", "description": "Place the person in the role offer's reserve list, taking up one of its reserved places rather than one of its main ones. Only meaningful on a role offer that has reserved places configured; on one that does not, the request is refused because the reserve list has no room.", "examples": [ 0 ] }, "status_type": { "type": "string", "description": "An alternative to `status_id` on update: send the type of the status you want - for example `accepted` or `declined` - and it is resolved to the matching status for the account. Use it when you know the outcome you want but not the account's ids. A type that matches nothing is not reported as such; the request comes back as a 422 naming `status_id` instead.", "examples": [ null ] }, "custom_*": { "type": "string", "description": "A custom attribute, named by its code - custom_shirt_size, for example. The value follows the attribute's own type, so it may be a string, a number, a boolean or a list. See the custom attributes documentation.", "examples": [ null ] } }, "required": [ "status_id" ] } } } } }, "delete": { "summary": "Delete an application", "operationId": "deleteAnApplication", "description": "Removes a person's application to the role offer, freeing the place it occupied\nand freeing that person to be added to the role offer again.\n\nThe status history recorded against the application goes with it, so if you need\nthat history, read it before deleting.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "204": { "description": "No content, successful deletion", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Role Offer Module" ] }, "parameters": [ { "in": "path", "name": "roleoffer_id", "description": "The ID of the role offer.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } }, { "in": "path", "name": "id", "description": "The ID of the application.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/event": { "get": { "summary": "List events", "operationId": "listEvents", "description": "Returns the events in the account you are calling as.\n\nWhat comes back depends on who is asking. A caller who may read events gets every\nevent, published or not. A caller who may not gets only events that are published\nand approved. An anonymous caller gets only events that are both public and\npublished, and only on an account that has public browsing turned on - otherwise\nthe endpoint answers as though it does not exist.\n\nEvents still being drafted in the admin console are never returned to anyone but\nthe person drafting them.", "parameters": [ { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "query", "name": "extras", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "required": false, "schema": { "type": "array", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "items": { "type": "string", "enum": [ "leader_state", "shift_count", "stats", "certificate_user_count" ] }, "examples": [ [ "leader_state" ] ] } }, { "in": "query", "name": "with", "description": "A list of relations to include in the response. May be single records or collections.\nIt is often more efficient to retrieve this way, to avoid follow-up API calls.", "required": false, "schema": { "type": "array", "description": "A list of relations to include in the response. May be single records or collections.\nIt is often more efficient to retrieve this way, to avoid follow-up API calls.", "items": { "type": "string", "enum": [ "hasManyDeepFromRelationsWithConstraints", "hasOneDeepFromRelationsWithConstraints", "hasManyDeepFromReverse", "hasOneDeepFromReverse" ] }, "examples": [ [ "hasManyDeepFromRelationsWithConstraints" ] ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 21476343 ] }, "parent_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_template_id": { "type": [ "string", "null" ], "examples": [ null ] }, "path": { "type": "string", "examples": [ "21476343" ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "event_type_id": { "type": "integer", "examples": [ 11 ] }, "journey_id": { "type": [ "string", "null" ], "examples": [ null ] }, "timezone": { "type": "string", "examples": [ "UTC" ] }, "start_timestamp": { "type": "string", "examples": [ "2026-09-17T05:00:00.000000Z" ] }, "end_timestamp": { "type": "string", "examples": [ "2026-10-01T05:00:00.000000Z" ] }, "is_ongoing": { "type": "integer", "examples": [ 0 ] }, "apps_open_timestamp": { "type": "string", "examples": [ "2026-05-30T05:00:00.000000Z" ] }, "apps_close_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_functional_area_job_title_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_status_default": { "type": "integer", "examples": [ 2 ] }, "max_shift_apps_per_user": { "type": "integer", "examples": [ 0 ] }, "min_shift_apps_per_user": { "type": "integer", "examples": [ 0 ] }, "min_shift_apps_per_shift_type": { "type": [ "string", "null" ], "examples": [ null ] }, "max_shift_apps_per_shift_type": { "type": [ "string", "null" ], "examples": [ null ] }, "gap_between_shifts": { "type": "integer", "examples": [ 0 ] }, "shift_confirmed_status_default": { "type": "integer", "examples": [ 3 ] }, "shift_rejected_status_default": { "type": "integer", "examples": [ 6 ] }, "shift_can_withdraw_default": { "type": "integer", "examples": [ 1 ] }, "shift_can_confirm_default": { "type": "integer", "examples": [ 1 ] }, "shift_can_confirm_limit": { "type": "integer", "examples": [ 0 ] }, "shift_can_withdraw_limit": { "type": "integer", "examples": [ 0 ] }, "shift_checked_in_status_default": { "type": "integer", "examples": [ 4 ] }, "shift_checked_out_status_default": { "type": "integer", "examples": [ 4 ] }, "certificate_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_leader_feedback_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_feedback_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_default_journey_complete_status": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_default_journey_id": { "type": [ "string", "null" ], "examples": [ null ] }, "allow_user_activities": { "type": "integer", "examples": [ 0 ] }, "user_activity_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "training_ids": { "type": [ "string", "null" ], "examples": [ null ] }, "banner_image": { "type": [ "string", "null" ], "examples": [ null ] }, "grid_image": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "visibility_show_groups": { "type": "array", "examples": [ [] ] }, "visibility_hide_groups": { "type": "array", "examples": [ [] ] }, "visibility_show_roleoffer": { "type": "array", "examples": [ [] ] }, "role_offer_address": { "type": "integer", "examples": [ 0 ] }, "checkin_visible_attributes": { "type": "array", "examples": [ [] ] }, "shift_filter_attributes": { "type": [ "string", "null" ], "examples": [ null ] }, "leader_shift_filter_attributes": { "type": [ "string", "null" ], "examples": [ null ] }, "self_checkin": { "type": "integer", "examples": [ 0 ] }, "self_checkin_open": { "type": "integer", "examples": [ 1800 ] }, "self_checkin_close": { "type": "integer", "examples": [ 1800 ] }, "self_checkout_close": { "type": "integer", "examples": [ 1800 ] }, "checkin_close_default": { "type": "integer", "examples": [ 0 ] }, "shift_precheckin_open_default": { "type": "integer", "examples": [ 0 ] }, "shift_enable_waitlist_default": { "type": "integer", "examples": [ 0 ] }, "geofence_checkin_limit_default": { "type": [ "string", "null" ], "examples": [ null ] }, "max_waitlist": { "type": "integer", "examples": [ 0 ] }, "group_booking_ttl_default": { "type": [ "string", "null" ], "examples": [ null ] }, "max_group_demand_default": { "type": [ "string", "null" ], "examples": [ null ] }, "max_group_size": { "type": [ "string", "null" ], "examples": [ null ] }, "reserved_expiry": { "type": [ "string", "null" ], "examples": [ null ] }, "post_feedback_form": { "type": [ "string", "null" ], "examples": [ null ] }, "post_feedback_publish_at": { "type": [ "string", "null" ], "examples": [ null ] }, "expression_of_interest": { "type": "integer", "examples": [ 0 ] }, "journey_complete_status": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_apply_status": { "type": [ "string", "null" ], "examples": [ null ] }, "expression_of_interest_form": { "type": [ "string", "null" ], "examples": [ null ] }, "cancel_expression_of_interest_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "eoi_demand": { "type": "integer", "examples": [ 0 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "is_virtual": { "type": "integer", "examples": [ 0 ] }, "status": { "type": "string", "examples": [ "published" ] }, "approval_status": { "type": "string", "examples": [ "approved" ] }, "approval_reason": { "type": [ "string", "null" ], "examples": [ null ] }, "promoted": { "type": "integer", "examples": [ 0 ] }, "public": { "type": "integer", "examples": [ 0 ] }, "is_cancelled": { "type": "integer", "examples": [ 0 ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "public_shift": { "type": "integer", "examples": [ 0 ] }, "public_shift_default": { "type": "integer", "examples": [ 0 ] }, "token": { "type": "string", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] }, "certificates_awarded": { "type": "integer", "examples": [ 0 ] }, "created_by": { "type": [ "string", "null" ], "examples": [ null ] }, "updated_by": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:43.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:43.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "description": { "type": "string", "examples": [ "

A weekend of community events across the city.

" ] }, "name": { "type": "string", "examples": [ "Community Festival" ] }, "post_feedback": { "type": "string", "examples": [ "" ] }, "tags": { "type": [ "string", "null" ], "examples": [ null ] }, "address": { "type": "object", "properties": { "iso": { "type": "string", "examples": [ "AUS" ] }, "region_code": { "type": "string", "examples": [ "VIC" ] }, "coordinates": { "type": "object", "properties": { "latitude": { "type": "string", "examples": [ "-37.814200" ] }, "longitude": { "type": "string", "examples": [ "144.963200" ] } } }, "street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "city": { "type": "string", "examples": [ "MELBOURNE" ] }, "postcode": { "type": "string", "examples": [ "3000" ] }, "region": { "type": "string", "examples": [ "VIC" ] }, "country": { "type": "string", "examples": [ "AU" ] }, "latitude": { "type": "string", "examples": [ "-37.814200" ] }, "longitude": { "type": "string", "examples": [ "144.963200" ] } } } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:example:20101:event:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] }, "address": { "type": "string", "examples": [ "1 Example Street\nMELBOURNE\nVictoria\nAustralia\n3000" ] }, "address_oneline": { "type": "string", "examples": [ "1 Example Street, MELBOURNE, Victoria, Australia, 3000" ] }, "address.country": { "type": "string", "examples": [ "Australia" ] }, "address.country:raw": { "type": "string", "examples": [ "AUS" ] }, "address.city": { "type": "string", "examples": [ "MELBOURNE" ] }, "address.region": { "type": "string", "examples": [ "Victoria" ] }, "address.region:raw": { "type": "string", "examples": [ "VIC" ] }, "address.postcode": { "type": "string", "examples": [ "3000" ] }, "address.street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "address.street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "address.street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "address.latitude": { "type": "string", "examples": [ "-37.814200" ] }, "address.longitude": { "type": "string", "examples": [ "144.963200" ] }, "allow_user_activities": { "type": "string", "examples": [ "No" ] }, "approval_status": { "type": "string", "examples": [ "Approved" ] }, "approval_status:value": { "type": "string", "examples": [ "approved" ] }, "approval_status:array": { "type": "string", "examples": [ "Approved" ] }, "apps_open_timestamp": { "type": "string", "examples": [ "May 30, 2026, 5:00 AM" ] }, "apps_open_timestamp__date": { "type": "string", "examples": [ "May 30, 2026" ] }, "apps_open_timestamp__time": { "type": "string", "examples": [ "5:00 AM" ] }, "apps_open_timestamp__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "apps_open_timestamp__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "apps_open_timestamp__dayofweek": { "type": "string", "examples": [ "Saturday" ] }, "cancel_expression_of_interest_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "cancel_expression_of_interest_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "cancel_expression_of_interest_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "end_timestamp": { "type": "string", "examples": [ "Oct 1, 2026, 5:00 AM" ] }, "end_timestamp__date": { "type": "string", "examples": [ "Oct 1, 2026" ] }, "end_timestamp__time": { "type": "string", "examples": [ "5:00 AM" ] }, "end_timestamp__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "end_timestamp__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "end_timestamp__dayofweek": { "type": "string", "examples": [ "Thursday" ] }, "event_template_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_template_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "event_template_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "event_type_id": { "type": "string", "examples": [ "ratione laborum dolor" ] }, "event_type_id:value": { "type": "integer", "examples": [ 11 ] }, "event_type_id:array": { "type": "string", "examples": [ "ratione laborum dolor" ] }, "expression_of_interest": { "type": "string", "examples": [ "No" ] }, "headcount_location_venue_id": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "is_ongoing": { "type": "string", "examples": [ "No" ] }, "is_virtual": { "type": "string", "examples": [ "No" ] }, "name": { "type": "string", "examples": [ "Community Festival" ] }, "promoted": { "type": "string", "examples": [ "No" ] }, "role_offer_address": { "type": "string", "examples": [ "No" ] }, "self_checkin": { "type": "string", "examples": [ "No" ] }, "shift_application_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_feedback_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_feedback_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_feedback_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "start_timestamp": { "type": "string", "examples": [ "Sep 17, 2026, 5:00 AM" ] }, "start_timestamp__date": { "type": "string", "examples": [ "Sep 17, 2026" ] }, "start_timestamp__time": { "type": "string", "examples": [ "5:00 AM" ] }, "start_timestamp__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "start_timestamp__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "start_timestamp__dayofweek": { "type": "string", "examples": [ "Thursday" ] }, "status": { "type": "string", "examples": [ "Published" ] }, "status:value": { "type": "string", "examples": [ "published" ] }, "status:array": { "type": "string", "examples": [ "Published" ] }, "tags": { "type": [ "string", "null" ], "examples": [ null ] }, "tags:value": { "type": [ "string", "null" ], "examples": [ null ] }, "tags:array": { "type": [ "string", "null" ], "examples": [ null ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "visibility_hide_groups": { "type": "string", "examples": [ "" ] }, "visibility_show_groups": { "type": "string", "examples": [ "" ] }, "visibility_show_roleoffer": { "type": "string", "examples": [ "" ] }, "full_name": { "type": "string", "examples": [ "Community Festival" ] }, "event_type_name": { "type": "string", "examples": [ "ratione laborum dolor" ] }, "grid_list_image": { "type": [ "string", "null" ], "examples": [ null ] }, "is_eoi_demand_met": { "type": "boolean", "examples": [ false ] }, "has_payrun": { "type": "boolean", "examples": [ false ] }, "min_shifts": { "type": "integer", "examples": [ 0 ] }, "post_event_feedback_form_completed_at": { "type": [ "string", "null" ], "examples": [ null ] }, "expression_of_interest_form_completed_at": { "type": [ "string", "null" ], "examples": [ null ] }, "expression_of_interest_form_cancelled_at": { "type": [ "string", "null" ], "examples": [ null ] }, "account_name": { "type": "string", "examples": [ "Example Organisation" ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "apply": { "type": "boolean", "examples": [ true ] }, "cancel": { "type": "boolean", "examples": [ true ] }, "can_publish": { "type": "boolean", "examples": [ true ] } } }, "attributes": { "type": "array", "examples": [ [] ] } } }, "examples": [ [ { "object": { "id": 21476343, "parent_id": null, "event_template_id": null, "path": "21476343", "account_id": 20101, "event_type_id": 11, "journey_id": null, "timezone": "UTC", "start_timestamp": "2026-09-17T05:00:00.000000Z", "end_timestamp": "2026-10-01T05:00:00.000000Z", "is_ongoing": 0, "apps_open_timestamp": "2026-05-30T05:00:00.000000Z", "apps_close_timestamp": null, "headcount_location_venue_id": null, "headcount_functional_area_job_title_id": null, "shift_status_default": 2, "max_shift_apps_per_user": 0, "min_shift_apps_per_user": 0, "min_shift_apps_per_shift_type": null, "max_shift_apps_per_shift_type": null, "gap_between_shifts": 0, "shift_confirmed_status_default": 3, "shift_rejected_status_default": 6, "shift_can_withdraw_default": 1, "shift_can_confirm_default": 1, "shift_can_confirm_limit": 0, "shift_can_withdraw_limit": 0, "shift_checked_in_status_default": 4, "shift_checked_out_status_default": 4, "certificate_id": null, "shift_application_form_id_default": null, "shift_withdraw_form_id_default": null, "shift_checkin_form_id_default": null, "shift_attended_form_id_default": null, "shift_checkout_form_id_default": null, "shift_leader_feedback_form_id_default": null, "shift_feedback_form_id_default": null, "shift_precheckin_form_id_default": null, "shift_default_journey_complete_status": null, "shift_default_journey_id": null, "allow_user_activities": 0, "user_activity_form_id": null, "training_ids": null, "banner_image": null, "grid_image": null, "minimum_dob": null, "minimum_age": null, "maximum_dob": null, "maximum_age": null, "visibility_show_groups": [], "visibility_hide_groups": [], "visibility_show_roleoffer": [], "role_offer_address": 0, "checkin_visible_attributes": [], "shift_filter_attributes": null, "leader_shift_filter_attributes": null, "self_checkin": 0, "self_checkin_open": 1800, "self_checkin_close": 1800, "self_checkout_close": 1800, "checkin_close_default": 0, "shift_precheckin_open_default": 0, "shift_enable_waitlist_default": 0, "geofence_checkin_limit_default": null, "max_waitlist": 0, "group_booking_ttl_default": null, "max_group_demand_default": null, "max_group_size": null, "reserved_expiry": null, "post_feedback_form": null, "post_feedback_publish_at": null, "expression_of_interest": 0, "journey_complete_status": null, "journey_apply_status": null, "expression_of_interest_form": null, "cancel_expression_of_interest_form_id": null, "eoi_demand": 0, "sort_order": 0, "is_virtual": 0, "status": "published", "approval_status": "approved", "approval_reason": null, "promoted": 0, "public": 0, "is_cancelled": 0, "is_archived": 0, "public_shift": 0, "public_shift_default": 0, "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "certificates_awarded": 0, "created_by": null, "updated_by": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:36:43.000000Z", "updated_at": "2026-06-09T05:36:43.000000Z", "deleted_by": null, "description": "

A weekend of community events across the city.

", "name": "Community Festival", "post_feedback": "", "tags": null, "address": { "iso": "AUS", "region_code": "VIC", "coordinates": { "latitude": "-37.814200", "longitude": "144.963200" }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "MELBOURNE", "postcode": "3000", "region": "VIC", "country": "AU", "latitude": "-37.814200", "longitude": "144.963200" } }, "nice": { "rrn": "rrn:example:20101:event:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "address": "1 Example Street\nMELBOURNE\nVictoria\nAustralia\n3000", "address_oneline": "1 Example Street, MELBOURNE, Victoria, Australia, 3000", "address.country": "Australia", "address.country:raw": "AUS", "address.city": "MELBOURNE", "address.region": "Victoria", "address.region:raw": "VIC", "address.postcode": "3000", "address.street_address_1": "1 Example Street", "address.street_address_2": null, "address.street_address_3": null, "address.latitude": "-37.814200", "address.longitude": "144.963200", "allow_user_activities": "No", "approval_status": "Approved", "approval_status:value": "approved", "approval_status:array": "Approved", "apps_open_timestamp": "May 30, 2026, 5:00 AM", "apps_open_timestamp__date": "May 30, 2026", "apps_open_timestamp__time": "5:00 AM", "apps_open_timestamp__offset": " (+00:00 UTC)", "apps_open_timestamp__offset_minutes": 0, "apps_open_timestamp__dayofweek": "Saturday", "cancel_expression_of_interest_form_id": null, "cancel_expression_of_interest_form_id:value": null, "cancel_expression_of_interest_form_id:array": null, "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "end_timestamp": "Oct 1, 2026, 5:00 AM", "end_timestamp__date": "Oct 1, 2026", "end_timestamp__time": "5:00 AM", "end_timestamp__offset": " (+00:00 UTC)", "end_timestamp__offset_minutes": 0, "end_timestamp__dayofweek": "Thursday", "event_template_id": null, "event_template_id:value": null, "event_template_id:array": null, "event_type_id": "ratione laborum dolor", "event_type_id:value": 11, "event_type_id:array": "ratione laborum dolor", "expression_of_interest": "No", "headcount_location_venue_id": null, "headcount_location_venue_id:value": null, "headcount_location_venue_id:array": null, "is_ongoing": "No", "is_virtual": "No", "name": "Community Festival", "promoted": "No", "role_offer_address": "No", "self_checkin": "No", "shift_application_form_id_default": null, "shift_application_form_id_default:value": null, "shift_application_form_id_default:array": null, "shift_attended_form_id_default": null, "shift_attended_form_id_default:value": null, "shift_attended_form_id_default:array": null, "shift_checkin_form_id_default": null, "shift_checkin_form_id_default:value": null, "shift_checkin_form_id_default:array": null, "shift_checkout_form_id_default": null, "shift_checkout_form_id_default:value": null, "shift_checkout_form_id_default:array": null, "shift_feedback_form_id_default": null, "shift_feedback_form_id_default:value": null, "shift_feedback_form_id_default:array": null, "shift_precheckin_form_id_default": null, "shift_precheckin_form_id_default:value": null, "shift_precheckin_form_id_default:array": null, "shift_withdraw_form_id_default": null, "shift_withdraw_form_id_default:value": null, "shift_withdraw_form_id_default:array": null, "start_timestamp": "Sep 17, 2026, 5:00 AM", "start_timestamp__date": "Sep 17, 2026", "start_timestamp__time": "5:00 AM", "start_timestamp__offset": " (+00:00 UTC)", "start_timestamp__offset_minutes": 0, "start_timestamp__dayofweek": "Thursday", "status": "Published", "status:value": "published", "status:array": "Published", "tags": null, "tags:value": null, "tags:array": null, "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "visibility_hide_groups": "", "visibility_show_groups": "", "visibility_show_roleoffer": "", "full_name": "Community Festival", "event_type_name": "ratione laborum dolor", "grid_list_image": null, "is_eoi_demand_met": false, "has_payrun": false, "min_shifts": 0, "post_event_feedback_form_completed_at": null, "expression_of_interest_form_completed_at": null, "expression_of_interest_form_cancelled_at": null, "account_name": "Example Organisation" }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "apply": true, "cancel": true, "can_publish": true }, "attributes": [] }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/event?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/event?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/event" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 21476343, "parent_id": null, "event_template_id": null, "path": "21476343", "account_id": 20101, "event_type_id": 11, "journey_id": null, "timezone": "UTC", "start_timestamp": "2026-09-17T05:00:00.000000Z", "end_timestamp": "2026-10-01T05:00:00.000000Z", "is_ongoing": 0, "apps_open_timestamp": "2026-05-30T05:00:00.000000Z", "apps_close_timestamp": null, "headcount_location_venue_id": null, "headcount_functional_area_job_title_id": null, "shift_status_default": 2, "max_shift_apps_per_user": 0, "min_shift_apps_per_user": 0, "min_shift_apps_per_shift_type": null, "max_shift_apps_per_shift_type": null, "gap_between_shifts": 0, "shift_confirmed_status_default": 3, "shift_rejected_status_default": 6, "shift_can_withdraw_default": 1, "shift_can_confirm_default": 1, "shift_can_confirm_limit": 0, "shift_can_withdraw_limit": 0, "shift_checked_in_status_default": 4, "shift_checked_out_status_default": 4, "certificate_id": null, "shift_application_form_id_default": null, "shift_withdraw_form_id_default": null, "shift_checkin_form_id_default": null, "shift_attended_form_id_default": null, "shift_checkout_form_id_default": null, "shift_leader_feedback_form_id_default": null, "shift_feedback_form_id_default": null, "shift_precheckin_form_id_default": null, "shift_default_journey_complete_status": null, "shift_default_journey_id": null, "allow_user_activities": 0, "user_activity_form_id": null, "training_ids": null, "banner_image": null, "grid_image": null, "minimum_dob": null, "minimum_age": null, "maximum_dob": null, "maximum_age": null, "visibility_show_groups": [], "visibility_hide_groups": [], "visibility_show_roleoffer": [], "role_offer_address": 0, "checkin_visible_attributes": [], "shift_filter_attributes": null, "leader_shift_filter_attributes": null, "self_checkin": 0, "self_checkin_open": 1800, "self_checkin_close": 1800, "self_checkout_close": 1800, "checkin_close_default": 0, "shift_precheckin_open_default": 0, "shift_enable_waitlist_default": 0, "geofence_checkin_limit_default": null, "max_waitlist": 0, "group_booking_ttl_default": null, "max_group_demand_default": null, "max_group_size": null, "reserved_expiry": null, "post_feedback_form": null, "post_feedback_publish_at": null, "expression_of_interest": 0, "journey_complete_status": null, "journey_apply_status": null, "expression_of_interest_form": null, "cancel_expression_of_interest_form_id": null, "eoi_demand": 0, "sort_order": 0, "is_virtual": 0, "status": "published", "approval_status": "approved", "approval_reason": null, "promoted": 0, "public": 0, "is_cancelled": 0, "is_archived": 0, "public_shift": 0, "public_shift_default": 0, "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "certificates_awarded": 0, "created_by": null, "updated_by": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:36:43.000000Z", "updated_at": "2026-06-09T05:36:43.000000Z", "deleted_by": null, "description": "

A weekend of community events across the city.

", "name": "Community Festival", "post_feedback": "", "tags": null, "address": { "iso": "AUS", "region_code": "VIC", "coordinates": { "latitude": "-37.814200", "longitude": "144.963200" }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "MELBOURNE", "postcode": "3000", "region": "VIC", "country": "AU", "latitude": "-37.814200", "longitude": "144.963200" } }, "nice": { "rrn": "rrn:example:20101:event:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "address": "1 Example Street\nMELBOURNE\nVictoria\nAustralia\n3000", "address_oneline": "1 Example Street, MELBOURNE, Victoria, Australia, 3000", "address.country": "Australia", "address.country:raw": "AUS", "address.city": "MELBOURNE", "address.region": "Victoria", "address.region:raw": "VIC", "address.postcode": "3000", "address.street_address_1": "1 Example Street", "address.street_address_2": null, "address.street_address_3": null, "address.latitude": "-37.814200", "address.longitude": "144.963200", "allow_user_activities": "No", "approval_status": "Approved", "approval_status:value": "approved", "approval_status:array": "Approved", "apps_open_timestamp": "May 30, 2026, 5:00 AM", "apps_open_timestamp__date": "May 30, 2026", "apps_open_timestamp__time": "5:00 AM", "apps_open_timestamp__offset": " (+00:00 UTC)", "apps_open_timestamp__offset_minutes": 0, "apps_open_timestamp__dayofweek": "Saturday", "cancel_expression_of_interest_form_id": null, "cancel_expression_of_interest_form_id:value": null, "cancel_expression_of_interest_form_id:array": null, "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "end_timestamp": "Oct 1, 2026, 5:00 AM", "end_timestamp__date": "Oct 1, 2026", "end_timestamp__time": "5:00 AM", "end_timestamp__offset": " (+00:00 UTC)", "end_timestamp__offset_minutes": 0, "end_timestamp__dayofweek": "Thursday", "event_template_id": null, "event_template_id:value": null, "event_template_id:array": null, "event_type_id": "ratione laborum dolor", "event_type_id:value": 11, "event_type_id:array": "ratione laborum dolor", "expression_of_interest": "No", "headcount_location_venue_id": null, "headcount_location_venue_id:value": null, "headcount_location_venue_id:array": null, "is_ongoing": "No", "is_virtual": "No", "name": "Community Festival", "promoted": "No", "role_offer_address": "No", "self_checkin": "No", "shift_application_form_id_default": null, "shift_application_form_id_default:value": null, "shift_application_form_id_default:array": null, "shift_attended_form_id_default": null, "shift_attended_form_id_default:value": null, "shift_attended_form_id_default:array": null, "shift_checkin_form_id_default": null, "shift_checkin_form_id_default:value": null, "shift_checkin_form_id_default:array": null, "shift_checkout_form_id_default": null, "shift_checkout_form_id_default:value": null, "shift_checkout_form_id_default:array": null, "shift_feedback_form_id_default": null, "shift_feedback_form_id_default:value": null, "shift_feedback_form_id_default:array": null, "shift_precheckin_form_id_default": null, "shift_precheckin_form_id_default:value": null, "shift_precheckin_form_id_default:array": null, "shift_withdraw_form_id_default": null, "shift_withdraw_form_id_default:value": null, "shift_withdraw_form_id_default:array": null, "start_timestamp": "Sep 17, 2026, 5:00 AM", "start_timestamp__date": "Sep 17, 2026", "start_timestamp__time": "5:00 AM", "start_timestamp__offset": " (+00:00 UTC)", "start_timestamp__offset_minutes": 0, "start_timestamp__dayofweek": "Thursday", "status": "Published", "status:value": "published", "status:array": "Published", "tags": null, "tags:value": null, "tags:array": null, "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "visibility_hide_groups": "", "visibility_show_groups": "", "visibility_show_roleoffer": "", "full_name": "Community Festival", "event_type_name": "ratione laborum dolor", "grid_list_image": null, "is_eoi_demand_met": false, "has_payrun": false, "min_shifts": 0, "post_event_feedback_form_completed_at": null, "expression_of_interest_form_completed_at": null, "expression_of_interest_form_cancelled_at": null, "account_name": "Example Organisation" }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "apply": true, "cancel": true, "can_publish": true }, "attributes": [] }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/event?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/event?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/event", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Event Module" ] }, "post": { "summary": "Create an event", "operationId": "createAnEvent", "description": "Creates an event in the account you are calling as. The response is the same shape\nas reading the event back, so a follow-up read is not needed.\n\n**Only `name` and `description` have to be sent.** Everything the rules below mark\nrequired beyond those two is filled in from the account's own defaults before the\nrequest is validated - the timezone, the five shift status defaults, the\npublication status - and the event type falls back to the first one the account\nhas. New events are created unpublished.\n\n**An event needs a location.** Send an `address`, or a\n`headcount_location_venue_id`, or set `is_virtual`. A request with none of the\nthree is rejected even though each of them is individually optional.\n\nSend `event_template_id` to build the event from one of the account's templates.\nThe template's values are applied over the rest of the request, so a field the\ntemplate sets wins over the one you send.\n\nWhere the account has attribute prefilling turned on, fields you leave out may\ncome back with values of their own, taken from the defaults configured for your\nrole. Read the response rather than assuming an omitted field is empty.\n\nThe account's own configured attributes are accepted as `custom_*` fields.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 21476343 ] }, "parent_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_template_id": { "type": [ "string", "null" ], "examples": [ null ] }, "path": { "type": "string", "examples": [ "21476343" ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "event_type_id": { "type": "integer", "examples": [ 11 ] }, "journey_id": { "type": [ "string", "null" ], "examples": [ null ] }, "timezone": { "type": "string", "examples": [ "UTC" ] }, "start_timestamp": { "type": "string", "examples": [ "2026-09-17T05:00:00.000000Z" ] }, "end_timestamp": { "type": "string", "examples": [ "2026-10-01T05:00:00.000000Z" ] }, "is_ongoing": { "type": "integer", "examples": [ 0 ] }, "apps_open_timestamp": { "type": "string", "examples": [ "2026-05-30T05:00:00.000000Z" ] }, "apps_close_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_functional_area_job_title_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_status_default": { "type": "integer", "examples": [ 2 ] }, "max_shift_apps_per_user": { "type": "integer", "examples": [ 0 ] }, "min_shift_apps_per_user": { "type": "integer", "examples": [ 0 ] }, "min_shift_apps_per_shift_type": { "type": [ "string", "null" ], "examples": [ null ] }, "max_shift_apps_per_shift_type": { "type": [ "string", "null" ], "examples": [ null ] }, "gap_between_shifts": { "type": "integer", "examples": [ 0 ] }, "shift_confirmed_status_default": { "type": "integer", "examples": [ 3 ] }, "shift_rejected_status_default": { "type": "integer", "examples": [ 6 ] }, "shift_can_withdraw_default": { "type": "integer", "examples": [ 1 ] }, "shift_can_confirm_default": { "type": "integer", "examples": [ 1 ] }, "shift_can_confirm_limit": { "type": "integer", "examples": [ 0 ] }, "shift_can_withdraw_limit": { "type": "integer", "examples": [ 0 ] }, "shift_checked_in_status_default": { "type": "integer", "examples": [ 4 ] }, "shift_checked_out_status_default": { "type": "integer", "examples": [ 4 ] }, "certificate_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_leader_feedback_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_feedback_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_default_journey_complete_status": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_default_journey_id": { "type": [ "string", "null" ], "examples": [ null ] }, "allow_user_activities": { "type": "integer", "examples": [ 0 ] }, "user_activity_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "training_ids": { "type": [ "string", "null" ], "examples": [ null ] }, "banner_image": { "type": [ "string", "null" ], "examples": [ null ] }, "grid_image": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "visibility_show_groups": { "type": "array", "examples": [ [] ] }, "visibility_hide_groups": { "type": "array", "examples": [ [] ] }, "visibility_show_roleoffer": { "type": "array", "examples": [ [] ] }, "role_offer_address": { "type": "integer", "examples": [ 0 ] }, "checkin_visible_attributes": { "type": "array", "examples": [ [] ] }, "shift_filter_attributes": { "type": [ "string", "null" ], "examples": [ null ] }, "leader_shift_filter_attributes": { "type": [ "string", "null" ], "examples": [ null ] }, "self_checkin": { "type": "integer", "examples": [ 0 ] }, "self_checkin_open": { "type": "integer", "examples": [ 1800 ] }, "self_checkin_close": { "type": "integer", "examples": [ 1800 ] }, "self_checkout_close": { "type": "integer", "examples": [ 1800 ] }, "checkin_close_default": { "type": "integer", "examples": [ 0 ] }, "shift_precheckin_open_default": { "type": "integer", "examples": [ 0 ] }, "shift_enable_waitlist_default": { "type": "integer", "examples": [ 0 ] }, "geofence_checkin_limit_default": { "type": [ "string", "null" ], "examples": [ null ] }, "max_waitlist": { "type": "integer", "examples": [ 0 ] }, "group_booking_ttl_default": { "type": [ "string", "null" ], "examples": [ null ] }, "max_group_demand_default": { "type": [ "string", "null" ], "examples": [ null ] }, "max_group_size": { "type": [ "string", "null" ], "examples": [ null ] }, "reserved_expiry": { "type": [ "string", "null" ], "examples": [ null ] }, "post_feedback_form": { "type": [ "string", "null" ], "examples": [ null ] }, "post_feedback_publish_at": { "type": [ "string", "null" ], "examples": [ null ] }, "expression_of_interest": { "type": "integer", "examples": [ 0 ] }, "journey_complete_status": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_apply_status": { "type": [ "string", "null" ], "examples": [ null ] }, "expression_of_interest_form": { "type": [ "string", "null" ], "examples": [ null ] }, "cancel_expression_of_interest_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "eoi_demand": { "type": "integer", "examples": [ 0 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "is_virtual": { "type": "integer", "examples": [ 0 ] }, "status": { "type": "string", "examples": [ "published" ] }, "approval_status": { "type": "string", "examples": [ "approved" ] }, "approval_reason": { "type": [ "string", "null" ], "examples": [ null ] }, "promoted": { "type": "integer", "examples": [ 0 ] }, "public": { "type": "integer", "examples": [ 0 ] }, "is_cancelled": { "type": "integer", "examples": [ 0 ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "public_shift": { "type": "integer", "examples": [ 0 ] }, "public_shift_default": { "type": "integer", "examples": [ 0 ] }, "token": { "type": "string", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] }, "certificates_awarded": { "type": "integer", "examples": [ 0 ] }, "created_by": { "type": [ "string", "null" ], "examples": [ null ] }, "updated_by": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:43.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:43.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "description": { "type": "string", "examples": [ "

A weekend of community events across the city.

" ] }, "name": { "type": "string", "examples": [ "Community Festival" ] }, "post_feedback": { "type": "string", "examples": [ "" ] }, "tags": { "type": [ "string", "null" ], "examples": [ null ] }, "address": { "type": "object", "properties": { "iso": { "type": "string", "examples": [ "AUS" ] }, "region_code": { "type": "string", "examples": [ "VIC" ] }, "coordinates": { "type": "object", "properties": { "latitude": { "type": "string", "examples": [ "-37.814200" ] }, "longitude": { "type": "string", "examples": [ "144.963200" ] } } }, "street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "city": { "type": "string", "examples": [ "MELBOURNE" ] }, "postcode": { "type": "string", "examples": [ "3000" ] }, "region": { "type": "string", "examples": [ "VIC" ] }, "country": { "type": "string", "examples": [ "AU" ] }, "latitude": { "type": "string", "examples": [ "-37.814200" ] }, "longitude": { "type": "string", "examples": [ "144.963200" ] } } } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:example:20101:event:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] }, "address": { "type": "string", "examples": [ "1 Example Street\nMELBOURNE\nVictoria\nAustralia\n3000" ] }, "address_oneline": { "type": "string", "examples": [ "1 Example Street, MELBOURNE, Victoria, Australia, 3000" ] }, "address.country": { "type": "string", "examples": [ "Australia" ] }, "address.country:raw": { "type": "string", "examples": [ "AUS" ] }, "address.city": { "type": "string", "examples": [ "MELBOURNE" ] }, "address.region": { "type": "string", "examples": [ "Victoria" ] }, "address.region:raw": { "type": "string", "examples": [ "VIC" ] }, "address.postcode": { "type": "string", "examples": [ "3000" ] }, "address.street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "address.street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "address.street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "address.latitude": { "type": "string", "examples": [ "-37.814200" ] }, "address.longitude": { "type": "string", "examples": [ "144.963200" ] }, "allow_user_activities": { "type": "string", "examples": [ "No" ] }, "approval_status": { "type": "string", "examples": [ "Approved" ] }, "approval_status:value": { "type": "string", "examples": [ "approved" ] }, "approval_status:array": { "type": "string", "examples": [ "Approved" ] }, "apps_open_timestamp": { "type": "string", "examples": [ "May 30, 2026, 5:00 AM" ] }, "apps_open_timestamp__date": { "type": "string", "examples": [ "May 30, 2026" ] }, "apps_open_timestamp__time": { "type": "string", "examples": [ "5:00 AM" ] }, "apps_open_timestamp__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "apps_open_timestamp__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "apps_open_timestamp__dayofweek": { "type": "string", "examples": [ "Saturday" ] }, "cancel_expression_of_interest_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "cancel_expression_of_interest_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "cancel_expression_of_interest_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "end_timestamp": { "type": "string", "examples": [ "Oct 1, 2026, 5:00 AM" ] }, "end_timestamp__date": { "type": "string", "examples": [ "Oct 1, 2026" ] }, "end_timestamp__time": { "type": "string", "examples": [ "5:00 AM" ] }, "end_timestamp__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "end_timestamp__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "end_timestamp__dayofweek": { "type": "string", "examples": [ "Thursday" ] }, "event_template_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_template_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "event_template_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "event_type_id": { "type": "string", "examples": [ "ratione laborum dolor" ] }, "event_type_id:value": { "type": "integer", "examples": [ 11 ] }, "event_type_id:array": { "type": "string", "examples": [ "ratione laborum dolor" ] }, "expression_of_interest": { "type": "string", "examples": [ "No" ] }, "headcount_location_venue_id": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "is_ongoing": { "type": "string", "examples": [ "No" ] }, "is_virtual": { "type": "string", "examples": [ "No" ] }, "name": { "type": "string", "examples": [ "Community Festival" ] }, "promoted": { "type": "string", "examples": [ "No" ] }, "role_offer_address": { "type": "string", "examples": [ "No" ] }, "self_checkin": { "type": "string", "examples": [ "No" ] }, "shift_application_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_feedback_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_feedback_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_feedback_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "start_timestamp": { "type": "string", "examples": [ "Sep 17, 2026, 5:00 AM" ] }, "start_timestamp__date": { "type": "string", "examples": [ "Sep 17, 2026" ] }, "start_timestamp__time": { "type": "string", "examples": [ "5:00 AM" ] }, "start_timestamp__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "start_timestamp__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "start_timestamp__dayofweek": { "type": "string", "examples": [ "Thursday" ] }, "status": { "type": "string", "examples": [ "Published" ] }, "status:value": { "type": "string", "examples": [ "published" ] }, "status:array": { "type": "string", "examples": [ "Published" ] }, "tags": { "type": [ "string", "null" ], "examples": [ null ] }, "tags:value": { "type": [ "string", "null" ], "examples": [ null ] }, "tags:array": { "type": [ "string", "null" ], "examples": [ null ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "visibility_hide_groups": { "type": "string", "examples": [ "" ] }, "visibility_show_groups": { "type": "string", "examples": [ "" ] }, "visibility_show_roleoffer": { "type": "string", "examples": [ "" ] }, "full_name": { "type": "string", "examples": [ "Community Festival" ] }, "event_type_name": { "type": "string", "examples": [ "ratione laborum dolor" ] }, "grid_list_image": { "type": [ "string", "null" ], "examples": [ null ] }, "is_eoi_demand_met": { "type": "boolean", "examples": [ false ] }, "has_payrun": { "type": "boolean", "examples": [ false ] }, "min_shifts": { "type": "integer", "examples": [ 0 ] }, "post_event_feedback_form_completed_at": { "type": [ "string", "null" ], "examples": [ null ] }, "expression_of_interest_form_completed_at": { "type": [ "string", "null" ], "examples": [ null ] }, "expression_of_interest_form_cancelled_at": { "type": [ "string", "null" ], "examples": [ null ] }, "account_name": { "type": "string", "examples": [ "Example Organisation" ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "apply": { "type": "boolean", "examples": [ true ] }, "cancel": { "type": "boolean", "examples": [ true ] }, "can_publish": { "type": "boolean", "examples": [ true ] } } }, "attributes": { "type": "object", "properties": {} } }, "examples": [ { "object": { "id": 21476343, "parent_id": null, "event_template_id": null, "path": "21476343", "account_id": 20101, "event_type_id": 11, "journey_id": null, "timezone": "UTC", "start_timestamp": "2026-09-17T05:00:00.000000Z", "end_timestamp": "2026-10-01T05:00:00.000000Z", "is_ongoing": 0, "apps_open_timestamp": "2026-05-30T05:00:00.000000Z", "apps_close_timestamp": null, "headcount_location_venue_id": null, "headcount_functional_area_job_title_id": null, "shift_status_default": 2, "max_shift_apps_per_user": 0, "min_shift_apps_per_user": 0, "min_shift_apps_per_shift_type": null, "max_shift_apps_per_shift_type": null, "gap_between_shifts": 0, "shift_confirmed_status_default": 3, "shift_rejected_status_default": 6, "shift_can_withdraw_default": 1, "shift_can_confirm_default": 1, "shift_can_confirm_limit": 0, "shift_can_withdraw_limit": 0, "shift_checked_in_status_default": 4, "shift_checked_out_status_default": 4, "certificate_id": null, "shift_application_form_id_default": null, "shift_withdraw_form_id_default": null, "shift_checkin_form_id_default": null, "shift_attended_form_id_default": null, "shift_checkout_form_id_default": null, "shift_leader_feedback_form_id_default": null, "shift_feedback_form_id_default": null, "shift_precheckin_form_id_default": null, "shift_default_journey_complete_status": null, "shift_default_journey_id": null, "allow_user_activities": 0, "user_activity_form_id": null, "training_ids": null, "banner_image": null, "grid_image": null, "minimum_dob": null, "minimum_age": null, "maximum_dob": null, "maximum_age": null, "visibility_show_groups": [], "visibility_hide_groups": [], "visibility_show_roleoffer": [], "role_offer_address": 0, "checkin_visible_attributes": [], "shift_filter_attributes": null, "leader_shift_filter_attributes": null, "self_checkin": 0, "self_checkin_open": 1800, "self_checkin_close": 1800, "self_checkout_close": 1800, "checkin_close_default": 0, "shift_precheckin_open_default": 0, "shift_enable_waitlist_default": 0, "geofence_checkin_limit_default": null, "max_waitlist": 0, "group_booking_ttl_default": null, "max_group_demand_default": null, "max_group_size": null, "reserved_expiry": null, "post_feedback_form": null, "post_feedback_publish_at": null, "expression_of_interest": 0, "journey_complete_status": null, "journey_apply_status": null, "expression_of_interest_form": null, "cancel_expression_of_interest_form_id": null, "eoi_demand": 0, "sort_order": 0, "is_virtual": 0, "status": "published", "approval_status": "approved", "approval_reason": null, "promoted": 0, "public": 0, "is_cancelled": 0, "is_archived": 0, "public_shift": 0, "public_shift_default": 0, "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "certificates_awarded": 0, "created_by": null, "updated_by": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:36:43.000000Z", "updated_at": "2026-06-09T05:36:43.000000Z", "deleted_by": null, "description": "

A weekend of community events across the city.

", "name": "Community Festival", "post_feedback": "", "tags": null, "address": { "iso": "AUS", "region_code": "VIC", "coordinates": { "latitude": "-37.814200", "longitude": "144.963200" }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "MELBOURNE", "postcode": "3000", "region": "VIC", "country": "AU", "latitude": "-37.814200", "longitude": "144.963200" } }, "nice": { "rrn": "rrn:example:20101:event:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "address": "1 Example Street\nMELBOURNE\nVictoria\nAustralia\n3000", "address_oneline": "1 Example Street, MELBOURNE, Victoria, Australia, 3000", "address.country": "Australia", "address.country:raw": "AUS", "address.city": "MELBOURNE", "address.region": "Victoria", "address.region:raw": "VIC", "address.postcode": "3000", "address.street_address_1": "1 Example Street", "address.street_address_2": null, "address.street_address_3": null, "address.latitude": "-37.814200", "address.longitude": "144.963200", "allow_user_activities": "No", "approval_status": "Approved", "approval_status:value": "approved", "approval_status:array": "Approved", "apps_open_timestamp": "May 30, 2026, 5:00 AM", "apps_open_timestamp__date": "May 30, 2026", "apps_open_timestamp__time": "5:00 AM", "apps_open_timestamp__offset": " (+00:00 UTC)", "apps_open_timestamp__offset_minutes": 0, "apps_open_timestamp__dayofweek": "Saturday", "cancel_expression_of_interest_form_id": null, "cancel_expression_of_interest_form_id:value": null, "cancel_expression_of_interest_form_id:array": null, "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "end_timestamp": "Oct 1, 2026, 5:00 AM", "end_timestamp__date": "Oct 1, 2026", "end_timestamp__time": "5:00 AM", "end_timestamp__offset": " (+00:00 UTC)", "end_timestamp__offset_minutes": 0, "end_timestamp__dayofweek": "Thursday", "event_template_id": null, "event_template_id:value": null, "event_template_id:array": null, "event_type_id": "ratione laborum dolor", "event_type_id:value": 11, "event_type_id:array": "ratione laborum dolor", "expression_of_interest": "No", "headcount_location_venue_id": null, "headcount_location_venue_id:value": null, "headcount_location_venue_id:array": null, "is_ongoing": "No", "is_virtual": "No", "name": "Community Festival", "promoted": "No", "role_offer_address": "No", "self_checkin": "No", "shift_application_form_id_default": null, "shift_application_form_id_default:value": null, "shift_application_form_id_default:array": null, "shift_attended_form_id_default": null, "shift_attended_form_id_default:value": null, "shift_attended_form_id_default:array": null, "shift_checkin_form_id_default": null, "shift_checkin_form_id_default:value": null, "shift_checkin_form_id_default:array": null, "shift_checkout_form_id_default": null, "shift_checkout_form_id_default:value": null, "shift_checkout_form_id_default:array": null, "shift_feedback_form_id_default": null, "shift_feedback_form_id_default:value": null, "shift_feedback_form_id_default:array": null, "shift_precheckin_form_id_default": null, "shift_precheckin_form_id_default:value": null, "shift_precheckin_form_id_default:array": null, "shift_withdraw_form_id_default": null, "shift_withdraw_form_id_default:value": null, "shift_withdraw_form_id_default:array": null, "start_timestamp": "Sep 17, 2026, 5:00 AM", "start_timestamp__date": "Sep 17, 2026", "start_timestamp__time": "5:00 AM", "start_timestamp__offset": " (+00:00 UTC)", "start_timestamp__offset_minutes": 0, "start_timestamp__dayofweek": "Thursday", "status": "Published", "status:value": "published", "status:array": "Published", "tags": null, "tags:value": null, "tags:array": null, "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "visibility_hide_groups": "", "visibility_show_groups": "", "visibility_show_roleoffer": "", "full_name": "Community Festival", "event_type_name": "ratione laborum dolor", "grid_list_image": null, "is_eoi_demand_met": false, "has_payrun": false, "min_shifts": 0, "post_event_feedback_form_completed_at": null, "expression_of_interest_form_completed_at": null, "expression_of_interest_form_cancelled_at": null, "account_name": "Example Organisation" }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "apply": true, "cancel": true, "can_publish": true }, "attributes": {} } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Event Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_template_id": { "type": "integer", "description": "The template to build the event from. Its values are applied over whatever else you send. Send `no_template` to start from nothing instead. Where the account has templates configured, one of the two is expected.", "examples": [ 1 ] }, "name": { "type": "string", "description": "What the event is called. Shown to everyone who can see the event.", "examples": [ "Community Festival" ] }, "event_type_id": { "type": "integer", "description": "Which of the account's event types this is. Defaults to the account's first type when left out.", "examples": [ 11 ] }, "description": { "type": "string", "description": "The event's description, as HTML. Shown on the event's page in the portal.", "examples": [ "

A weekend of community events across the city.

" ] }, "timezone": { "type": "string", "description": "The timezone every timestamp on the event is given in, as an IANA name such as `Australia/Melbourne`. Defaults to the account's timezone.", "examples": [ "UTC" ] }, "start_timestamp": { "type": "string", "description": "When the event starts, as `YYYY-MM-DD HH:MM:SS` in the event's timezone. Required when the event is not ongoing. Cleared if you mark the event ongoing.", "examples": [ "2026-09-17T05:00:00.000000Z" ] }, "end_timestamp": { "type": "string", "description": "When the event ends, as `YYYY-MM-DD HH:MM:SS` in the event's timezone. Defaults to the start when the event is not ongoing. Cleared if you mark the event ongoing.", "examples": [ "2026-10-01T05:00:00.000000Z" ] }, "is_virtual": { "type": "boolean", "description": "Whether the event has no physical location. A virtual event needs neither an address nor a venue.", "examples": [ 0 ] }, "shift_status_default": { "type": "integer", "description": "The status a new application to a shift on this event starts in. Defaults to the account's.", "examples": [ 2 ] }, "shift_confirmed_status_default": { "type": "integer", "description": "The status applied when someone confirms their place on a shift. Defaults to the account's.", "examples": [ 3 ] }, "shift_rejected_status_default": { "type": "integer", "description": "The status applied when someone is turned down for a shift. Defaults to the account's.", "examples": [ 6 ] }, "shift_can_withdraw_default": { "type": "boolean", "description": "Whether people may withdraw from this event's shifts.", "examples": [ 1 ] }, "shift_can_confirm_default": { "type": "boolean", "description": "Whether people are asked to confirm their place on this event's shifts.", "examples": [ 1 ] }, "shift_can_withdraw_limit": { "type": "integer", "description": "How long before a shift starts withdrawing stops being allowed, in seconds.", "examples": [ 0 ] }, "shift_can_confirm_limit": { "type": "integer", "description": "How long before a shift starts confirming stops being allowed, in seconds.", "examples": [ 0 ] }, "shift_checked_in_status_default": { "type": "integer", "description": "The status applied when someone checks in to a shift. Defaults to the account's.", "examples": [ 4 ] }, "shift_checked_out_status_default": { "type": "integer", "description": "The status applied when someone checks out of a shift. Defaults to the account's.", "examples": [ 4 ] }, "apps_open_timestamp": { "type": "string", "description": "When applications open, as `YYYY-MM-DD HH:MM:SS` in the event's timezone. Leave empty for applications that are open from the start.", "examples": [ "2026-05-30T05:00:00.000000Z" ] }, "apps_close_timestamp": { "type": "string", "description": "When applications close, as `YYYY-MM-DD HH:MM:SS` in the event's timezone. Must be after `apps_open_timestamp`.", "examples": [ null ] }, "max_shift_apps_per_user": { "type": "integer", "description": "The most shifts on this event one person may hold. `0` means no limit.", "examples": [ 0 ] }, "min_shift_apps_per_user": { "type": "integer", "description": "The fewest shifts on this event one person is expected to hold. `0` means no minimum.", "examples": [ 0 ] }, "min_shift_apps_per_shift_type": { "type": "object", "description": "Per-shift-type minimums, as an object keyed by shift type id.", "properties": {}, "examples": [ "{}" ] }, "max_shift_apps_per_shift_type": { "type": "object", "description": "Per-shift-type ceilings, as an object keyed by shift type id.", "properties": {}, "examples": [ "{}" ] }, "gap_between_shifts": { "type": "integer", "description": "The rest required between two shifts on this event, in seconds. `0` means none.", "examples": [ 0 ] }, "role_offer_address": { "type": "boolean", "description": "Whether the event takes its location from the role offer people applied through rather than from its own address.", "examples": [ 0 ] }, "status": { "type": "string", "description": "Whether the event is visible to people who can apply: `published`, `unpublished`, `auto_publish`, `submit_for_approval` or `rejected`. New events start unpublished.", "examples": [ "published" ] }, "parent_id": { "type": "integer", "description": "The id of the event this one sits beneath, for accounts that group events into a parent and its sub-events.", "examples": [ 1 ] }, "address": { "type": "object", "description": "Where the event takes place. Required unless the event is virtual or is held at a venue.", "properties": {}, "examples": [ { "iso": "AUS", "region_code": "VIC", "coordinates": { "latitude": "-37.814200", "longitude": "144.963200" }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "MELBOURNE", "postcode": "3000", "region": "VIC", "country": "AU", "latitude": "-37.814200", "longitude": "144.963200" } ] }, "headcount_location_venue_id": { "type": "integer", "description": "The venue the event is held at, instead of an address of its own.", "examples": [ 1 ] }, "headcount_functional_area_job_title_id": { "type": "integer", "description": "The job title this event's work is counted against for workforce planning.", "examples": [ 1 ] }, "certificate_id": { "type": "integer", "description": "The certificate awarded for taking part in this event.", "examples": [ 1 ] }, "visibility_show_groups": { "type": "array", "description": "Restrict the event to these groups, as a list of group ids. An empty list shows it to everyone.", "items": { "type": "integer" }, "examples": [ [] ] }, "visibility_hide_groups": { "type": "array", "description": "Hide the event from these groups, as a list of group ids.", "items": { "type": "integer" }, "examples": [ [] ] }, "visibility_show_roleoffer": { "type": "array", "description": "Restrict the event to people who came through these role offers, as a list of role offer ids.", "items": { "type": "integer" }, "examples": [ [] ] }, "shift_application_form_id_default": { "type": "integer", "description": "The form filled in when applying for one of this event's shifts.", "examples": [ 1 ] }, "shift_precheckin_form_id_default": { "type": "integer", "description": "The form filled in before checking in to one of this event's shifts.", "examples": [ 1 ] }, "shift_checkin_form_id_default": { "type": "integer", "description": "The form filled in at check-in.", "examples": [ 1 ] }, "shift_attended_form_id_default": { "type": "integer", "description": "The form filled in once attendance is recorded.", "examples": [ 1 ] }, "shift_checkout_form_id_default": { "type": "integer", "description": "The form filled in at check-out.", "examples": [ 1 ] }, "shift_feedback_form_id_default": { "type": "integer", "description": "The feedback form offered after one of this event's shifts.", "examples": [ 1 ] }, "shift_leader_feedback_form_id_default": { "type": "integer", "description": "The feedback form a shift leader is asked to fill in.", "examples": [ 1 ] }, "shift_precheckin_open_default": { "type": "integer", "description": "How long before a shift starts its pre-check-in form becomes available, in seconds.", "examples": [ 0 ] }, "max_group_demand_default": { "type": "integer", "description": "The most places a group leader may reserve on one of this event's shifts.", "examples": [ 1 ] }, "group_booking_ttl_default": { "type": "integer", "description": "How long a group leader's reserved places are held before they are released, in seconds.", "examples": [ 1 ] }, "geofence_checkin_limit_default": { "type": "integer", "description": "How close to the shift's location someone must be to check in, in metres. Empty means no limit.", "examples": [ 1 ] }, "self_checkin": { "type": "boolean", "description": "Whether people may check themselves in to this event's shifts.", "examples": [ 0 ] }, "self_checkin_open": { "type": "integer", "description": "How long before a shift starts self check-in opens, in seconds.", "examples": [ 1800 ] }, "self_checkin_close": { "type": "integer", "description": "How long after a shift starts self check-in closes, in seconds.", "examples": [ 1800 ] }, "self_checkout_close": { "type": "integer", "description": "How long after a shift ends self check-out closes, in seconds.", "examples": [ 1800 ] }, "checkin_close_default": { "type": "integer", "description": "How long after a shift ends check-in closes, in seconds.", "examples": [ 0 ] }, "checkin_visible_attributes": { "type": "array", "description": "Which fields are shown on the check-in page, as a list of `.` names such as `user.first_name`.", "items": { "type": "string" }, "examples": [ [] ] }, "shift_filter_attributes": { "type": "array", "description": "Which attributes people may filter this event's shifts by, as a list of attribute ids.", "items": { "type": "integer" }, "examples": [ [] ] }, "leader_shift_filter_attributes": { "type": "array", "description": "Which attributes a shift leader may filter by, as a list of attribute ids.", "items": { "type": "integer" }, "examples": [ [] ] }, "post_feedback": { "type": "string", "description": "The message shown once the post-event feedback form is available, as HTML.", "examples": [ "" ] }, "post_feedback_publish_at": { "type": "string", "description": "When the post-event feedback form becomes available, as `YYYY-MM-DD HH:MM:SS`.", "examples": [ null ] }, "training_ids": { "type": "array", "description": "The training people must have completed before they can apply, as a list of training ids.", "items": { "type": "integer" }, "examples": [ [] ] }, "banner_image": { "type": "string", "description": "The event's banner image. Send the URL of an image already uploaded through Rosterfy, or the image itself as `multipart/form-data`. A URL on any other host is rejected.", "examples": [ null ] }, "grid_image": { "type": "string", "description": "The image shown for the event in listings. Same accepted values as `banner_image`.", "examples": [ null ] }, "mobile_banner_image": { "type": "string", "description": "The banner image used on smaller screens. Same accepted values as `banner_image`.", "examples": [ null ] }, "minimum_dob": { "type": "string", "description": "The latest date of birth allowed, as `YYYY-MM-DD`. Cannot be combined with `minimum_age`.", "examples": [ null ] }, "minimum_age": { "type": "string", "description": "The youngest age allowed, as `years:months`, for example `16:0`. Cannot be combined with `minimum_dob`.", "examples": [ null ] }, "maximum_dob": { "type": "string", "description": "The earliest date of birth allowed, as `YYYY-MM-DD`. Cannot be combined with `maximum_age`.", "examples": [ null ] }, "maximum_age": { "type": "string", "description": "The oldest age allowed, as `years:months`. Cannot be combined with `maximum_dob`.", "examples": [ null ] }, "public": { "type": "boolean", "description": "Whether the event is visible to people who are not signed in, on accounts that allow public browsing.", "examples": [ 0 ] }, "public_shift": { "type": "boolean", "description": "Whether this event's shifts are visible to people who are not signed in.", "examples": [ 0 ] }, "public_shift_default": { "type": "boolean", "description": "Whether a newly created shift on this event is public by default.", "examples": [ 0 ] }, "token": { "type": "string", "description": "The event's public reference, the last part of its `rrn`. Generated when the event is created; there is rarely a reason to set your own.", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] }, "expression_of_interest": { "type": "boolean", "description": "Whether people may register interest in the event without applying for a specific shift.", "examples": [ 0 ] }, "expression_of_interest_form": { "type": "integer", "description": "The form filled in when registering interest.", "examples": [ 1 ] }, "shift_enable_waitlist_default": { "type": "boolean", "description": "Whether a full shift on this event takes a waitlist.", "examples": [ 0 ] }, "max_waitlist": { "type": "integer", "description": "How many people a shift's waitlist holds.", "examples": [ 0 ] }, "allow_user_activities": { "type": "boolean", "description": "Whether people may log their own activity against this event.", "examples": [ 0 ] }, "user_activity_form_id": { "type": "integer", "description": "The form used to log that activity.", "examples": [ 1 ] }, "approval_status": { "type": "string", "description": "Where the event sits in the account's approval process, when the account requires events to be approved.", "examples": [ "approved" ] }, "approval_reason": { "type": "string", "description": "Free text explaining the approval decision.", "examples": [ null ] }, "is_ongoing": { "type": "boolean", "description": "Whether the event runs indefinitely rather than between two dates. Setting it clears the start and end.", "examples": [ 0 ] }, "sort_order": { "type": "integer", "description": "Where the event sits when events are ordered manually. Lower comes first.", "examples": [ 0 ] }, "custom_*": { "type": "string", "description": "A custom attribute, named by its code - custom_shirt_size, for example. The value follows the attribute's own type, so it may be a string, a number, a boolean or a list. See the custom attributes documentation.", "examples": [ null ] } }, "required": [ "name", "description" ] } } } } } }, "/api/v2/event/{id}": { "get": { "summary": "Read an event", "operationId": "readAnEvent", "description": "Returns one event: when and where it runs, when applications open and close, who\nmay see it, and the defaults every shift beneath it inherits - the statuses an\napplication moves through, the forms it collects, the check-in window and the\nlimits on how many shifts one person may hold.\n\nThe `nice` block repeats the same values rendered for display - dates in the\nevent's timezone, ids resolved to the names behind them - so a listing can be\nshown without resolving each id yourself.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 21476343 ] }, "parent_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_template_id": { "type": [ "string", "null" ], "examples": [ null ] }, "path": { "type": "string", "examples": [ "21476343" ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "event_type_id": { "type": "integer", "examples": [ 11 ] }, "journey_id": { "type": [ "string", "null" ], "examples": [ null ] }, "timezone": { "type": "string", "examples": [ "UTC" ] }, "start_timestamp": { "type": "string", "examples": [ "2026-09-17T05:00:00.000000Z" ] }, "end_timestamp": { "type": "string", "examples": [ "2026-10-01T05:00:00.000000Z" ] }, "is_ongoing": { "type": "integer", "examples": [ 0 ] }, "apps_open_timestamp": { "type": "string", "examples": [ "2026-05-30T05:00:00.000000Z" ] }, "apps_close_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_functional_area_job_title_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_status_default": { "type": "integer", "examples": [ 2 ] }, "max_shift_apps_per_user": { "type": "integer", "examples": [ 0 ] }, "min_shift_apps_per_user": { "type": "integer", "examples": [ 0 ] }, "min_shift_apps_per_shift_type": { "type": [ "string", "null" ], "examples": [ null ] }, "max_shift_apps_per_shift_type": { "type": [ "string", "null" ], "examples": [ null ] }, "gap_between_shifts": { "type": "integer", "examples": [ 0 ] }, "shift_confirmed_status_default": { "type": "integer", "examples": [ 3 ] }, "shift_rejected_status_default": { "type": "integer", "examples": [ 6 ] }, "shift_can_withdraw_default": { "type": "integer", "examples": [ 1 ] }, "shift_can_confirm_default": { "type": "integer", "examples": [ 1 ] }, "shift_can_confirm_limit": { "type": "integer", "examples": [ 0 ] }, "shift_can_withdraw_limit": { "type": "integer", "examples": [ 0 ] }, "shift_checked_in_status_default": { "type": "integer", "examples": [ 4 ] }, "shift_checked_out_status_default": { "type": "integer", "examples": [ 4 ] }, "certificate_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_leader_feedback_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_feedback_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_default_journey_complete_status": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_default_journey_id": { "type": [ "string", "null" ], "examples": [ null ] }, "allow_user_activities": { "type": "integer", "examples": [ 0 ] }, "user_activity_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "training_ids": { "type": [ "string", "null" ], "examples": [ null ] }, "banner_image": { "type": [ "string", "null" ], "examples": [ null ] }, "grid_image": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "visibility_show_groups": { "type": "array", "examples": [ [] ] }, "visibility_hide_groups": { "type": "array", "examples": [ [] ] }, "visibility_show_roleoffer": { "type": "array", "examples": [ [] ] }, "role_offer_address": { "type": "integer", "examples": [ 0 ] }, "checkin_visible_attributes": { "type": "array", "examples": [ [] ] }, "shift_filter_attributes": { "type": [ "string", "null" ], "examples": [ null ] }, "leader_shift_filter_attributes": { "type": [ "string", "null" ], "examples": [ null ] }, "self_checkin": { "type": "integer", "examples": [ 0 ] }, "self_checkin_open": { "type": "integer", "examples": [ 1800 ] }, "self_checkin_close": { "type": "integer", "examples": [ 1800 ] }, "self_checkout_close": { "type": "integer", "examples": [ 1800 ] }, "checkin_close_default": { "type": "integer", "examples": [ 0 ] }, "shift_precheckin_open_default": { "type": "integer", "examples": [ 0 ] }, "shift_enable_waitlist_default": { "type": "integer", "examples": [ 0 ] }, "geofence_checkin_limit_default": { "type": [ "string", "null" ], "examples": [ null ] }, "max_waitlist": { "type": "integer", "examples": [ 0 ] }, "group_booking_ttl_default": { "type": [ "string", "null" ], "examples": [ null ] }, "max_group_demand_default": { "type": [ "string", "null" ], "examples": [ null ] }, "max_group_size": { "type": [ "string", "null" ], "examples": [ null ] }, "reserved_expiry": { "type": [ "string", "null" ], "examples": [ null ] }, "post_feedback_form": { "type": [ "string", "null" ], "examples": [ null ] }, "post_feedback_publish_at": { "type": [ "string", "null" ], "examples": [ null ] }, "expression_of_interest": { "type": "integer", "examples": [ 0 ] }, "journey_complete_status": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_apply_status": { "type": [ "string", "null" ], "examples": [ null ] }, "expression_of_interest_form": { "type": [ "string", "null" ], "examples": [ null ] }, "cancel_expression_of_interest_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "eoi_demand": { "type": "integer", "examples": [ 0 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "is_virtual": { "type": "integer", "examples": [ 0 ] }, "status": { "type": "string", "examples": [ "published" ] }, "approval_status": { "type": "string", "examples": [ "approved" ] }, "approval_reason": { "type": [ "string", "null" ], "examples": [ null ] }, "promoted": { "type": "integer", "examples": [ 0 ] }, "public": { "type": "integer", "examples": [ 0 ] }, "is_cancelled": { "type": "integer", "examples": [ 0 ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "public_shift": { "type": "integer", "examples": [ 0 ] }, "public_shift_default": { "type": "integer", "examples": [ 0 ] }, "token": { "type": "string", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] }, "certificates_awarded": { "type": "integer", "examples": [ 0 ] }, "created_by": { "type": [ "string", "null" ], "examples": [ null ] }, "updated_by": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:43.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:43.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "description": { "type": "string", "examples": [ "

A weekend of community events across the city.

" ] }, "name": { "type": "string", "examples": [ "Community Festival" ] }, "post_feedback": { "type": "string", "examples": [ "" ] }, "tags": { "type": [ "string", "null" ], "examples": [ null ] }, "address": { "type": "object", "properties": { "iso": { "type": "string", "examples": [ "AUS" ] }, "region_code": { "type": "string", "examples": [ "VIC" ] }, "coordinates": { "type": "object", "properties": { "latitude": { "type": "string", "examples": [ "-37.814200" ] }, "longitude": { "type": "string", "examples": [ "144.963200" ] } } }, "street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "city": { "type": "string", "examples": [ "MELBOURNE" ] }, "postcode": { "type": "string", "examples": [ "3000" ] }, "region": { "type": "string", "examples": [ "VIC" ] }, "country": { "type": "string", "examples": [ "AU" ] }, "latitude": { "type": "string", "examples": [ "-37.814200" ] }, "longitude": { "type": "string", "examples": [ "144.963200" ] } } } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:example:20101:event:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] }, "address": { "type": "string", "examples": [ "1 Example Street\nMELBOURNE\nVictoria\nAustralia\n3000" ] }, "address_oneline": { "type": "string", "examples": [ "1 Example Street, MELBOURNE, Victoria, Australia, 3000" ] }, "address.country": { "type": "string", "examples": [ "Australia" ] }, "address.country:raw": { "type": "string", "examples": [ "AUS" ] }, "address.city": { "type": "string", "examples": [ "MELBOURNE" ] }, "address.region": { "type": "string", "examples": [ "Victoria" ] }, "address.region:raw": { "type": "string", "examples": [ "VIC" ] }, "address.postcode": { "type": "string", "examples": [ "3000" ] }, "address.street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "address.street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "address.street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "address.latitude": { "type": "string", "examples": [ "-37.814200" ] }, "address.longitude": { "type": "string", "examples": [ "144.963200" ] }, "allow_user_activities": { "type": "string", "examples": [ "No" ] }, "approval_status": { "type": "string", "examples": [ "Approved" ] }, "approval_status:value": { "type": "string", "examples": [ "approved" ] }, "approval_status:array": { "type": "string", "examples": [ "Approved" ] }, "apps_open_timestamp": { "type": "string", "examples": [ "May 30, 2026, 5:00 AM" ] }, "apps_open_timestamp__date": { "type": "string", "examples": [ "May 30, 2026" ] }, "apps_open_timestamp__time": { "type": "string", "examples": [ "5:00 AM" ] }, "apps_open_timestamp__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "apps_open_timestamp__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "apps_open_timestamp__dayofweek": { "type": "string", "examples": [ "Saturday" ] }, "cancel_expression_of_interest_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "cancel_expression_of_interest_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "cancel_expression_of_interest_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "end_timestamp": { "type": "string", "examples": [ "Oct 1, 2026, 5:00 AM" ] }, "end_timestamp__date": { "type": "string", "examples": [ "Oct 1, 2026" ] }, "end_timestamp__time": { "type": "string", "examples": [ "5:00 AM" ] }, "end_timestamp__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "end_timestamp__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "end_timestamp__dayofweek": { "type": "string", "examples": [ "Thursday" ] }, "event_template_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_template_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "event_template_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "event_type_id": { "type": "string", "examples": [ "ratione laborum dolor" ] }, "event_type_id:value": { "type": "integer", "examples": [ 11 ] }, "event_type_id:array": { "type": "string", "examples": [ "ratione laborum dolor" ] }, "expression_of_interest": { "type": "string", "examples": [ "No" ] }, "headcount_location_venue_id": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "is_ongoing": { "type": "string", "examples": [ "No" ] }, "is_virtual": { "type": "string", "examples": [ "No" ] }, "name": { "type": "string", "examples": [ "Community Festival" ] }, "promoted": { "type": "string", "examples": [ "No" ] }, "role_offer_address": { "type": "string", "examples": [ "No" ] }, "self_checkin": { "type": "string", "examples": [ "No" ] }, "shift_application_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_feedback_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_feedback_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_feedback_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "start_timestamp": { "type": "string", "examples": [ "Sep 17, 2026, 5:00 AM" ] }, "start_timestamp__date": { "type": "string", "examples": [ "Sep 17, 2026" ] }, "start_timestamp__time": { "type": "string", "examples": [ "5:00 AM" ] }, "start_timestamp__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "start_timestamp__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "start_timestamp__dayofweek": { "type": "string", "examples": [ "Thursday" ] }, "status": { "type": "string", "examples": [ "Published" ] }, "status:value": { "type": "string", "examples": [ "published" ] }, "status:array": { "type": "string", "examples": [ "Published" ] }, "tags": { "type": [ "string", "null" ], "examples": [ null ] }, "tags:value": { "type": [ "string", "null" ], "examples": [ null ] }, "tags:array": { "type": [ "string", "null" ], "examples": [ null ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "visibility_hide_groups": { "type": "string", "examples": [ "" ] }, "visibility_show_groups": { "type": "string", "examples": [ "" ] }, "visibility_show_roleoffer": { "type": "string", "examples": [ "" ] }, "full_name": { "type": "string", "examples": [ "Community Festival" ] }, "event_type_name": { "type": "string", "examples": [ "ratione laborum dolor" ] }, "grid_list_image": { "type": [ "string", "null" ], "examples": [ null ] }, "is_eoi_demand_met": { "type": "boolean", "examples": [ false ] }, "has_payrun": { "type": "boolean", "examples": [ false ] }, "min_shifts": { "type": "integer", "examples": [ 0 ] }, "post_event_feedback_form_completed_at": { "type": [ "string", "null" ], "examples": [ null ] }, "expression_of_interest_form_completed_at": { "type": [ "string", "null" ], "examples": [ null ] }, "expression_of_interest_form_cancelled_at": { "type": [ "string", "null" ], "examples": [ null ] }, "account_name": { "type": "string", "examples": [ "Example Organisation" ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "apply": { "type": "boolean", "examples": [ true ] }, "cancel": { "type": "boolean", "examples": [ true ] }, "can_publish": { "type": "boolean", "examples": [ true ] } } }, "attributes": { "type": "object", "properties": {} } }, "examples": [ { "object": { "id": 21476343, "parent_id": null, "event_template_id": null, "path": "21476343", "account_id": 20101, "event_type_id": 11, "journey_id": null, "timezone": "UTC", "start_timestamp": "2026-09-17T05:00:00.000000Z", "end_timestamp": "2026-10-01T05:00:00.000000Z", "is_ongoing": 0, "apps_open_timestamp": "2026-05-30T05:00:00.000000Z", "apps_close_timestamp": null, "headcount_location_venue_id": null, "headcount_functional_area_job_title_id": null, "shift_status_default": 2, "max_shift_apps_per_user": 0, "min_shift_apps_per_user": 0, "min_shift_apps_per_shift_type": null, "max_shift_apps_per_shift_type": null, "gap_between_shifts": 0, "shift_confirmed_status_default": 3, "shift_rejected_status_default": 6, "shift_can_withdraw_default": 1, "shift_can_confirm_default": 1, "shift_can_confirm_limit": 0, "shift_can_withdraw_limit": 0, "shift_checked_in_status_default": 4, "shift_checked_out_status_default": 4, "certificate_id": null, "shift_application_form_id_default": null, "shift_withdraw_form_id_default": null, "shift_checkin_form_id_default": null, "shift_attended_form_id_default": null, "shift_checkout_form_id_default": null, "shift_leader_feedback_form_id_default": null, "shift_feedback_form_id_default": null, "shift_precheckin_form_id_default": null, "shift_default_journey_complete_status": null, "shift_default_journey_id": null, "allow_user_activities": 0, "user_activity_form_id": null, "training_ids": null, "banner_image": null, "grid_image": null, "minimum_dob": null, "minimum_age": null, "maximum_dob": null, "maximum_age": null, "visibility_show_groups": [], "visibility_hide_groups": [], "visibility_show_roleoffer": [], "role_offer_address": 0, "checkin_visible_attributes": [], "shift_filter_attributes": null, "leader_shift_filter_attributes": null, "self_checkin": 0, "self_checkin_open": 1800, "self_checkin_close": 1800, "self_checkout_close": 1800, "checkin_close_default": 0, "shift_precheckin_open_default": 0, "shift_enable_waitlist_default": 0, "geofence_checkin_limit_default": null, "max_waitlist": 0, "group_booking_ttl_default": null, "max_group_demand_default": null, "max_group_size": null, "reserved_expiry": null, "post_feedback_form": null, "post_feedback_publish_at": null, "expression_of_interest": 0, "journey_complete_status": null, "journey_apply_status": null, "expression_of_interest_form": null, "cancel_expression_of_interest_form_id": null, "eoi_demand": 0, "sort_order": 0, "is_virtual": 0, "status": "published", "approval_status": "approved", "approval_reason": null, "promoted": 0, "public": 0, "is_cancelled": 0, "is_archived": 0, "public_shift": 0, "public_shift_default": 0, "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "certificates_awarded": 0, "created_by": null, "updated_by": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:36:43.000000Z", "updated_at": "2026-06-09T05:36:43.000000Z", "deleted_by": null, "description": "

A weekend of community events across the city.

", "name": "Community Festival", "post_feedback": "", "tags": null, "address": { "iso": "AUS", "region_code": "VIC", "coordinates": { "latitude": "-37.814200", "longitude": "144.963200" }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "MELBOURNE", "postcode": "3000", "region": "VIC", "country": "AU", "latitude": "-37.814200", "longitude": "144.963200" } }, "nice": { "rrn": "rrn:example:20101:event:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "address": "1 Example Street\nMELBOURNE\nVictoria\nAustralia\n3000", "address_oneline": "1 Example Street, MELBOURNE, Victoria, Australia, 3000", "address.country": "Australia", "address.country:raw": "AUS", "address.city": "MELBOURNE", "address.region": "Victoria", "address.region:raw": "VIC", "address.postcode": "3000", "address.street_address_1": "1 Example Street", "address.street_address_2": null, "address.street_address_3": null, "address.latitude": "-37.814200", "address.longitude": "144.963200", "allow_user_activities": "No", "approval_status": "Approved", "approval_status:value": "approved", "approval_status:array": "Approved", "apps_open_timestamp": "May 30, 2026, 5:00 AM", "apps_open_timestamp__date": "May 30, 2026", "apps_open_timestamp__time": "5:00 AM", "apps_open_timestamp__offset": " (+00:00 UTC)", "apps_open_timestamp__offset_minutes": 0, "apps_open_timestamp__dayofweek": "Saturday", "cancel_expression_of_interest_form_id": null, "cancel_expression_of_interest_form_id:value": null, "cancel_expression_of_interest_form_id:array": null, "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "end_timestamp": "Oct 1, 2026, 5:00 AM", "end_timestamp__date": "Oct 1, 2026", "end_timestamp__time": "5:00 AM", "end_timestamp__offset": " (+00:00 UTC)", "end_timestamp__offset_minutes": 0, "end_timestamp__dayofweek": "Thursday", "event_template_id": null, "event_template_id:value": null, "event_template_id:array": null, "event_type_id": "ratione laborum dolor", "event_type_id:value": 11, "event_type_id:array": "ratione laborum dolor", "expression_of_interest": "No", "headcount_location_venue_id": null, "headcount_location_venue_id:value": null, "headcount_location_venue_id:array": null, "is_ongoing": "No", "is_virtual": "No", "name": "Community Festival", "promoted": "No", "role_offer_address": "No", "self_checkin": "No", "shift_application_form_id_default": null, "shift_application_form_id_default:value": null, "shift_application_form_id_default:array": null, "shift_attended_form_id_default": null, "shift_attended_form_id_default:value": null, "shift_attended_form_id_default:array": null, "shift_checkin_form_id_default": null, "shift_checkin_form_id_default:value": null, "shift_checkin_form_id_default:array": null, "shift_checkout_form_id_default": null, "shift_checkout_form_id_default:value": null, "shift_checkout_form_id_default:array": null, "shift_feedback_form_id_default": null, "shift_feedback_form_id_default:value": null, "shift_feedback_form_id_default:array": null, "shift_precheckin_form_id_default": null, "shift_precheckin_form_id_default:value": null, "shift_precheckin_form_id_default:array": null, "shift_withdraw_form_id_default": null, "shift_withdraw_form_id_default:value": null, "shift_withdraw_form_id_default:array": null, "start_timestamp": "Sep 17, 2026, 5:00 AM", "start_timestamp__date": "Sep 17, 2026", "start_timestamp__time": "5:00 AM", "start_timestamp__offset": " (+00:00 UTC)", "start_timestamp__offset_minutes": 0, "start_timestamp__dayofweek": "Thursday", "status": "Published", "status:value": "published", "status:array": "Published", "tags": null, "tags:value": null, "tags:array": null, "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "visibility_hide_groups": "", "visibility_show_groups": "", "visibility_show_roleoffer": "", "full_name": "Community Festival", "event_type_name": "ratione laborum dolor", "grid_list_image": null, "is_eoi_demand_met": false, "has_payrun": false, "min_shifts": 0, "post_event_feedback_form_completed_at": null, "expression_of_interest_form_completed_at": null, "expression_of_interest_form_cancelled_at": null, "account_name": "Example Organisation" }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "apply": true, "cancel": true, "can_publish": true }, "attributes": {} } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Event Module" ] }, "put": { "summary": "Update an event", "operationId": "updateAnEvent", "description": "Updates an event and returns it, the same shape as reading it. Every field is\noptional; a request with an empty body succeeds and changes nothing.\n\n**Sending a date onto an ongoing event ends its ongoing state.** A start or end\ntimestamp on an event marked ongoing clears that flag, because an event cannot be\nboth. Marking it ongoing does the reverse and clears both timestamps.\n\n**Where the event was built from a template, the template's fields are ignored**\nunless you are allowed to override them - they are dropped from the request rather\nthan rejected, so the call still succeeds and those fields keep their old values.\nThe same is true of any field locked on the event itself.\n\nAn account that requires events to be approved refuses changes to anything other\nthan the status and the approval fields once the event has been approved, and says\nso per field.\n\nThe account's own configured attributes are accepted as `custom_*` fields.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 21476343 ] }, "parent_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_template_id": { "type": [ "string", "null" ], "examples": [ null ] }, "path": { "type": "string", "examples": [ "21476343" ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "event_type_id": { "type": "integer", "examples": [ 11 ] }, "journey_id": { "type": [ "string", "null" ], "examples": [ null ] }, "timezone": { "type": "string", "examples": [ "UTC" ] }, "start_timestamp": { "type": "string", "examples": [ "2026-09-17T05:00:00.000000Z" ] }, "end_timestamp": { "type": "string", "examples": [ "2026-10-01T05:00:00.000000Z" ] }, "is_ongoing": { "type": "integer", "examples": [ 0 ] }, "apps_open_timestamp": { "type": "string", "examples": [ "2026-05-30T05:00:00.000000Z" ] }, "apps_close_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_functional_area_job_title_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_status_default": { "type": "integer", "examples": [ 2 ] }, "max_shift_apps_per_user": { "type": "integer", "examples": [ 0 ] }, "min_shift_apps_per_user": { "type": "integer", "examples": [ 0 ] }, "min_shift_apps_per_shift_type": { "type": [ "string", "null" ], "examples": [ null ] }, "max_shift_apps_per_shift_type": { "type": [ "string", "null" ], "examples": [ null ] }, "gap_between_shifts": { "type": "integer", "examples": [ 0 ] }, "shift_confirmed_status_default": { "type": "integer", "examples": [ 3 ] }, "shift_rejected_status_default": { "type": "integer", "examples": [ 6 ] }, "shift_can_withdraw_default": { "type": "integer", "examples": [ 1 ] }, "shift_can_confirm_default": { "type": "integer", "examples": [ 1 ] }, "shift_can_confirm_limit": { "type": "integer", "examples": [ 0 ] }, "shift_can_withdraw_limit": { "type": "integer", "examples": [ 0 ] }, "shift_checked_in_status_default": { "type": "integer", "examples": [ 4 ] }, "shift_checked_out_status_default": { "type": "integer", "examples": [ 4 ] }, "certificate_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_leader_feedback_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_feedback_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_default_journey_complete_status": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_default_journey_id": { "type": [ "string", "null" ], "examples": [ null ] }, "allow_user_activities": { "type": "integer", "examples": [ 0 ] }, "user_activity_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "training_ids": { "type": [ "string", "null" ], "examples": [ null ] }, "banner_image": { "type": [ "string", "null" ], "examples": [ null ] }, "grid_image": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "visibility_show_groups": { "type": "array", "examples": [ [] ] }, "visibility_hide_groups": { "type": "array", "examples": [ [] ] }, "visibility_show_roleoffer": { "type": "array", "examples": [ [] ] }, "role_offer_address": { "type": "integer", "examples": [ 0 ] }, "checkin_visible_attributes": { "type": "array", "examples": [ [] ] }, "shift_filter_attributes": { "type": [ "string", "null" ], "examples": [ null ] }, "leader_shift_filter_attributes": { "type": [ "string", "null" ], "examples": [ null ] }, "self_checkin": { "type": "integer", "examples": [ 0 ] }, "self_checkin_open": { "type": "integer", "examples": [ 1800 ] }, "self_checkin_close": { "type": "integer", "examples": [ 1800 ] }, "self_checkout_close": { "type": "integer", "examples": [ 1800 ] }, "checkin_close_default": { "type": "integer", "examples": [ 0 ] }, "shift_precheckin_open_default": { "type": "integer", "examples": [ 0 ] }, "shift_enable_waitlist_default": { "type": "integer", "examples": [ 0 ] }, "geofence_checkin_limit_default": { "type": [ "string", "null" ], "examples": [ null ] }, "max_waitlist": { "type": "integer", "examples": [ 0 ] }, "group_booking_ttl_default": { "type": [ "string", "null" ], "examples": [ null ] }, "max_group_demand_default": { "type": [ "string", "null" ], "examples": [ null ] }, "max_group_size": { "type": [ "string", "null" ], "examples": [ null ] }, "reserved_expiry": { "type": [ "string", "null" ], "examples": [ null ] }, "post_feedback_form": { "type": [ "string", "null" ], "examples": [ null ] }, "post_feedback_publish_at": { "type": [ "string", "null" ], "examples": [ null ] }, "expression_of_interest": { "type": "integer", "examples": [ 0 ] }, "journey_complete_status": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_apply_status": { "type": [ "string", "null" ], "examples": [ null ] }, "expression_of_interest_form": { "type": [ "string", "null" ], "examples": [ null ] }, "cancel_expression_of_interest_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "eoi_demand": { "type": "integer", "examples": [ 0 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "is_virtual": { "type": "integer", "examples": [ 0 ] }, "status": { "type": "string", "examples": [ "published" ] }, "approval_status": { "type": "string", "examples": [ "approved" ] }, "approval_reason": { "type": [ "string", "null" ], "examples": [ null ] }, "promoted": { "type": "integer", "examples": [ 0 ] }, "public": { "type": "integer", "examples": [ 0 ] }, "is_cancelled": { "type": "integer", "examples": [ 0 ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "public_shift": { "type": "integer", "examples": [ 0 ] }, "public_shift_default": { "type": "integer", "examples": [ 0 ] }, "token": { "type": "string", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] }, "certificates_awarded": { "type": "integer", "examples": [ 0 ] }, "created_by": { "type": [ "string", "null" ], "examples": [ null ] }, "updated_by": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:43.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:43.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "description": { "type": "string", "examples": [ "

A weekend of community events across the city.

" ] }, "name": { "type": "string", "examples": [ "Community Festival" ] }, "post_feedback": { "type": "string", "examples": [ "" ] }, "tags": { "type": [ "string", "null" ], "examples": [ null ] }, "address": { "type": "object", "properties": { "iso": { "type": "string", "examples": [ "AUS" ] }, "region_code": { "type": "string", "examples": [ "VIC" ] }, "coordinates": { "type": "object", "properties": { "latitude": { "type": "string", "examples": [ "-37.814200" ] }, "longitude": { "type": "string", "examples": [ "144.963200" ] } } }, "street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "city": { "type": "string", "examples": [ "MELBOURNE" ] }, "postcode": { "type": "string", "examples": [ "3000" ] }, "region": { "type": "string", "examples": [ "VIC" ] }, "country": { "type": "string", "examples": [ "AU" ] }, "latitude": { "type": "string", "examples": [ "-37.814200" ] }, "longitude": { "type": "string", "examples": [ "144.963200" ] } } } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:example:20101:event:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] }, "address": { "type": "string", "examples": [ "1 Example Street\nMELBOURNE\nVictoria\nAustralia\n3000" ] }, "address_oneline": { "type": "string", "examples": [ "1 Example Street, MELBOURNE, Victoria, Australia, 3000" ] }, "address.country": { "type": "string", "examples": [ "Australia" ] }, "address.country:raw": { "type": "string", "examples": [ "AUS" ] }, "address.city": { "type": "string", "examples": [ "MELBOURNE" ] }, "address.region": { "type": "string", "examples": [ "Victoria" ] }, "address.region:raw": { "type": "string", "examples": [ "VIC" ] }, "address.postcode": { "type": "string", "examples": [ "3000" ] }, "address.street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "address.street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "address.street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "address.latitude": { "type": "string", "examples": [ "-37.814200" ] }, "address.longitude": { "type": "string", "examples": [ "144.963200" ] }, "allow_user_activities": { "type": "string", "examples": [ "No" ] }, "approval_status": { "type": "string", "examples": [ "Approved" ] }, "approval_status:value": { "type": "string", "examples": [ "approved" ] }, "approval_status:array": { "type": "string", "examples": [ "Approved" ] }, "apps_open_timestamp": { "type": "string", "examples": [ "May 30, 2026, 5:00 AM" ] }, "apps_open_timestamp__date": { "type": "string", "examples": [ "May 30, 2026" ] }, "apps_open_timestamp__time": { "type": "string", "examples": [ "5:00 AM" ] }, "apps_open_timestamp__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "apps_open_timestamp__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "apps_open_timestamp__dayofweek": { "type": "string", "examples": [ "Saturday" ] }, "cancel_expression_of_interest_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "cancel_expression_of_interest_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "cancel_expression_of_interest_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "end_timestamp": { "type": "string", "examples": [ "Oct 1, 2026, 5:00 AM" ] }, "end_timestamp__date": { "type": "string", "examples": [ "Oct 1, 2026" ] }, "end_timestamp__time": { "type": "string", "examples": [ "5:00 AM" ] }, "end_timestamp__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "end_timestamp__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "end_timestamp__dayofweek": { "type": "string", "examples": [ "Thursday" ] }, "event_template_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_template_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "event_template_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "event_type_id": { "type": "string", "examples": [ "ratione laborum dolor" ] }, "event_type_id:value": { "type": "integer", "examples": [ 11 ] }, "event_type_id:array": { "type": "string", "examples": [ "ratione laborum dolor" ] }, "expression_of_interest": { "type": "string", "examples": [ "No" ] }, "headcount_location_venue_id": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "is_ongoing": { "type": "string", "examples": [ "No" ] }, "is_virtual": { "type": "string", "examples": [ "No" ] }, "name": { "type": "string", "examples": [ "Community Festival" ] }, "promoted": { "type": "string", "examples": [ "No" ] }, "role_offer_address": { "type": "string", "examples": [ "No" ] }, "self_checkin": { "type": "string", "examples": [ "No" ] }, "shift_application_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_feedback_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_feedback_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_feedback_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id_default": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id_default:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id_default:array": { "type": [ "string", "null" ], "examples": [ null ] }, "start_timestamp": { "type": "string", "examples": [ "Sep 17, 2026, 5:00 AM" ] }, "start_timestamp__date": { "type": "string", "examples": [ "Sep 17, 2026" ] }, "start_timestamp__time": { "type": "string", "examples": [ "5:00 AM" ] }, "start_timestamp__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "start_timestamp__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "start_timestamp__dayofweek": { "type": "string", "examples": [ "Thursday" ] }, "status": { "type": "string", "examples": [ "Published" ] }, "status:value": { "type": "string", "examples": [ "published" ] }, "status:array": { "type": "string", "examples": [ "Published" ] }, "tags": { "type": [ "string", "null" ], "examples": [ null ] }, "tags:value": { "type": [ "string", "null" ], "examples": [ null ] }, "tags:array": { "type": [ "string", "null" ], "examples": [ null ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "visibility_hide_groups": { "type": "string", "examples": [ "" ] }, "visibility_show_groups": { "type": "string", "examples": [ "" ] }, "visibility_show_roleoffer": { "type": "string", "examples": [ "" ] }, "full_name": { "type": "string", "examples": [ "Community Festival" ] }, "event_type_name": { "type": "string", "examples": [ "ratione laborum dolor" ] }, "grid_list_image": { "type": [ "string", "null" ], "examples": [ null ] }, "is_eoi_demand_met": { "type": "boolean", "examples": [ false ] }, "has_payrun": { "type": "boolean", "examples": [ false ] }, "min_shifts": { "type": "integer", "examples": [ 0 ] }, "post_event_feedback_form_completed_at": { "type": [ "string", "null" ], "examples": [ null ] }, "expression_of_interest_form_completed_at": { "type": [ "string", "null" ], "examples": [ null ] }, "expression_of_interest_form_cancelled_at": { "type": [ "string", "null" ], "examples": [ null ] }, "account_name": { "type": "string", "examples": [ "Example Organisation" ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "apply": { "type": "boolean", "examples": [ true ] }, "cancel": { "type": "boolean", "examples": [ true ] }, "can_publish": { "type": "boolean", "examples": [ true ] } } }, "attributes": { "type": "object", "properties": {} } }, "examples": [ { "object": { "id": 21476343, "parent_id": null, "event_template_id": null, "path": "21476343", "account_id": 20101, "event_type_id": 11, "journey_id": null, "timezone": "UTC", "start_timestamp": "2026-09-17T05:00:00.000000Z", "end_timestamp": "2026-10-01T05:00:00.000000Z", "is_ongoing": 0, "apps_open_timestamp": "2026-05-30T05:00:00.000000Z", "apps_close_timestamp": null, "headcount_location_venue_id": null, "headcount_functional_area_job_title_id": null, "shift_status_default": 2, "max_shift_apps_per_user": 0, "min_shift_apps_per_user": 0, "min_shift_apps_per_shift_type": null, "max_shift_apps_per_shift_type": null, "gap_between_shifts": 0, "shift_confirmed_status_default": 3, "shift_rejected_status_default": 6, "shift_can_withdraw_default": 1, "shift_can_confirm_default": 1, "shift_can_confirm_limit": 0, "shift_can_withdraw_limit": 0, "shift_checked_in_status_default": 4, "shift_checked_out_status_default": 4, "certificate_id": null, "shift_application_form_id_default": null, "shift_withdraw_form_id_default": null, "shift_checkin_form_id_default": null, "shift_attended_form_id_default": null, "shift_checkout_form_id_default": null, "shift_leader_feedback_form_id_default": null, "shift_feedback_form_id_default": null, "shift_precheckin_form_id_default": null, "shift_default_journey_complete_status": null, "shift_default_journey_id": null, "allow_user_activities": 0, "user_activity_form_id": null, "training_ids": null, "banner_image": null, "grid_image": null, "minimum_dob": null, "minimum_age": null, "maximum_dob": null, "maximum_age": null, "visibility_show_groups": [], "visibility_hide_groups": [], "visibility_show_roleoffer": [], "role_offer_address": 0, "checkin_visible_attributes": [], "shift_filter_attributes": null, "leader_shift_filter_attributes": null, "self_checkin": 0, "self_checkin_open": 1800, "self_checkin_close": 1800, "self_checkout_close": 1800, "checkin_close_default": 0, "shift_precheckin_open_default": 0, "shift_enable_waitlist_default": 0, "geofence_checkin_limit_default": null, "max_waitlist": 0, "group_booking_ttl_default": null, "max_group_demand_default": null, "max_group_size": null, "reserved_expiry": null, "post_feedback_form": null, "post_feedback_publish_at": null, "expression_of_interest": 0, "journey_complete_status": null, "journey_apply_status": null, "expression_of_interest_form": null, "cancel_expression_of_interest_form_id": null, "eoi_demand": 0, "sort_order": 0, "is_virtual": 0, "status": "published", "approval_status": "approved", "approval_reason": null, "promoted": 0, "public": 0, "is_cancelled": 0, "is_archived": 0, "public_shift": 0, "public_shift_default": 0, "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "certificates_awarded": 0, "created_by": null, "updated_by": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:36:43.000000Z", "updated_at": "2026-06-09T05:36:43.000000Z", "deleted_by": null, "description": "

A weekend of community events across the city.

", "name": "Community Festival", "post_feedback": "", "tags": null, "address": { "iso": "AUS", "region_code": "VIC", "coordinates": { "latitude": "-37.814200", "longitude": "144.963200" }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "MELBOURNE", "postcode": "3000", "region": "VIC", "country": "AU", "latitude": "-37.814200", "longitude": "144.963200" } }, "nice": { "rrn": "rrn:example:20101:event:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "address": "1 Example Street\nMELBOURNE\nVictoria\nAustralia\n3000", "address_oneline": "1 Example Street, MELBOURNE, Victoria, Australia, 3000", "address.country": "Australia", "address.country:raw": "AUS", "address.city": "MELBOURNE", "address.region": "Victoria", "address.region:raw": "VIC", "address.postcode": "3000", "address.street_address_1": "1 Example Street", "address.street_address_2": null, "address.street_address_3": null, "address.latitude": "-37.814200", "address.longitude": "144.963200", "allow_user_activities": "No", "approval_status": "Approved", "approval_status:value": "approved", "approval_status:array": "Approved", "apps_open_timestamp": "May 30, 2026, 5:00 AM", "apps_open_timestamp__date": "May 30, 2026", "apps_open_timestamp__time": "5:00 AM", "apps_open_timestamp__offset": " (+00:00 UTC)", "apps_open_timestamp__offset_minutes": 0, "apps_open_timestamp__dayofweek": "Saturday", "cancel_expression_of_interest_form_id": null, "cancel_expression_of_interest_form_id:value": null, "cancel_expression_of_interest_form_id:array": null, "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "end_timestamp": "Oct 1, 2026, 5:00 AM", "end_timestamp__date": "Oct 1, 2026", "end_timestamp__time": "5:00 AM", "end_timestamp__offset": " (+00:00 UTC)", "end_timestamp__offset_minutes": 0, "end_timestamp__dayofweek": "Thursday", "event_template_id": null, "event_template_id:value": null, "event_template_id:array": null, "event_type_id": "ratione laborum dolor", "event_type_id:value": 11, "event_type_id:array": "ratione laborum dolor", "expression_of_interest": "No", "headcount_location_venue_id": null, "headcount_location_venue_id:value": null, "headcount_location_venue_id:array": null, "is_ongoing": "No", "is_virtual": "No", "name": "Community Festival", "promoted": "No", "role_offer_address": "No", "self_checkin": "No", "shift_application_form_id_default": null, "shift_application_form_id_default:value": null, "shift_application_form_id_default:array": null, "shift_attended_form_id_default": null, "shift_attended_form_id_default:value": null, "shift_attended_form_id_default:array": null, "shift_checkin_form_id_default": null, "shift_checkin_form_id_default:value": null, "shift_checkin_form_id_default:array": null, "shift_checkout_form_id_default": null, "shift_checkout_form_id_default:value": null, "shift_checkout_form_id_default:array": null, "shift_feedback_form_id_default": null, "shift_feedback_form_id_default:value": null, "shift_feedback_form_id_default:array": null, "shift_precheckin_form_id_default": null, "shift_precheckin_form_id_default:value": null, "shift_precheckin_form_id_default:array": null, "shift_withdraw_form_id_default": null, "shift_withdraw_form_id_default:value": null, "shift_withdraw_form_id_default:array": null, "start_timestamp": "Sep 17, 2026, 5:00 AM", "start_timestamp__date": "Sep 17, 2026", "start_timestamp__time": "5:00 AM", "start_timestamp__offset": " (+00:00 UTC)", "start_timestamp__offset_minutes": 0, "start_timestamp__dayofweek": "Thursday", "status": "Published", "status:value": "published", "status:array": "Published", "tags": null, "tags:value": null, "tags:array": null, "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "visibility_hide_groups": "", "visibility_show_groups": "", "visibility_show_roleoffer": "", "full_name": "Community Festival", "event_type_name": "ratione laborum dolor", "grid_list_image": null, "is_eoi_demand_met": false, "has_payrun": false, "min_shifts": 0, "post_event_feedback_form_completed_at": null, "expression_of_interest_form_completed_at": null, "expression_of_interest_form_cancelled_at": null, "account_name": "Example Organisation" }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "apply": true, "cancel": true, "can_publish": true }, "attributes": {} } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Event Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_template_id": { "type": "integer", "description": "The template to build the event from. Its values are applied over whatever else you send. Send `no_template` to start from nothing instead. Where the account has templates configured, one of the two is expected.", "examples": [ 1 ] }, "name": { "type": "string", "description": "What the event is called. Shown to everyone who can see the event.", "examples": [ "Community Festival" ] }, "event_type_id": { "type": "integer", "description": "Which of the account's event types this is. Defaults to the account's first type when left out.", "examples": [ 11 ] }, "description": { "type": "string", "description": "The event's description, as HTML. Shown on the event's page in the portal.", "examples": [ "

A weekend of community events across the city.

" ] }, "timezone": { "type": "string", "description": "The timezone every timestamp on the event is given in, as an IANA name such as `Australia/Melbourne`. Defaults to the account's timezone.", "examples": [ "UTC" ] }, "start_timestamp": { "type": "string", "description": "When the event starts, as `YYYY-MM-DD HH:MM:SS` in the event's timezone. Required when the event is not ongoing. Cleared if you mark the event ongoing.", "examples": [ "2026-09-17T05:00:00.000000Z" ] }, "end_timestamp": { "type": "string", "description": "When the event ends, as `YYYY-MM-DD HH:MM:SS` in the event's timezone. Defaults to the start when the event is not ongoing. Cleared if you mark the event ongoing.", "examples": [ "2026-10-01T05:00:00.000000Z" ] }, "is_virtual": { "type": "boolean", "description": "Whether the event has no physical location. A virtual event needs neither an address nor a venue.", "examples": [ 0 ] }, "shift_status_default": { "type": "integer", "description": "The status a new application to a shift on this event starts in. Defaults to the account's.", "examples": [ 2 ] }, "shift_confirmed_status_default": { "type": "integer", "description": "The status applied when someone confirms their place on a shift. Defaults to the account's.", "examples": [ 3 ] }, "shift_rejected_status_default": { "type": "integer", "description": "The status applied when someone is turned down for a shift. Defaults to the account's.", "examples": [ 6 ] }, "shift_can_withdraw_default": { "type": "boolean", "description": "Whether people may withdraw from this event's shifts.", "examples": [ 1 ] }, "shift_can_confirm_default": { "type": "boolean", "description": "Whether people are asked to confirm their place on this event's shifts.", "examples": [ 1 ] }, "shift_can_withdraw_limit": { "type": "integer", "description": "How long before a shift starts withdrawing stops being allowed, in seconds.", "examples": [ 0 ] }, "shift_can_confirm_limit": { "type": "integer", "description": "How long before a shift starts confirming stops being allowed, in seconds.", "examples": [ 0 ] }, "shift_checked_in_status_default": { "type": "integer", "description": "The status applied when someone checks in to a shift. Defaults to the account's.", "examples": [ 4 ] }, "shift_checked_out_status_default": { "type": "integer", "description": "The status applied when someone checks out of a shift. Defaults to the account's.", "examples": [ 4 ] }, "apps_open_timestamp": { "type": "string", "description": "When applications open, as `YYYY-MM-DD HH:MM:SS` in the event's timezone. Leave empty for applications that are open from the start.", "examples": [ "2026-05-30T05:00:00.000000Z" ] }, "apps_close_timestamp": { "type": "string", "description": "When applications close, as `YYYY-MM-DD HH:MM:SS` in the event's timezone. Must be after `apps_open_timestamp`.", "examples": [ null ] }, "max_shift_apps_per_user": { "type": "integer", "description": "The most shifts on this event one person may hold. `0` means no limit.", "examples": [ 0 ] }, "min_shift_apps_per_user": { "type": "integer", "description": "The fewest shifts on this event one person is expected to hold. `0` means no minimum.", "examples": [ 0 ] }, "min_shift_apps_per_shift_type": { "type": "object", "description": "Per-shift-type minimums, as an object keyed by shift type id.", "properties": {}, "examples": [ "{}" ] }, "max_shift_apps_per_shift_type": { "type": "object", "description": "Per-shift-type ceilings, as an object keyed by shift type id.", "properties": {}, "examples": [ "{}" ] }, "gap_between_shifts": { "type": "integer", "description": "The rest required between two shifts on this event, in seconds. `0` means none.", "examples": [ 0 ] }, "role_offer_address": { "type": "boolean", "description": "Whether the event takes its location from the role offer people applied through rather than from its own address.", "examples": [ 0 ] }, "status": { "type": "string", "description": "Whether the event is visible to people who can apply: `published`, `unpublished`, `auto_publish`, `submit_for_approval` or `rejected`. New events start unpublished.", "examples": [ "published" ] }, "parent_id": { "type": "integer", "description": "The id of the event this one sits beneath, for accounts that group events into a parent and its sub-events.", "examples": [ 1 ] }, "address": { "type": "object", "description": "Where the event takes place. Required unless the event is virtual or is held at a venue.", "properties": {}, "examples": [ { "iso": "AUS", "region_code": "VIC", "coordinates": { "latitude": "-37.814200", "longitude": "144.963200" }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "MELBOURNE", "postcode": "3000", "region": "VIC", "country": "AU", "latitude": "-37.814200", "longitude": "144.963200" } ] }, "headcount_location_venue_id": { "type": "integer", "description": "The venue the event is held at, instead of an address of its own.", "examples": [ 1 ] }, "headcount_functional_area_job_title_id": { "type": "integer", "description": "The job title this event's work is counted against for workforce planning.", "examples": [ 1 ] }, "certificate_id": { "type": "integer", "description": "The certificate awarded for taking part in this event.", "examples": [ 1 ] }, "visibility_show_groups": { "type": "array", "description": "Restrict the event to these groups, as a list of group ids. An empty list shows it to everyone.", "items": { "type": "integer" }, "examples": [ [] ] }, "visibility_hide_groups": { "type": "array", "description": "Hide the event from these groups, as a list of group ids.", "items": { "type": "integer" }, "examples": [ [] ] }, "visibility_show_roleoffer": { "type": "array", "description": "Restrict the event to people who came through these role offers, as a list of role offer ids.", "items": { "type": "integer" }, "examples": [ [] ] }, "shift_application_form_id_default": { "type": "integer", "description": "The form filled in when applying for one of this event's shifts.", "examples": [ 1 ] }, "shift_precheckin_form_id_default": { "type": "integer", "description": "The form filled in before checking in to one of this event's shifts.", "examples": [ 1 ] }, "shift_checkin_form_id_default": { "type": "integer", "description": "The form filled in at check-in.", "examples": [ 1 ] }, "shift_attended_form_id_default": { "type": "integer", "description": "The form filled in once attendance is recorded.", "examples": [ 1 ] }, "shift_checkout_form_id_default": { "type": "integer", "description": "The form filled in at check-out.", "examples": [ 1 ] }, "shift_feedback_form_id_default": { "type": "integer", "description": "The feedback form offered after one of this event's shifts.", "examples": [ 1 ] }, "shift_leader_feedback_form_id_default": { "type": "integer", "description": "The feedback form a shift leader is asked to fill in.", "examples": [ 1 ] }, "shift_precheckin_open_default": { "type": "integer", "description": "How long before a shift starts its pre-check-in form becomes available, in seconds.", "examples": [ 0 ] }, "max_group_demand_default": { "type": "integer", "description": "The most places a group leader may reserve on one of this event's shifts.", "examples": [ 1 ] }, "group_booking_ttl_default": { "type": "integer", "description": "How long a group leader's reserved places are held before they are released, in seconds.", "examples": [ 1 ] }, "geofence_checkin_limit_default": { "type": "integer", "description": "How close to the shift's location someone must be to check in, in metres. Empty means no limit.", "examples": [ 1 ] }, "self_checkin": { "type": "boolean", "description": "Whether people may check themselves in to this event's shifts.", "examples": [ 0 ] }, "self_checkin_open": { "type": "integer", "description": "How long before a shift starts self check-in opens, in seconds.", "examples": [ 1800 ] }, "self_checkin_close": { "type": "integer", "description": "How long after a shift starts self check-in closes, in seconds.", "examples": [ 1800 ] }, "self_checkout_close": { "type": "integer", "description": "How long after a shift ends self check-out closes, in seconds.", "examples": [ 1800 ] }, "checkin_close_default": { "type": "integer", "description": "How long after a shift ends check-in closes, in seconds.", "examples": [ 0 ] }, "checkin_visible_attributes": { "type": "array", "description": "Which fields are shown on the check-in page, as a list of `.` names such as `user.first_name`.", "items": { "type": "string" }, "examples": [ [] ] }, "shift_filter_attributes": { "type": "array", "description": "Which attributes people may filter this event's shifts by, as a list of attribute ids.", "items": { "type": "integer" }, "examples": [ [] ] }, "leader_shift_filter_attributes": { "type": "array", "description": "Which attributes a shift leader may filter by, as a list of attribute ids.", "items": { "type": "integer" }, "examples": [ [] ] }, "post_feedback": { "type": "string", "description": "The message shown once the post-event feedback form is available, as HTML.", "examples": [ "" ] }, "post_feedback_publish_at": { "type": "string", "description": "When the post-event feedback form becomes available, as `YYYY-MM-DD HH:MM:SS`.", "examples": [ null ] }, "training_ids": { "type": "array", "description": "The training people must have completed before they can apply, as a list of training ids.", "items": { "type": "integer" }, "examples": [ [] ] }, "banner_image": { "type": "string", "description": "The event's banner image. Send the URL of an image already uploaded through Rosterfy, or the image itself as `multipart/form-data`. A URL on any other host is rejected.", "examples": [ null ] }, "grid_image": { "type": "string", "description": "The image shown for the event in listings. Same accepted values as `banner_image`.", "examples": [ null ] }, "mobile_banner_image": { "type": "string", "description": "The banner image used on smaller screens. Same accepted values as `banner_image`.", "examples": [ null ] }, "minimum_dob": { "type": "string", "description": "The latest date of birth allowed, as `YYYY-MM-DD`. Cannot be combined with `minimum_age`.", "examples": [ null ] }, "minimum_age": { "type": "string", "description": "The youngest age allowed, as `years:months`, for example `16:0`. Cannot be combined with `minimum_dob`.", "examples": [ null ] }, "maximum_dob": { "type": "string", "description": "The earliest date of birth allowed, as `YYYY-MM-DD`. Cannot be combined with `maximum_age`.", "examples": [ null ] }, "maximum_age": { "type": "string", "description": "The oldest age allowed, as `years:months`. Cannot be combined with `maximum_dob`.", "examples": [ null ] }, "public": { "type": "boolean", "description": "Whether the event is visible to people who are not signed in, on accounts that allow public browsing.", "examples": [ 0 ] }, "public_shift": { "type": "boolean", "description": "Whether this event's shifts are visible to people who are not signed in.", "examples": [ 0 ] }, "public_shift_default": { "type": "boolean", "description": "Whether a newly created shift on this event is public by default.", "examples": [ 0 ] }, "token": { "type": "string", "description": "The event's public reference, the last part of its `rrn`. Generated when the event is created; there is rarely a reason to set your own.", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] }, "expression_of_interest": { "type": "boolean", "description": "Whether people may register interest in the event without applying for a specific shift.", "examples": [ 0 ] }, "expression_of_interest_form": { "type": "integer", "description": "The form filled in when registering interest.", "examples": [ 1 ] }, "shift_enable_waitlist_default": { "type": "boolean", "description": "Whether a full shift on this event takes a waitlist.", "examples": [ 0 ] }, "max_waitlist": { "type": "integer", "description": "How many people a shift's waitlist holds.", "examples": [ 0 ] }, "allow_user_activities": { "type": "boolean", "description": "Whether people may log their own activity against this event.", "examples": [ 0 ] }, "user_activity_form_id": { "type": "integer", "description": "The form used to log that activity.", "examples": [ 1 ] }, "approval_status": { "type": "string", "description": "Where the event sits in the account's approval process, when the account requires events to be approved.", "examples": [ "approved" ] }, "approval_reason": { "type": "string", "description": "Free text explaining the approval decision.", "examples": [ null ] }, "is_ongoing": { "type": "boolean", "description": "Whether the event runs indefinitely rather than between two dates. Setting it clears the start and end.", "examples": [ 0 ] }, "sort_order": { "type": "integer", "description": "Where the event sits when events are ordered manually. Lower comes first.", "examples": [ 0 ] }, "post_feedback_form": { "type": "integer", "description": "The feedback form offered after the event itself.", "examples": [ 1 ] }, "is_archived": { "type": "boolean", "description": "Whether the event is archived. Archived events stay readable but are kept out of the day-to-day listings.", "examples": [ 0 ] }, "custom_*": { "type": "string", "description": "A custom attribute, named by its code - custom_shirt_size, for example. The value follows the attribute's own type, so it may be a string, a number, a boolean or a list. See the custom attributes documentation.", "examples": [ null ] } } } } } } }, "delete": { "summary": "Delete an event", "operationId": "deleteAnEvent", "description": "Removes an event. The record is retained rather than erased, but no endpoint\nrestores it, so treat this as final.\n\n**This delete answers `200`, not the usual `204`.** The body carries `messages`, a\nlist of notices raised while deleting - for example when the event was still in use\nelsewhere in the account. It is `null` when there is nothing to say.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": [ "string", "null" ], "examples": [ null ] } }, "examples": [ { "messages": null } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Event Module" ] }, "parameters": [ { "in": "path", "name": "id", "description": "The ID of the event.", "required": true, "schema": { "type": "integer", "examples": [ 21476343 ] } } ] }, "/api/v2/event/{event_id}/shift/{shift_id}/user": { "get": { "summary": "List shift assignments", "operationId": "listShiftAssignments", "description": "Returns one row per person-on-a-shift, carrying the status they are at and the\ntimes they checked in and out.\n\n**The same listing is published on two paths and they differ in scope.**\n`/event/{event_id}/shift/{shift_id}/user` returns the people on that one shift.\n`/event/shift/user` returns every assignment in the account, across every event,\nand is the one to reach for when you are syncing rather than looking at a single\nshift - narrow it with `filter` and page through it.\n\nThe response is only wrapped in a paginated envelope when a `page` parameter is\nsent. Without one, every match comes back as a flat array. The envelope carries\nno `total` and no `last_page` - page until `next_page_url` is null rather than\ncounting pages up front.\n\nRows carry no related records at all, whichever path you use. The person's name\nand the shift's name are on the row as `nice.user_name` and `nice.shift_name`;\nfor anything more, read the user or the shift by the ids the row carries.", "parameters": [ { "in": "query", "name": "scan", "description": "Match people by name, email, phone or reference, the way\nthe console's search box does.", "required": false, "schema": { "type": "string", "description": "Match people by name, email, phone or reference, the way\nthe console's search box does.", "examples": [ "smith" ] } }, { "in": "query", "name": "active", "description": "Keep only assignments at a status that counts towards\nthe shift's demand.", "required": false, "schema": { "type": "boolean", "description": "Keep only assignments at a status that counts towards\nthe shift's demand.", "examples": [ true ] } }, { "in": "query", "name": "leader", "description": "Keep only assignments at an active status. On\n`/event/shift/user`, where no shift is named, this also narrows the results to\nshifts starting within twelve hours either side of now, and a caller who cannot\nupdate shift assignments sees only the shifts they lead.", "required": false, "schema": { "type": "boolean", "description": "Keep only assignments at an active status. On\n`/event/shift/user`, where no shift is named, this also narrows the results to\nshifts starting within twelve hours either side of now, and a caller who cannot\nupdate shift assignments sees only the shifts they lead.", "examples": [ true ] } }, { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "query", "name": "extras", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "required": false, "schema": { "type": "array", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "items": { "type": "string", "enum": [ "shift_schedule_view_attributes", "payrun", "stats", "other_shift_user_details", "referred_from" ] }, "examples": [ [ "shift_schedule_view_attributes" ] ] } }, { "in": "query", "name": "with", "description": "A list of relations to include in the response. May be single records or collections.\nIt is often more efficient to retrieve this way, to avoid follow-up API calls.", "required": false, "schema": { "type": "array", "description": "A list of relations to include in the response. May be single records or collections.\nIt is often more efficient to retrieve this way, to avoid follow-up API calls.", "items": { "type": "string", "enum": [ "role_offer", "integration_data", "hasManyDeepFromRelationsWithConstraints", "hasOneDeepFromRelationsWithConstraints", "hasManyDeepFromReverse", "hasOneDeepFromReverse" ] }, "examples": [ [ "role_offer" ] ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 3001 ] }, "event_shift_id": { "type": "integer", "examples": [ 2001 ] }, "user_id": { "type": "integer", "examples": [ 1234 ] }, "post_shift_feedback_form_completed_at": { "type": [ "string", "null" ], "examples": [ null ] }, "precheckin_form_completed_at": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_status_id": { "type": "integer", "examples": [ 3 ] }, "demand": { "type": "integer", "examples": [ 1 ] }, "break": { "type": [ "string", "null" ], "examples": [ null ] }, "start_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "end_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "cost": { "type": "string", "examples": [ "0.00" ] }, "cost_meta": { "type": "array", "examples": [ [] ] }, "meta": { "type": [ "string", "null" ], "examples": [ null ] }, "latitude": { "type": [ "string", "null" ], "examples": [ null ] }, "longitude": { "type": [ "string", "null" ], "examples": [ null ] }, "payment_authorization_id": { "type": [ "string", "null" ], "examples": [ null ] }, "waitlist_notification_last_sent_at": { "type": [ "string", "null" ], "examples": [ null ] }, "timesheet_status": { "type": "string", "examples": [ "pending" ] }, "rating": { "type": [ "string", "null" ], "examples": [ null ] }, "demand_expire": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:42.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:42.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20000:event_shift_user:3001" ] }, "journey_step": { "type": "string", "examples": [ "" ] }, "journey_step_category": { "type": "string", "examples": [ "" ] }, "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "event_shift_status_id": { "type": "string", "examples": [ "Confirmed" ] }, "event_shift_status_id:value": { "type": "integer", "examples": [ 3 ] }, "event_shift_status_id:array": { "type": "string", "examples": [ "Confirmed" ] }, "payment_authorization_id": { "type": "string", "examples": [ "" ] }, "timesheet_status": { "type": "string", "examples": [ "Pending" ] }, "timesheet_status:value": { "type": "string", "examples": [ "pending" ] }, "timesheet_status:array": { "type": "string", "examples": [ "Pending" ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "attended": { "type": "object", "properties": { "seconds": { "type": "integer", "examples": [ 0 ] }, "minutes": { "type": "integer", "examples": [ 0 ] }, "hours": { "type": "integer", "examples": [ 0 ] }, "pretty": { "type": "string", "examples": [ "00:00:00" ] } } }, "attended_without_checkout": { "type": "object", "properties": { "seconds": { "type": "integer", "examples": [ 0 ] }, "minutes": { "type": "integer", "examples": [ 0 ] }, "hours": { "type": "integer", "examples": [ 0 ] }, "pretty": { "type": "string", "examples": [ "00:00:00" ] } } }, "event_id": { "type": "integer", "examples": [ 1001 ] }, "event_name": { "type": "string", "examples": [ "Example Event" ] }, "is_event_leader": { "type": "boolean", "examples": [ false ] }, "is_leader": { "type": "boolean", "examples": [ false ] }, "checkin_location": { "type": "array", "examples": [ [] ] }, "shift_name": { "type": "string", "examples": [ "Example Shift" ] }, "user_name": { "type": "string", "examples": [ "Example Volunteer" ] }, "requires_pre_checkin": { "type": "boolean", "examples": [ false ] }, "has_shift_attended_form": { "type": "boolean", "examples": [ false ] }, "has_checkin_form": { "type": "boolean", "examples": [ false ] }, "has_checkout_form": { "type": "boolean", "examples": [ false ] }, "shift_checkin_visible_attributes": { "type": "array", "examples": [ [] ] }, "has_confirmed": { "type": "boolean", "examples": [ true ] }, "has_rejected": { "type": "boolean", "examples": [ false ] }, "has_cancelled": { "type": "boolean", "examples": [ false ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "status_update": { "type": "boolean", "examples": [ true ] }, "precheckin": { "type": "boolean", "examples": [ false ] }, "checkin": { "type": "boolean", "examples": [ true ] }, "checkout": { "type": "boolean", "examples": [ true ] }, "submitAttendedForm": { "type": "boolean", "examples": [ false ] } } }, "attributes": { "type": "array", "examples": [ [] ] }, "is_leader": { "type": "integer", "examples": [ 0 ] } } }, "examples": [ [ { "object": { "id": 3001, "event_shift_id": 2001, "user_id": 1234, "post_shift_feedback_form_completed_at": null, "precheckin_form_completed_at": null, "event_shift_status_id": 3, "demand": 1, "break": null, "start_timestamp": null, "end_timestamp": null, "cost": "0.00", "cost_meta": [], "meta": null, "latitude": null, "longitude": null, "payment_authorization_id": null, "waitlist_notification_last_sent_at": null, "timesheet_status": "pending", "rating": null, "demand_expire": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:36:42.000000Z", "updated_at": "2026-06-09T05:36:42.000000Z", "deleted_by": null }, "nice": { "rrn": "rrn:local:20000:event_shift_user:3001", "journey_step": "", "journey_step_category": "", "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "event_shift_status_id": "Confirmed", "event_shift_status_id:value": 3, "event_shift_status_id:array": "Confirmed", "payment_authorization_id": "", "timesheet_status": "Pending", "timesheet_status:value": "pending", "timesheet_status:array": "Pending", "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "attended": { "seconds": 0, "minutes": 0, "hours": 0, "pretty": "00:00:00" }, "attended_without_checkout": { "seconds": 0, "minutes": 0, "hours": 0, "pretty": "00:00:00" }, "event_id": 1001, "event_name": "Example Event", "is_event_leader": false, "is_leader": false, "checkin_location": [], "shift_name": "Example Shift", "user_name": "Example Volunteer", "requires_pre_checkin": false, "has_shift_attended_form": false, "has_checkin_form": false, "has_checkout_form": false, "shift_checkin_visible_attributes": [], "has_confirmed": true, "has_rejected": false, "has_cancelled": false }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "status_update": true, "precheckin": false, "checkin": true, "checkout": true, "submitAttendedForm": false }, "attributes": [], "is_leader": 0 }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/event/{event}/shift/{shift}/user?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/event/{event}/shift/{shift}/user?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/event/{event}/shift/{shift}/user" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 3001, "event_shift_id": 2001, "user_id": 1234, "post_shift_feedback_form_completed_at": null, "precheckin_form_completed_at": null, "event_shift_status_id": 3, "demand": 1, "break": null, "start_timestamp": null, "end_timestamp": null, "cost": "0.00", "cost_meta": [], "meta": null, "latitude": null, "longitude": null, "payment_authorization_id": null, "waitlist_notification_last_sent_at": null, "timesheet_status": "pending", "rating": null, "demand_expire": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:36:42.000000Z", "updated_at": "2026-06-09T05:36:42.000000Z", "deleted_by": null }, "nice": { "rrn": "rrn:local:20000:event_shift_user:3001", "journey_step": "", "journey_step_category": "", "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "event_shift_status_id": "Confirmed", "event_shift_status_id:value": 3, "event_shift_status_id:array": "Confirmed", "payment_authorization_id": "", "timesheet_status": "Pending", "timesheet_status:value": "pending", "timesheet_status:array": "Pending", "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "attended": { "seconds": 0, "minutes": 0, "hours": 0, "pretty": "00:00:00" }, "attended_without_checkout": { "seconds": 0, "minutes": 0, "hours": 0, "pretty": "00:00:00" }, "event_id": 1001, "event_name": "Example Event", "is_event_leader": false, "is_leader": false, "checkin_location": [], "shift_name": "Example Shift", "user_name": "Example Volunteer", "requires_pre_checkin": false, "has_shift_attended_form": false, "has_checkin_form": false, "has_checkout_form": false, "shift_checkin_visible_attributes": [], "has_confirmed": true, "has_rejected": false, "has_cancelled": false }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "status_update": true, "precheckin": false, "checkin": true, "checkout": true, "submitAttendedForm": false }, "attributes": [], "is_leader": 0 }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/event/{event}/shift/{shift}/user?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/event/{event}/shift/{shift}/user?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/event/{event}/shift/{shift}/user", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Shift Module" ] }, "post": { "summary": "Put a person on a shift", "operationId": "putAPersonOnAShift", "description": "Creates one assignment against the shift in the URL, at the status you name, and\nreturns it.\n\nThe created record carries only the fields the create set - the rest are filled\nin as the shift runs - so read it back if you need the full shape.\n\n**`swap_from_shift_id` turns this into a move rather than an add.** Send it and\nthe person is taken off that shift as part of the same request, then put on this\none; their assignment on the old shift is deleted, along with the same person's\nassignment for any family member you named. Leave it out and nothing is removed.\nBecause it changes what the endpoint does, it is also authorised differently: a\nplain add needs only the access to create an assignment, while a move needs\neither the access to move people between shifts or both create **and** delete.\nA caller without that gets a 404 rather than a create.\n\n`family_member_ids` adds several people in one call - the person in `user_id`\nplus any of their own family members you name. The response is the assignment for\n`user_id`; read the shift's assignments back for the rest.\n\n`repeat` extends the create to every later shift linked to this one, so one call\ncan put someone on a whole recurring series.\n\nA status the account treats as cancelled is refused, and so is a `demand` larger\nthan the places the shift has left. Both come back as a 422 naming the field.\n\nBeyond the fields listed here the endpoint also accepts the account's own\nconfigured attributes for an assignment.\n\nThis endpoint honours the `trigger_automation` request option. It honours\n`dry_run` **only for callers whose access allows it** - for anyone else the\noption is ignored and the write goes ahead, with no sign in the response that a\npreview was asked for. See **Request options**.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "timesheet_status": { "type": "string", "examples": [ "pending" ] }, "event_shift_status_id": { "type": "integer", "examples": [ 3001 ] }, "user_id": { "type": "integer", "examples": [ 1234 ] }, "event_shift_id": { "type": "integer", "examples": [ 2001 ] }, "cost_meta": { "type": "array", "examples": [ [] ] }, "updated_at": { "type": "string", "examples": [ "2026-08-12T00:40:25.000000Z" ] }, "created_at": { "type": "string", "examples": [ "2026-08-12T00:40:25.000000Z" ] }, "id": { "type": "integer", "examples": [ 3001 ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20000:event_shift_user:3001" ] }, "journey_step": { "type": "string", "examples": [ "" ] }, "journey_step_category": { "type": "string", "examples": [ "" ] }, "created_at": { "type": "string", "examples": [ "Aug 12, 2026, 12:40 AM" ] }, "created_at__date": { "type": "string", "examples": [ "Aug 12, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "12:40 AM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Wednesday" ] }, "event_shift_status_id": { "type": "string", "examples": [ "Pending" ] }, "event_shift_status_id:value": { "type": "integer", "examples": [ 2 ] }, "event_shift_status_id:array": { "type": "string", "examples": [ "Pending" ] }, "payment_authorization_id": { "type": "string", "examples": [ "" ] }, "timesheet_status": { "type": "string", "examples": [ "Pending" ] }, "timesheet_status:value": { "type": "string", "examples": [ "pending" ] }, "timesheet_status:array": { "type": "string", "examples": [ "Pending" ] }, "updated_at": { "type": "string", "examples": [ "Aug 12, 2026, 12:40 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Aug 12, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "12:40 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Wednesday" ] }, "attended": { "type": "object", "properties": { "seconds": { "type": "integer", "examples": [ 0 ] }, "minutes": { "type": "integer", "examples": [ 0 ] }, "hours": { "type": "integer", "examples": [ 0 ] }, "pretty": { "type": "string", "examples": [ "00:00:00" ] } } }, "attended_without_checkout": { "type": "object", "properties": { "seconds": { "type": "integer", "examples": [ 0 ] }, "minutes": { "type": "integer", "examples": [ 0 ] }, "hours": { "type": "integer", "examples": [ 0 ] }, "pretty": { "type": "string", "examples": [ "00:00:00" ] } } }, "event_id": { "type": "integer", "examples": [ 1001 ] }, "event_name": { "type": "string", "examples": [ "Example Event" ] }, "is_event_leader": { "type": "boolean", "examples": [ false ] }, "is_leader": { "type": "boolean", "examples": [ false ] }, "checkin_location": { "type": "array", "examples": [ [] ] }, "shift_name": { "type": "string", "examples": [ "Example Shift" ] }, "user_name": { "type": "string", "examples": [ "Example Volunteer" ] }, "requires_pre_checkin": { "type": "boolean", "examples": [ false ] }, "has_shift_attended_form": { "type": "boolean", "examples": [ false ] }, "has_checkin_form": { "type": "boolean", "examples": [ false ] }, "has_checkout_form": { "type": "boolean", "examples": [ false ] }, "shift_checkin_visible_attributes": { "type": "array", "examples": [ [] ] }, "has_confirmed": { "type": "boolean", "examples": [ false ] }, "has_rejected": { "type": "boolean", "examples": [ false ] }, "has_cancelled": { "type": "boolean", "examples": [ false ] } } }, "relations": { "type": "object", "properties": {} }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "status_update": { "type": "boolean", "examples": [ true ] }, "precheckin": { "type": "boolean", "examples": [ false ] }, "checkin": { "type": "boolean", "examples": [ true ] }, "checkout": { "type": "boolean", "examples": [ true ] }, "submitAttendedForm": { "type": "boolean", "examples": [ false ] } } }, "attributes": { "type": "object", "properties": {} }, "is_leader": { "type": "integer", "examples": [ 0 ] } }, "examples": [ { "object": { "timesheet_status": "pending", "event_shift_status_id": 3001, "user_id": 1234, "event_shift_id": 2001, "cost_meta": [], "updated_at": "2026-08-12T00:40:25.000000Z", "created_at": "2026-08-12T00:40:25.000000Z", "id": 3001 }, "nice": { "rrn": "rrn:local:20000:event_shift_user:3001", "journey_step": "", "journey_step_category": "", "created_at": "Aug 12, 2026, 12:40 AM", "created_at__date": "Aug 12, 2026", "created_at__time": "12:40 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Wednesday", "event_shift_status_id": "Pending", "event_shift_status_id:value": 2, "event_shift_status_id:array": "Pending", "payment_authorization_id": "", "timesheet_status": "Pending", "timesheet_status:value": "pending", "timesheet_status:array": "Pending", "updated_at": "Aug 12, 2026, 12:40 AM", "updated_at__date": "Aug 12, 2026", "updated_at__time": "12:40 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Wednesday", "attended": { "seconds": 0, "minutes": 0, "hours": 0, "pretty": "00:00:00" }, "attended_without_checkout": { "seconds": 0, "minutes": 0, "hours": 0, "pretty": "00:00:00" }, "event_id": 1001, "event_name": "Example Event", "is_event_leader": false, "is_leader": false, "checkin_location": [], "shift_name": "Example Shift", "user_name": "Example Volunteer", "requires_pre_checkin": false, "has_shift_attended_form": false, "has_checkin_form": false, "has_checkout_form": false, "shift_checkin_visible_attributes": [], "has_confirmed": false, "has_rejected": false, "has_cancelled": false }, "relations": {}, "permissions": { "read": true, "update": true, "delete": true, "status_update": true, "precheckin": false, "checkin": true, "checkout": true, "submitAttendedForm": false }, "attributes": {}, "is_leader": 0 } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Shift Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_shift_status_id": { "type": "integer", "description": "The status the assignment starts at, or moves to. Must be one of the account's own shift statuses; a status the account treats as cancelled is refused.", "examples": [ 3001 ] }, "user_id": { "type": "integer", "description": "The ID of the person to put on the shift.", "examples": [ 1234 ] }, "is_leader": { "type": "boolean", "description": "Whether this person leads the shift. Setting it on a shift that already has as many leaders as it allows returns a 405 - see the description.", "examples": [ true ] }, "start_timestamp": { "type": "string", "description": "When the person checked in, as `YYYY-MM-DDTHH:MM`. Clearing it while an end time is still set is refused.", "examples": [ null ] }, "end_timestamp": { "type": "string", "description": "When the person checked out, as `YYYY-MM-DDTHH:MM`.", "examples": [ null ] }, "break": { "type": "number", "description": "Unpaid break taken during the shift, in minutes. Subtracted from the attended time.", "examples": [ 1.23 ] }, "repeat": { "type": "boolean", "description": "Apply the same change to this person's assignments on every later shift linked to this one. Only meaningful on a shift that belongs to a linked series.", "examples": [ true ] }, "timesheet_status": { "type": "string", "description": "Where the assignment sits in timesheet approval.", "examples": [ "pending" ] }, "family_member_ids": { "type": "array", "description": "IDs of family members of `user_id` to put on the shift alongside them. Only members of that person's own family are used; anything else is ignored.", "items": { "type": "integer" }, "examples": [ [] ] }, "swap_from_shift_id": { "type": "integer", "description": "Move the person off this shift as part of the same request - see the description.", "examples": [ 1 ] }, "custom_*": { "type": "string", "description": "A custom attribute, named by its code - custom_shirt_size, for example. The value follows the attribute's own type, so it may be a string, a number, a boolean or a list. See the custom attributes documentation.", "examples": [ null ] } }, "required": [ "event_shift_status_id", "user_id" ] } } } } }, "parameters": [ { "in": "path", "name": "event_id", "description": "The ID of the event.", "required": true, "schema": { "type": "integer", "examples": [ 16 ] } }, { "in": "path", "name": "shift_id", "description": "The ID of the shift.", "required": true, "schema": { "type": "integer", "examples": [ 16 ] } } ] }, "/api/v2/event/{event_id}/shift/{shift_id}/user/{id}": { "get": { "summary": "Read a shift assignment", "operationId": "readAShiftAssignment", "description": "Returns one person's place on one shift: the status they are at, the times they\nchecked in and out, the break they took, any rating recorded, and the account's\nown configured attributes for an assignment.\n\nAll three ids in the URL have to line up - the shift must belong to the event and\nthe assignment must belong to the shift - otherwise the response is a 404.", "parameters": [ { "in": "query", "name": "leader_mode", "description": "Return the reduced view a shift leader is shown,\ncarrying only the check-in and check-out fields rather than the whole assignment.", "required": false, "schema": { "type": "boolean", "description": "Return the reduced view a shift leader is shown,\ncarrying only the check-in and check-out fields rather than the whole assignment.", "examples": [ true ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 3001 ] }, "event_shift_id": { "type": "integer", "examples": [ 2001 ] }, "user_id": { "type": "integer", "examples": [ 1234 ] }, "post_shift_feedback_form_completed_at": { "type": [ "string", "null" ], "examples": [ null ] }, "precheckin_form_completed_at": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_status_id": { "type": "integer", "examples": [ 3 ] }, "demand": { "type": "integer", "examples": [ 1 ] }, "break": { "type": [ "string", "null" ], "examples": [ null ] }, "start_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "end_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "cost": { "type": "string", "examples": [ "0.00" ] }, "cost_meta": { "type": "array", "examples": [ [] ] }, "meta": { "type": [ "string", "null" ], "examples": [ null ] }, "latitude": { "type": [ "string", "null" ], "examples": [ null ] }, "longitude": { "type": [ "string", "null" ], "examples": [ null ] }, "payment_authorization_id": { "type": [ "string", "null" ], "examples": [ null ] }, "waitlist_notification_last_sent_at": { "type": [ "string", "null" ], "examples": [ null ] }, "timesheet_status": { "type": "string", "examples": [ "pending" ] }, "rating": { "type": [ "string", "null" ], "examples": [ null ] }, "demand_expire": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:42.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:42.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20000:event_shift_user:3001" ] }, "journey_step": { "type": "string", "examples": [ "" ] }, "journey_step_category": { "type": "string", "examples": [ "" ] }, "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "event_shift_status_id": { "type": "string", "examples": [ "Confirmed" ] }, "event_shift_status_id:value": { "type": "integer", "examples": [ 3 ] }, "event_shift_status_id:array": { "type": "string", "examples": [ "Confirmed" ] }, "payment_authorization_id": { "type": "string", "examples": [ "" ] }, "timesheet_status": { "type": "string", "examples": [ "Pending" ] }, "timesheet_status:value": { "type": "string", "examples": [ "pending" ] }, "timesheet_status:array": { "type": "string", "examples": [ "Pending" ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "attended": { "type": "object", "properties": { "seconds": { "type": "integer", "examples": [ 0 ] }, "minutes": { "type": "integer", "examples": [ 0 ] }, "hours": { "type": "integer", "examples": [ 0 ] }, "pretty": { "type": "string", "examples": [ "00:00:00" ] } } }, "attended_without_checkout": { "type": "object", "properties": { "seconds": { "type": "integer", "examples": [ 0 ] }, "minutes": { "type": "integer", "examples": [ 0 ] }, "hours": { "type": "integer", "examples": [ 0 ] }, "pretty": { "type": "string", "examples": [ "00:00:00" ] } } }, "event_id": { "type": "integer", "examples": [ 1001 ] }, "event_name": { "type": "string", "examples": [ "Example Event" ] }, "is_event_leader": { "type": "boolean", "examples": [ false ] }, "is_leader": { "type": "boolean", "examples": [ false ] }, "checkin_location": { "type": "array", "examples": [ [] ] }, "shift_name": { "type": "string", "examples": [ "Example Shift" ] }, "user_name": { "type": "string", "examples": [ "Example Volunteer" ] }, "requires_pre_checkin": { "type": "boolean", "examples": [ false ] }, "has_shift_attended_form": { "type": "boolean", "examples": [ false ] }, "has_checkin_form": { "type": "boolean", "examples": [ false ] }, "has_checkout_form": { "type": "boolean", "examples": [ false ] }, "shift_checkin_visible_attributes": { "type": "array", "examples": [ [] ] }, "has_confirmed": { "type": "boolean", "examples": [ true ] }, "has_rejected": { "type": "boolean", "examples": [ false ] }, "has_cancelled": { "type": "boolean", "examples": [ false ] } } }, "relations": { "type": "object", "properties": {} }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "status_update": { "type": "boolean", "examples": [ true ] }, "precheckin": { "type": "boolean", "examples": [ false ] }, "checkin": { "type": "boolean", "examples": [ true ] }, "checkout": { "type": "boolean", "examples": [ true ] }, "submitAttendedForm": { "type": "boolean", "examples": [ false ] } } }, "attributes": { "type": "object", "properties": {} }, "is_leader": { "type": "integer", "examples": [ 0 ] } }, "examples": [ { "object": { "id": 3001, "event_shift_id": 2001, "user_id": 1234, "post_shift_feedback_form_completed_at": null, "precheckin_form_completed_at": null, "event_shift_status_id": 3, "demand": 1, "break": null, "start_timestamp": null, "end_timestamp": null, "cost": "0.00", "cost_meta": [], "meta": null, "latitude": null, "longitude": null, "payment_authorization_id": null, "waitlist_notification_last_sent_at": null, "timesheet_status": "pending", "rating": null, "demand_expire": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:36:42.000000Z", "updated_at": "2026-06-09T05:36:42.000000Z", "deleted_by": null }, "nice": { "rrn": "rrn:local:20000:event_shift_user:3001", "journey_step": "", "journey_step_category": "", "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "event_shift_status_id": "Confirmed", "event_shift_status_id:value": 3, "event_shift_status_id:array": "Confirmed", "payment_authorization_id": "", "timesheet_status": "Pending", "timesheet_status:value": "pending", "timesheet_status:array": "Pending", "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "attended": { "seconds": 0, "minutes": 0, "hours": 0, "pretty": "00:00:00" }, "attended_without_checkout": { "seconds": 0, "minutes": 0, "hours": 0, "pretty": "00:00:00" }, "event_id": 1001, "event_name": "Example Event", "is_event_leader": false, "is_leader": false, "checkin_location": [], "shift_name": "Example Shift", "user_name": "Example Volunteer", "requires_pre_checkin": false, "has_shift_attended_form": false, "has_checkin_form": false, "has_checkout_form": false, "shift_checkin_visible_attributes": [], "has_confirmed": true, "has_rejected": false, "has_cancelled": false }, "relations": {}, "permissions": { "read": true, "update": true, "delete": true, "status_update": true, "precheckin": false, "checkin": true, "checkout": true, "submitAttendedForm": false }, "attributes": {}, "is_leader": 0 } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Shift Module" ] }, "put": { "summary": "Update a shift assignment", "operationId": "updateAShiftAssignment", "description": "Moves an assignment to a new status, or records the check-in and check-out times,\nbreak, demand, rating or note against it. Returns the assignment in the same\nshape as reading it.\n\nEvery field is optional, so an empty body is a no-op that returns the assignment\nunchanged. **Fields the account has not configured as attributes of an assignment\nare dropped without comment** rather than rejected, so a misspelt field name\ncomes back as a 200 that changed nothing - read the response to confirm what\nlanded.\n\nThree changes behave in ways worth knowing before you send them:\n\n- **Making someone a leader of a shift that already has its full complement of\n leaders returns a 405.** The body carries a `reference`, and a caller holding\n the matching permission can repeat the request with that key in an `override`\n **query parameter** - `?override[]=override_system_limits.event.shift.leader.demand` -\n to raise the shift's leader demand and go ahead. Sending `override` in the JSON\n body does not work.\n- **On a shift belonging to a linked series, the first attempt returns a 400**\n asking whether the change should apply to the later linked shifts too. Repeat\n the request with `repeat` set to answer it; the `reference` in the body names\n the field to send.\n- Moving to a status the account treats as cancelled is refused unless the shift\n itself is cancelled, and clearing `start_timestamp` while `end_timestamp` is\n still set is refused. Both are a 422 naming the field.\n\n`feedback` is kept only when the status being set is one the account treats as\nnot approved; sent with any other status it is discarded.\n\nBeyond the fields listed here the endpoint also accepts the account's own\nconfigured attributes for an assignment.\n\nThis endpoint honours the `trigger_automation` request option. It honours\n`dry_run` **only for callers whose access allows it** - for anyone else the\noption is ignored and the write goes ahead, with no sign in the response that a\npreview was asked for. See **Request options**.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 3001 ] }, "event_shift_id": { "type": "integer", "examples": [ 2001 ] }, "user_id": { "type": "integer", "examples": [ 1234 ] }, "post_shift_feedback_form_completed_at": { "type": [ "string", "null" ], "examples": [ null ] }, "precheckin_form_completed_at": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_status_id": { "type": "integer", "examples": [ 3 ] }, "demand": { "type": "integer", "examples": [ 1 ] }, "break": { "type": [ "string", "null" ], "examples": [ null ] }, "start_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "end_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "cost": { "type": "string", "examples": [ "0.00" ] }, "cost_meta": { "type": "array", "examples": [ [] ] }, "meta": { "type": [ "string", "null" ], "examples": [ null ] }, "latitude": { "type": [ "string", "null" ], "examples": [ null ] }, "longitude": { "type": [ "string", "null" ], "examples": [ null ] }, "payment_authorization_id": { "type": [ "string", "null" ], "examples": [ null ] }, "waitlist_notification_last_sent_at": { "type": [ "string", "null" ], "examples": [ null ] }, "timesheet_status": { "type": "string", "examples": [ "pending" ] }, "rating": { "type": [ "string", "null" ], "examples": [ null ] }, "demand_expire": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:42.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:42.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20000:event_shift_user:3001" ] }, "journey_step": { "type": "string", "examples": [ "" ] }, "journey_step_category": { "type": "string", "examples": [ "" ] }, "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "event_shift_status_id": { "type": "string", "examples": [ "Confirmed" ] }, "event_shift_status_id:value": { "type": "integer", "examples": [ 3 ] }, "event_shift_status_id:array": { "type": "string", "examples": [ "Confirmed" ] }, "payment_authorization_id": { "type": "string", "examples": [ "" ] }, "timesheet_status": { "type": "string", "examples": [ "Pending" ] }, "timesheet_status:value": { "type": "string", "examples": [ "pending" ] }, "timesheet_status:array": { "type": "string", "examples": [ "Pending" ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "attended": { "type": "object", "properties": { "seconds": { "type": "integer", "examples": [ 0 ] }, "minutes": { "type": "integer", "examples": [ 0 ] }, "hours": { "type": "integer", "examples": [ 0 ] }, "pretty": { "type": "string", "examples": [ "00:00:00" ] } } }, "attended_without_checkout": { "type": "object", "properties": { "seconds": { "type": "integer", "examples": [ 0 ] }, "minutes": { "type": "integer", "examples": [ 0 ] }, "hours": { "type": "integer", "examples": [ 0 ] }, "pretty": { "type": "string", "examples": [ "00:00:00" ] } } }, "event_id": { "type": "integer", "examples": [ 1001 ] }, "event_name": { "type": "string", "examples": [ "Example Event" ] }, "is_event_leader": { "type": "boolean", "examples": [ false ] }, "is_leader": { "type": "boolean", "examples": [ false ] }, "checkin_location": { "type": "array", "examples": [ [] ] }, "shift_name": { "type": "string", "examples": [ "Example Shift" ] }, "user_name": { "type": "string", "examples": [ "Example Volunteer" ] }, "requires_pre_checkin": { "type": "boolean", "examples": [ false ] }, "has_shift_attended_form": { "type": "boolean", "examples": [ false ] }, "has_checkin_form": { "type": "boolean", "examples": [ false ] }, "has_checkout_form": { "type": "boolean", "examples": [ false ] }, "shift_checkin_visible_attributes": { "type": "array", "examples": [ [] ] }, "has_confirmed": { "type": "boolean", "examples": [ true ] }, "has_rejected": { "type": "boolean", "examples": [ false ] }, "has_cancelled": { "type": "boolean", "examples": [ false ] } } }, "relations": { "type": "object", "properties": {} }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "status_update": { "type": "boolean", "examples": [ true ] }, "precheckin": { "type": "boolean", "examples": [ false ] }, "checkin": { "type": "boolean", "examples": [ true ] }, "checkout": { "type": "boolean", "examples": [ true ] }, "submitAttendedForm": { "type": "boolean", "examples": [ false ] } } }, "attributes": { "type": "object", "properties": {} }, "is_leader": { "type": "integer", "examples": [ 0 ] } }, "examples": [ { "object": { "id": 3001, "event_shift_id": 2001, "user_id": 1234, "post_shift_feedback_form_completed_at": null, "precheckin_form_completed_at": null, "event_shift_status_id": 3, "demand": 1, "break": null, "start_timestamp": null, "end_timestamp": null, "cost": "0.00", "cost_meta": [], "meta": null, "latitude": null, "longitude": null, "payment_authorization_id": null, "waitlist_notification_last_sent_at": null, "timesheet_status": "pending", "rating": null, "demand_expire": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:36:42.000000Z", "updated_at": "2026-06-09T05:36:42.000000Z", "deleted_by": null }, "nice": { "rrn": "rrn:local:20000:event_shift_user:3001", "journey_step": "", "journey_step_category": "", "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "event_shift_status_id": "Confirmed", "event_shift_status_id:value": 3, "event_shift_status_id:array": "Confirmed", "payment_authorization_id": "", "timesheet_status": "Pending", "timesheet_status:value": "pending", "timesheet_status:array": "Pending", "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "attended": { "seconds": 0, "minutes": 0, "hours": 0, "pretty": "00:00:00" }, "attended_without_checkout": { "seconds": 0, "minutes": 0, "hours": 0, "pretty": "00:00:00" }, "event_id": 1001, "event_name": "Example Event", "is_event_leader": false, "is_leader": false, "checkin_location": [], "shift_name": "Example Shift", "user_name": "Example Volunteer", "requires_pre_checkin": false, "has_shift_attended_form": false, "has_checkin_form": false, "has_checkout_form": false, "shift_checkin_visible_attributes": [], "has_confirmed": true, "has_rejected": false, "has_cancelled": false }, "relations": {}, "permissions": { "read": true, "update": true, "delete": true, "status_update": true, "precheckin": false, "checkin": true, "checkout": true, "submitAttendedForm": false }, "attributes": {}, "is_leader": 0 } ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Do you want to update all linked Shifts after this one that have the same status?" ] }, "reference": { "type": "string", "examples": [ "repeat" ] } }, "examples": [ { "message": "Do you want to update all linked Shifts after this one that have the same status?", "reference": "repeat" } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } }, "405": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Leader demand is already full for this Shift. Would you like to increase the leader demand?" ] }, "reference": { "type": "string", "examples": [ "override_system_limits.event.shift.leader.demand" ] } }, "examples": [ { "message": "Leader demand is already full for this Shift. Would you like to increase the leader demand?", "reference": "override_system_limits.event.shift.leader.demand" } ] } } } } }, "tags": [ "Shift Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_shift_status_id": { "type": "integer", "description": "The status the assignment starts at, or moves to. Must be one of the account's own shift statuses; a status the account treats as cancelled is refused.", "examples": [ 3 ] }, "is_leader": { "type": "boolean", "description": "Whether this person leads the shift. Setting it on a shift that already has as many leaders as it allows returns a 405 - see the description.", "examples": [ true ] }, "feedback": { "type": "string", "description": "A note about this person's performance on the shift. Kept only when the status being set is one the account treats as not approved, and discarded otherwise.", "examples": [ null ] }, "start_timestamp": { "type": "string", "description": "When the person checked in, as `YYYY-MM-DDTHH:MM`. Clearing it while an end time is still set is refused.", "examples": [ null ] }, "end_timestamp": { "type": "string", "description": "When the person checked out, as `YYYY-MM-DDTHH:MM`.", "examples": [ null ] }, "break": { "type": "number", "description": "Unpaid break taken during the shift, in minutes. Subtracted from the attended time.", "examples": [ 1.23 ] }, "demand": { "type": "number", "description": "How many places on the shift this assignment takes up. Defaults to 1. Cannot exceed the places the shift has left.", "examples": [ 1 ] }, "rating": { "type": "integer", "description": "A rating for how the person performed on this shift, 0 to 5.", "examples": [ 1 ] }, "timesheet_status": { "type": "string", "description": "Where the assignment sits in timesheet approval.", "examples": [ "pending" ] }, "repeat": { "type": "boolean", "description": "Apply the same change to this person's assignments on every later shift linked to this one. Only meaningful on a shift that belongs to a linked series.", "examples": [ true ] }, "custom_*": { "type": "string", "description": "A custom attribute, named by its code - custom_shirt_size, for example. The value follows the attribute's own type, so it may be a string, a number, a boolean or a list. See the custom attributes documentation.", "examples": [ null ] } } } } } } }, "delete": { "summary": "Take a person off a shift", "operationId": "takeAPersonOffAShift", "description": "Removes one assignment. The person and the shift are both left alone; only their\nplace on it goes.\n\nThe record is soft-deleted, so it stops appearing in listings but the history of\nwho was on the shift is kept.\n\n**On a shift belonging to a linked series the first attempt returns a 400**\nasking whether the person should come off the later linked shifts too. Repeat the\nrequest with `repeat` set to answer it. Sending `repeat` as true removes them\nfrom every later linked shift as well.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "204": { "description": "No content, successful deletion", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Do you want to delete this User from all linked Shifts after this one?" ] }, "reference": { "type": "string", "examples": [ "repeat" ] } }, "examples": [ { "message": "Do you want to delete this User from all linked Shifts after this one?", "reference": "repeat" } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Shift Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "repeat": { "type": "boolean", "description": "Apply the same change to this person's assignments on every later shift linked to this one. Only meaningful on a shift that belongs to a linked series.", "examples": [ true ] } } } } } } }, "parameters": [ { "in": "path", "name": "event_id", "description": "The ID of the event.", "required": true, "schema": { "type": "integer", "examples": [ 1001 ] } }, { "in": "path", "name": "shift_id", "description": "The ID of the shift.", "required": true, "schema": { "type": "integer", "examples": [ 2001 ] } }, { "in": "path", "name": "id", "description": "The ID of the shift assignment.", "required": true, "schema": { "type": "integer", "examples": [ 3001 ] } } ] }, "/api/v2/event/shift/user": { "get": { "summary": "List shift assignments", "operationId": "listAllShiftAssignments", "description": "Returns one row per person-on-a-shift, carrying the status they are at and the\ntimes they checked in and out.\n\n**The same listing is published on two paths and they differ in scope.**\n`/event/{event_id}/shift/{shift_id}/user` returns the people on that one shift.\n`/event/shift/user` returns every assignment in the account, across every event,\nand is the one to reach for when you are syncing rather than looking at a single\nshift - narrow it with `filter` and page through it.\n\nThe response is only wrapped in a paginated envelope when a `page` parameter is\nsent. Without one, every match comes back as a flat array. The envelope carries\nno `total` and no `last_page` - page until `next_page_url` is null rather than\ncounting pages up front.\n\nRows carry no related records at all, whichever path you use. The person's name\nand the shift's name are on the row as `nice.user_name` and `nice.shift_name`;\nfor anything more, read the user or the shift by the ids the row carries.", "parameters": [ { "in": "query", "name": "scan", "description": "Match people by name, email, phone or reference, the way\nthe console's search box does.", "required": false, "schema": { "type": "string", "description": "Match people by name, email, phone or reference, the way\nthe console's search box does.", "examples": [ "smith" ] } }, { "in": "query", "name": "active", "description": "Keep only assignments at a status that counts towards\nthe shift's demand.", "required": false, "schema": { "type": "boolean", "description": "Keep only assignments at a status that counts towards\nthe shift's demand.", "examples": [ true ] } }, { "in": "query", "name": "leader", "description": "Keep only assignments at an active status. On\n`/event/shift/user`, where no shift is named, this also narrows the results to\nshifts starting within twelve hours either side of now, and a caller who cannot\nupdate shift assignments sees only the shifts they lead.", "required": false, "schema": { "type": "boolean", "description": "Keep only assignments at an active status. On\n`/event/shift/user`, where no shift is named, this also narrows the results to\nshifts starting within twelve hours either side of now, and a caller who cannot\nupdate shift assignments sees only the shifts they lead.", "examples": [ true ] } }, { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "query", "name": "extras", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "required": false, "schema": { "type": "array", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "items": { "type": "string", "enum": [ "shift_schedule_view_attributes", "payrun", "stats", "other_shift_user_details", "referred_from" ] }, "examples": [ [ "shift_schedule_view_attributes" ] ] } }, { "in": "query", "name": "with", "description": "A list of relations to include in the response. May be single records or collections.\nIt is often more efficient to retrieve this way, to avoid follow-up API calls.", "required": false, "schema": { "type": "array", "description": "A list of relations to include in the response. May be single records or collections.\nIt is often more efficient to retrieve this way, to avoid follow-up API calls.", "items": { "type": "string", "enum": [ "role_offer", "integration_data", "hasManyDeepFromRelationsWithConstraints", "hasOneDeepFromRelationsWithConstraints", "hasManyDeepFromReverse", "hasOneDeepFromReverse" ] }, "examples": [ [ "role_offer" ] ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 3001 ] }, "event_shift_id": { "type": "integer", "examples": [ 2001 ] }, "user_id": { "type": "integer", "examples": [ 1234 ] }, "post_shift_feedback_form_completed_at": { "type": [ "string", "null" ], "examples": [ null ] }, "precheckin_form_completed_at": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_status_id": { "type": "integer", "examples": [ 3 ] }, "demand": { "type": "integer", "examples": [ 1 ] }, "break": { "type": [ "string", "null" ], "examples": [ null ] }, "start_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "end_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "cost": { "type": "string", "examples": [ "0.00" ] }, "cost_meta": { "type": "array", "examples": [ [] ] }, "meta": { "type": [ "string", "null" ], "examples": [ null ] }, "latitude": { "type": [ "string", "null" ], "examples": [ null ] }, "longitude": { "type": [ "string", "null" ], "examples": [ null ] }, "payment_authorization_id": { "type": [ "string", "null" ], "examples": [ null ] }, "waitlist_notification_last_sent_at": { "type": [ "string", "null" ], "examples": [ null ] }, "timesheet_status": { "type": "string", "examples": [ "pending" ] }, "rating": { "type": [ "string", "null" ], "examples": [ null ] }, "demand_expire": { "type": [ "string", "null" ], "examples": [ null ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:42.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:42.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20000:event_shift_user:3001" ] }, "journey_step": { "type": "string", "examples": [ "" ] }, "journey_step_category": { "type": "string", "examples": [ "" ] }, "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "event_shift_status_id": { "type": "string", "examples": [ "Confirmed" ] }, "event_shift_status_id:value": { "type": "integer", "examples": [ 3 ] }, "event_shift_status_id:array": { "type": "string", "examples": [ "Confirmed" ] }, "payment_authorization_id": { "type": "string", "examples": [ "" ] }, "timesheet_status": { "type": "string", "examples": [ "Pending" ] }, "timesheet_status:value": { "type": "string", "examples": [ "pending" ] }, "timesheet_status:array": { "type": "string", "examples": [ "Pending" ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 5:36 AM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "5:36 AM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+00:00 UTC)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 0 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "attended": { "type": "object", "properties": { "seconds": { "type": "integer", "examples": [ 0 ] }, "minutes": { "type": "integer", "examples": [ 0 ] }, "hours": { "type": "integer", "examples": [ 0 ] }, "pretty": { "type": "string", "examples": [ "00:00:00" ] } } }, "attended_without_checkout": { "type": "object", "properties": { "seconds": { "type": "integer", "examples": [ 0 ] }, "minutes": { "type": "integer", "examples": [ 0 ] }, "hours": { "type": "integer", "examples": [ 0 ] }, "pretty": { "type": "string", "examples": [ "00:00:00" ] } } }, "event_id": { "type": "integer", "examples": [ 1001 ] }, "event_name": { "type": "string", "examples": [ "Example Event" ] }, "is_event_leader": { "type": "boolean", "examples": [ false ] }, "is_leader": { "type": "boolean", "examples": [ false ] }, "checkin_location": { "type": "array", "examples": [ [] ] }, "shift_name": { "type": "string", "examples": [ "Example Shift" ] }, "user_name": { "type": "string", "examples": [ "Example Volunteer" ] }, "requires_pre_checkin": { "type": "boolean", "examples": [ false ] }, "has_shift_attended_form": { "type": "boolean", "examples": [ false ] }, "has_checkin_form": { "type": "boolean", "examples": [ false ] }, "has_checkout_form": { "type": "boolean", "examples": [ false ] }, "shift_checkin_visible_attributes": { "type": "array", "examples": [ [] ] }, "has_confirmed": { "type": "boolean", "examples": [ true ] }, "has_rejected": { "type": "boolean", "examples": [ false ] }, "has_cancelled": { "type": "boolean", "examples": [ false ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "status_update": { "type": "boolean", "examples": [ true ] }, "precheckin": { "type": "boolean", "examples": [ false ] }, "checkin": { "type": "boolean", "examples": [ true ] }, "checkout": { "type": "boolean", "examples": [ true ] }, "submitAttendedForm": { "type": "boolean", "examples": [ false ] } } }, "attributes": { "type": "array", "examples": [ [] ] }, "is_leader": { "type": "integer", "examples": [ 0 ] } } }, "examples": [ [ { "object": { "id": 3001, "event_shift_id": 2001, "user_id": 1234, "post_shift_feedback_form_completed_at": null, "precheckin_form_completed_at": null, "event_shift_status_id": 3, "demand": 1, "break": null, "start_timestamp": null, "end_timestamp": null, "cost": "0.00", "cost_meta": [], "meta": null, "latitude": null, "longitude": null, "payment_authorization_id": null, "waitlist_notification_last_sent_at": null, "timesheet_status": "pending", "rating": null, "demand_expire": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:36:42.000000Z", "updated_at": "2026-06-09T05:36:42.000000Z", "deleted_by": null }, "nice": { "rrn": "rrn:local:20000:event_shift_user:3001", "journey_step": "", "journey_step_category": "", "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "event_shift_status_id": "Confirmed", "event_shift_status_id:value": 3, "event_shift_status_id:array": "Confirmed", "payment_authorization_id": "", "timesheet_status": "Pending", "timesheet_status:value": "pending", "timesheet_status:array": "Pending", "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "attended": { "seconds": 0, "minutes": 0, "hours": 0, "pretty": "00:00:00" }, "attended_without_checkout": { "seconds": 0, "minutes": 0, "hours": 0, "pretty": "00:00:00" }, "event_id": 1001, "event_name": "Example Event", "is_event_leader": false, "is_leader": false, "checkin_location": [], "shift_name": "Example Shift", "user_name": "Example Volunteer", "requires_pre_checkin": false, "has_shift_attended_form": false, "has_checkin_form": false, "has_checkout_form": false, "shift_checkin_visible_attributes": [], "has_confirmed": true, "has_rejected": false, "has_cancelled": false }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "status_update": true, "precheckin": false, "checkin": true, "checkout": true, "submitAttendedForm": false }, "attributes": [], "is_leader": 0 }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/event/shift/user?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/event/shift/user?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/event/shift/user" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 3001, "event_shift_id": 2001, "user_id": 1234, "post_shift_feedback_form_completed_at": null, "precheckin_form_completed_at": null, "event_shift_status_id": 3, "demand": 1, "break": null, "start_timestamp": null, "end_timestamp": null, "cost": "0.00", "cost_meta": [], "meta": null, "latitude": null, "longitude": null, "payment_authorization_id": null, "waitlist_notification_last_sent_at": null, "timesheet_status": "pending", "rating": null, "demand_expire": null, "deleted_at": null, "is_erased": 0, "created_at": "2026-06-09T05:36:42.000000Z", "updated_at": "2026-06-09T05:36:42.000000Z", "deleted_by": null }, "nice": { "rrn": "rrn:local:20000:event_shift_user:3001", "journey_step": "", "journey_step_category": "", "created_at": "Jun 9, 2026, 5:36 AM", "created_at__date": "Jun 9, 2026", "created_at__time": "5:36 AM", "created_at__offset": " (+00:00 UTC)", "created_at__offset_minutes": 0, "created_at__dayofweek": "Tuesday", "event_shift_status_id": "Confirmed", "event_shift_status_id:value": 3, "event_shift_status_id:array": "Confirmed", "payment_authorization_id": "", "timesheet_status": "Pending", "timesheet_status:value": "pending", "timesheet_status:array": "Pending", "updated_at": "Jun 9, 2026, 5:36 AM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "5:36 AM", "updated_at__offset": " (+00:00 UTC)", "updated_at__offset_minutes": 0, "updated_at__dayofweek": "Tuesday", "attended": { "seconds": 0, "minutes": 0, "hours": 0, "pretty": "00:00:00" }, "attended_without_checkout": { "seconds": 0, "minutes": 0, "hours": 0, "pretty": "00:00:00" }, "event_id": 1001, "event_name": "Example Event", "is_event_leader": false, "is_leader": false, "checkin_location": [], "shift_name": "Example Shift", "user_name": "Example Volunteer", "requires_pre_checkin": false, "has_shift_attended_form": false, "has_checkin_form": false, "has_checkout_form": false, "shift_checkin_visible_attributes": [], "has_confirmed": true, "has_rejected": false, "has_cancelled": false }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "status_update": true, "precheckin": false, "checkin": true, "checkout": true, "submitAttendedForm": false }, "attributes": [], "is_leader": 0 }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/event/shift/user?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/event/shift/user?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/event/shift/user", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Shift Module" ] } }, "/api/v2/event/{event_id}/shift/{shift_id}/user/mass-create": { "post": { "summary": "Add many people to a shift", "operationId": "addManyPeopleToAShift", "description": "Queues the work of putting a set of people on one shift and returns a token for\nthe queued job. **Nothing is created by the time the response comes back**, and\nthe token is not something you can poll - confirm the outcome by listing the\nshift's assignments.\n\nChoose the people either by naming them in `selected`, or by sending\n`applyTo` with a `filter` describing them. A request whose fields are the right\nshape always returns a queue token, whether or not the background work then\nsucceeds: a person who cannot go on the shift is skipped rather than reported.\n\n**The same action is published on two paths and they name the shift differently.**\n`/event/{event_id}/shift/{shift_id}/user/mass-create` takes it from the URL, and\nignores `event_shift_id` if you send one. `/event/{event_id}/shift/user/mass-create`\ntakes it from `event_shift_id` instead - and reads that **only from the query\nstring**, as `?event_shift_id=123`. Sending it in the JSON body is not seen and\nthe request comes back as a 404. Prefer the first form unless you have a reason\nnot to.\n\nEither way the shift has to belong to the event in the URL; a mismatch is a 404.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "queue": { "type": "string", "examples": [ "mTsVQ1NCLS3vg7WwP5kG1Vbt" ] } }, "examples": [ { "queue": "mTsVQ1NCLS3vg7WwP5kG1Vbt" } ] } } } } }, "tags": [ "Shift Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_shift_status_id": { "type": "integer", "description": "The status the assignment starts at, or moves to. Must be one of the account's own shift statuses; a status the account treats as cancelled is refused.", "examples": [ 1 ] }, "start_timestamp": { "type": "string", "description": "When the person checked in, as `YYYY-MM-DDTHH:MM`. Clearing it while an end time is still set is refused.", "examples": [ null ] }, "end_timestamp": { "type": "string", "description": "When the person checked out, as `YYYY-MM-DDTHH:MM`.", "examples": [ null ] }, "break": { "type": "number", "description": "Unpaid break taken during the shift, in minutes. Subtracted from the attended time.", "examples": [ 1.23 ] }, "is_leader": { "type": "boolean", "description": "Whether this person leads the shift. Setting it on a shift that already has as many leaders as it allows returns a 405 - see the description.", "examples": [ true ] }, "repeat": { "type": "boolean", "description": "Apply the same change to this person's assignments on every later shift linked to this one. Only meaningful on a shift that belongs to a linked series.", "examples": [ true ] }, "event_shift_id": { "type": "integer", "description": "The shift to add people to. Read **only** on `/event/{event_id}/shift/user/mass-create`, and only from the query string - see the description. Ignored on the `/event/{event_id}/shift/{shift_id}/user/mass-create` form, which takes the shift from the URL.", "examples": [ 1 ] }, "applyTo": { "type": "string", "description": "Send `selected` to act only on the records named in `selected`. Any other value acts on everything the caller can see, narrowed by `filter` if one is sent. The value is not checked against a list, so a typo is accepted and treated as \"everything\".", "examples": [ null ] }, "selected": { "type": "array", "description": "The IDs to act on. On the mass add these are user IDs; on the mass delete they are shift assignment IDs. Required in practice when `applyTo` is `selected`, but nothing validates that: omitting it still returns a queue token and the background work then does nothing.", "items": { "type": "integer" }, "examples": [ [] ] }, "filter": { "type": "array", "description": "The same filter object the listings take, used to choose the records to act on when `applyTo` is not `selected`.", "items": { "type": "string" }, "examples": [ [] ] }, "swap_from_shift_id": { "type": "integer", "description": "Move everyone selected off this shift as part of the same request.", "examples": [ 1 ] } }, "required": [ "event_shift_status_id" ] } } } } }, "parameters": [ { "in": "path", "name": "event_id", "description": "The ID of the event.", "required": true, "schema": { "type": "integer", "examples": [ 16 ] } }, { "in": "path", "name": "shift_id", "description": "The ID of the shift.", "required": true, "schema": { "type": "integer", "examples": [ 16 ] } } ] }, "/api/v2/event/{event_id}/shift/user/mass-create": { "post": { "summary": "Add many people to a shift", "operationId": "addManyPeopleToAShiftByQuery", "description": "Queues the work of putting a set of people on one shift and returns a token for\nthe queued job. **Nothing is created by the time the response comes back**, and\nthe token is not something you can poll - confirm the outcome by listing the\nshift's assignments.\n\nChoose the people either by naming them in `selected`, or by sending\n`applyTo` with a `filter` describing them. A request whose fields are the right\nshape always returns a queue token, whether or not the background work then\nsucceeds: a person who cannot go on the shift is skipped rather than reported.\n\n**The same action is published on two paths and they name the shift differently.**\n`/event/{event_id}/shift/{shift_id}/user/mass-create` takes it from the URL, and\nignores `event_shift_id` if you send one. `/event/{event_id}/shift/user/mass-create`\ntakes it from `event_shift_id` instead - and reads that **only from the query\nstring**, as `?event_shift_id=123`. Sending it in the JSON body is not seen and\nthe request comes back as a 404. Prefer the first form unless you have a reason\nnot to.\n\nEither way the shift has to belong to the event in the URL; a mismatch is a 404.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "queue": { "type": "string", "examples": [ "mTsVQ1NCLS3vg7WwP5kG1Vbt" ] } }, "examples": [ { "queue": "mTsVQ1NCLS3vg7WwP5kG1Vbt" } ] } } } } }, "tags": [ "Shift Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_shift_status_id": { "type": "integer", "description": "The status the assignment starts at, or moves to. Must be one of the account's own shift statuses; a status the account treats as cancelled is refused.", "examples": [ 1 ] }, "start_timestamp": { "type": "string", "description": "When the person checked in, as `YYYY-MM-DDTHH:MM`. Clearing it while an end time is still set is refused.", "examples": [ null ] }, "end_timestamp": { "type": "string", "description": "When the person checked out, as `YYYY-MM-DDTHH:MM`.", "examples": [ null ] }, "break": { "type": "number", "description": "Unpaid break taken during the shift, in minutes. Subtracted from the attended time.", "examples": [ 1.23 ] }, "is_leader": { "type": "boolean", "description": "Whether this person leads the shift. Setting it on a shift that already has as many leaders as it allows returns a 405 - see the description.", "examples": [ true ] }, "repeat": { "type": "boolean", "description": "Apply the same change to this person's assignments on every later shift linked to this one. Only meaningful on a shift that belongs to a linked series.", "examples": [ true ] }, "event_shift_id": { "type": "integer", "description": "The shift to add people to. Read **only** on `/event/{event_id}/shift/user/mass-create`, and only from the query string - see the description. Ignored on the `/event/{event_id}/shift/{shift_id}/user/mass-create` form, which takes the shift from the URL.", "examples": [ 1 ] }, "applyTo": { "type": "string", "description": "Send `selected` to act only on the records named in `selected`. Any other value acts on everything the caller can see, narrowed by `filter` if one is sent. The value is not checked against a list, so a typo is accepted and treated as \"everything\".", "examples": [ null ] }, "selected": { "type": "array", "description": "The IDs to act on. On the mass add these are user IDs; on the mass delete they are shift assignment IDs. Required in practice when `applyTo` is `selected`, but nothing validates that: omitting it still returns a queue token and the background work then does nothing.", "items": { "type": "integer" }, "examples": [ [] ] }, "filter": { "type": "array", "description": "The same filter object the listings take, used to choose the records to act on when `applyTo` is not `selected`.", "items": { "type": "string" }, "examples": [ [] ] }, "swap_from_shift_id": { "type": "integer", "description": "Move everyone selected off this shift as part of the same request.", "examples": [ 1 ] } }, "required": [ "event_shift_status_id" ] } } } } }, "parameters": [ { "in": "path", "name": "event_id", "description": "The ID of the event.", "required": true, "schema": { "type": "integer", "examples": [ 16 ] } } ] }, "/api/v2/event/shift/user/mass-delete": { "post": { "summary": "Remove many people from shifts", "operationId": "removeManyPeopleFromShifts", "description": "Queues the work of removing a set of assignments and returns a token for the\nqueued job. **Nothing is removed by the time the response comes back**, and the\ntoken is not something you can poll - confirm the outcome by listing the shift's\nassignments.\n\nChoose the assignments either by naming them in `selected`, or by sending\n`applyTo` with a `filter` describing them. `selected` holds shift assignment IDs\n- the `id` on a listing row - not user IDs.\n\nNote this returns a **201**, where the other queued endpoints in the API return a\n200. The body is the same either way.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "queue": { "type": "string", "examples": [ "mTsVQ1NCLS3vg7WwP5kG1Vbt" ] } }, "examples": [ { "queue": "mTsVQ1NCLS3vg7WwP5kG1Vbt" } ] } } } } }, "tags": [ "Shift Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "applyTo": { "type": "string", "description": "Send `selected` to act only on the records named in `selected`. Any other value acts on everything the caller can see, narrowed by `filter` if one is sent. The value is not checked against a list, so a typo is accepted and treated as \"everything\".", "examples": [ null ] }, "selected": { "type": "array", "description": "The IDs to act on. On the mass add these are user IDs; on the mass delete they are shift assignment IDs. Required in practice when `applyTo` is `selected`, but nothing validates that: omitting it still returns a queue token and the background work then does nothing.", "items": { "type": "integer" }, "examples": [ [] ] }, "filter": { "type": "array", "description": "The same filter object the listings take, used to choose the records to act on when `applyTo` is not `selected`.", "items": { "type": "string" }, "examples": [ [] ] } }, "required": [ "applyTo" ] } } } } } }, "/api/v2/event/shift/apply-all": { "post": { "summary": "Apply for several shifts at once", "operationId": "applyForSeveralShiftsAtOnce", "description": "Puts the signed-in person on every shift in the body. This is what the cart submits\nwhen someone has finished choosing shifts, and it is the endpoint that actually\ncreates the applications - the check that runs as each shift goes into the cart\ndoes not.\n\n**The shifts are not named in the URL; they are the `shifts` array in the body**,\nand each entry has to carry both `event_shift_id` and `leader_applied` even when\nleading is not being asked for. An entry missing either comes back as a 422 saying\n\"Incorrect data structure\" against `shifts`.\n\n**All or nothing.** Every shift is checked before any application is made, and one\nshift that cannot be taken refuses the whole request with a 422 whose `errors`\nnames each shift and says why. The applications, any payment and any linked-series\njoins are made together, and a failure anywhere undoes all of it - including\nvoiding a payment that had already been authorised. A 200 with an empty body means\nevery application was made.\n\nWhere the event sets a minimum number of shifts per person, or a minimum per shift\ntype, a request that would leave the person short is refused here rather than\nshift by shift.\n\nSending the same set of shifts twice within ten seconds returns a 429; the second\nrequest is treated as a double submission rather than a second application.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "examples": [ {} ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "" ] }, "errors": { "type": "array", "items": { "type": "object", "properties": { "event_shift_id": { "type": "integer", "examples": [ 2001 ] }, "message": { "type": "string", "examples": [ "Unable to apply to this Shift" ] } } }, "examples": [ [ { "event_shift_id": 2001, "message": "Unable to apply to this Shift" } ] ] } }, "examples": [ { "message": "", "errors": [ { "event_shift_id": 2001, "message": "Unable to apply to this Shift" } ] } ] } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "User exists in that Shift" ] } }, "examples": [ { "message": "User exists in that Shift" } ] } } } } }, "tags": [ "Shift Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shifts": { "type": "array", "description": "The shifts to apply for, one object per shift. The rule says only \"array\", so the shape of an entry is stated here rather than in the schema. Every entry takes: `event_shift_id` (integer, **required**) the shift being applied for; `leader_applied` (0 or 1, **required** on every entry even when it is 0) whether the application is to lead the shift; `application_form` (object, optional) the answers to that shift's application form, keyed by the field codes your account configured; `linked` (boolean, optional) also join the linked series the shift belongs to, so the person is put on its other shifts; and `in_cart` (boolean, optional) which marks an entry as already in the cart and is ignored here - every entry is applied for whether or not it is set. An entry missing `event_shift_id` or `leader_applied` is refused with \"Incorrect data structure\" against `shifts`, and no application is made for any of them.", "items": { "type": "object" }, "examples": [ [ { "event_shift_id": 2001, "leader_applied": 0 }, { "event_shift_id": 2002, "leader_applied": 1, "linked": true, "application_form": { "user:first_name": "Example", "user:last_name": "Volunteer" } } ] ] }, "paymentData": { "type": "object", "description": "Payment details for shifts that cost money. Read only when the account has a payment provider configured, and ignored otherwise. The keys are the provider's own; a failed payment removes the applications it was for.", "properties": {}, "examples": [ [] ] } }, "required": [ "shifts" ] } } } } } }, "/api/v2/event/shift/{shift_id}/submit-application": { "post": { "summary": "Check a shift's application form", "operationId": "checkAShiftsApplicationForm", "description": "Runs the answers to a shift's application form through that form's own rules and\nreturns the values it accepted.\n\n**Nothing is stored and no application is made.** This is the step before applying:\nit tells you whether the answers will be accepted, so a form that is wrong is\ncaught while the person is still filling it in. Send the same answers as\n`application_form` on the entry for this shift when you apply.\n\nThe fields it accepts are whichever ones your account has configured on the form\nattached to this shift, under the codes you gave them, so they differ from account\nto account and from shift to shift. A field that fails its rule comes back as a 422\nkeyed by that code. The response echoes the values back, with any file answers\nreplaced by the URL they were stored at.\n\nA shift with no application form on it returns a 404.\n\n`asLeader` decides which permission is checked before any of this happens: with it,\nwhether the person can lead the shift, and without it, whether they can take an\nordinary place on it. It changes nothing about the form itself, and it is not one\nof the values returned.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "user:first_name": { "type": "string", "examples": [ "Example" ] }, "user:last_name": { "type": "string", "examples": [ "Volunteer" ] }, "user:email": { "type": "string", "examples": [ "volunteer@example.com" ] }, "user:dob": { "type": "string", "examples": [ "1990-01-01" ] }, "user:terms": { "type": "integer", "examples": [ 1 ] }, "user:custom_multiselect_attribute": { "type": [ "string", "null" ], "examples": [ null ] } }, "examples": [ { "user:first_name": "Example", "user:last_name": "Volunteer", "user:email": "volunteer@example.com", "user:dob": "1990-01-01", "user:terms": 1, "user:custom_multiselect_attribute": null } ] } } } } }, "tags": [ "Shift Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "asLeader": { "type": "boolean", "description": "Check whether the person can lead this shift rather than take an ordinary place on it. The name is camelCase because that is what the endpoint reads.", "examples": [ true ] } } } } } } }, "parameters": [ { "in": "path", "name": "shift_id", "description": "The ID of the shift.", "required": true, "schema": { "type": "integer", "examples": [ 2001 ] } } ] }, "/api/v2/event/{event_id}/shift/link/{link_id}/shift": { "get": { "summary": "List the shifts in a series", "operationId": "listTheShiftsInASeries", "description": "Returns the shifts that belong to one shift link, a page at a time. This is\nhow you see what a repeating shift actually turned into: every occurrence the series\ngenerated, each a full shift with its own times, demand figures, location and statuses.\n\nEach row carries a `relations.pivot` object holding the two ids that join the shift to the\nseries. Rows are the same shape the event's shift listing returns, so anything you can do\nwith a shift from there you can do with one from here.\n\nThe rows describe the shifts, not the people on them - demand appears as counts, and who\nholds a place is read through the shift user endpoints.", "parameters": [ { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "query", "name": "extras", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "required": false, "schema": { "type": "array", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "items": { "type": "string", "enum": [ "group_stats", "stats", "upcoming_shift_attributes", "certificate_stats" ] }, "examples": [ [ "group_stats" ] ] } }, { "in": "query", "name": "with", "description": "A list of relations to include in the response. May be single records or collections.\nIt is often more efficient to retrieve this way, to avoid follow-up API calls.", "required": false, "schema": { "type": "array", "description": "A list of relations to include in the response. May be single records or collections.\nIt is often more efficient to retrieve this way, to avoid follow-up API calls.", "items": { "type": "string", "enum": [ "location_type", "hasManyDeepFromRelationsWithConstraints", "hasOneDeepFromRelationsWithConstraints", "hasManyDeepFromReverse", "hasOneDeepFromReverse" ] }, "examples": [ [ "location_type" ] ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 2001 ] }, "event_id": { "type": "integer", "examples": [ 1001 ] }, "event_shift_type_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_template_id": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_id": { "type": [ "string", "null" ], "examples": [ null ] }, "min_demand": { "type": "integer", "examples": [ 10 ] }, "max_demand": { "type": "integer", "examples": [ 10 ] }, "leader_demand": { "type": "integer", "examples": [ 1 ] }, "start_timestamp": { "type": "string", "examples": [ "2026-09-17 05:00:00" ] }, "end_timestamp": { "type": "string", "examples": [ "2026-09-17 13:00:00" ] }, "timezone": { "type": "string", "examples": [ "Australia/Melbourne" ] }, "no_shift_time": { "type": "integer", "examples": [ 0 ] }, "apps_open_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "apps_close_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_confirmed_status_default": { "type": "integer", "examples": [ 3 ] }, "shift_rejected_status_default": { "type": "integer", "examples": [ 6 ] }, "journey_complete_status": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_can_withdraw_default": { "type": "integer", "examples": [ 1 ] }, "shift_can_confirm": { "type": "integer", "examples": [ 1 ] }, "shift_can_confirm_limit": { "type": "integer", "examples": [ 0 ] }, "shift_can_withdraw_limit": { "type": "integer", "examples": [ 0 ] }, "shift_checked_in_status_default": { "type": "integer", "examples": [ 4 ] }, "shift_checked_out_status_default": { "type": "integer", "examples": [ 4 ] }, "certificate_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "allow_application_form_resubmit": { "type": "integer", "examples": [ 0 ] }, "shift_checkin_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "training_ids": { "type": [ "string", "null" ], "examples": [ null ] }, "visibility_show_groups": { "type": "array", "examples": [ [] ] }, "visibility_hide_groups": { "type": "array", "examples": [ [] ] }, "visibility_show_roleoffer": { "type": "array", "examples": [ [] ] }, "role_offer_id": { "type": [ "string", "null" ], "examples": [ null ] }, "role_offer_address": { "type": "integer", "examples": [ 0 ] }, "checkin_visible_attributes": { "type": "array", "examples": [ [] ] }, "shift_enable_waitlist_default": { "type": "integer", "examples": [ 0 ] }, "max_waitlist": { "type": "integer", "examples": [ 0 ] }, "group_booking_ttl": { "type": [ "string", "null" ], "examples": [ null ] }, "max_group_demand": { "type": [ "string", "null" ], "examples": [ null ] }, "max_group_size": { "type": [ "string", "null" ], "examples": [ null ] }, "reserved_expiry": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "self_checkin": { "type": "integer", "examples": [ 0 ] }, "self_checkin_open": { "type": "integer", "examples": [ 1800 ] }, "self_checkin_close": { "type": "integer", "examples": [ 1800 ] }, "self_checkout_close": { "type": "integer", "examples": [ 1800 ] }, "checkin_close": { "type": "integer", "examples": [ 0 ] }, "shift_precheckin_open": { "type": "integer", "examples": [ 0 ] }, "break": { "type": "integer", "examples": [ 0 ] }, "post_feedback_form": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_leader_feedback_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "is_virtual": { "type": "integer", "examples": [ 0 ] }, "geofence_checkin_limit": { "type": [ "string", "null" ], "examples": [ null ] }, "tax": { "type": [ "string", "null" ], "examples": [ null ] }, "price_excluding_tax": { "type": "integer", "examples": [ 0 ] }, "tax_percentage": { "type": [ "string", "null" ], "examples": [ null ] }, "publish": { "type": "integer", "examples": [ 0 ] }, "public": { "type": "integer", "examples": [ 0 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "is_cancelled": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "is_draft": { "type": "boolean", "examples": [ false ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:10.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:10.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "address": { "type": "object", "properties": { "iso": { "type": "string", "examples": [ "AUS" ] }, "region_code": { "type": "string", "examples": [ "VIC" ] }, "coordinates": { "type": "object", "properties": { "latitude": { "type": "string", "examples": [ "-37.814000" ] }, "longitude": { "type": "string", "examples": [ "144.963100" ] } } }, "street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "city": { "type": "string", "examples": [ "Melbourne" ] }, "postcode": { "type": "string", "examples": [ "3000" ] }, "region": { "type": "string", "examples": [ "VIC" ] }, "country": { "type": "string", "examples": [ "AU" ] }, "latitude": { "type": "string", "examples": [ "-37.814000" ] }, "longitude": { "type": "string", "examples": [ "144.963100" ] } } } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:example:20000:shift:2001" ] }, "address": { "type": "string", "examples": [ "1 Example Street\nMelbourne\nVictoria\nAustralia\n3000" ] }, "address_oneline": { "type": "string", "examples": [ "1 Example Street, Melbourne, Victoria, Australia, 3000" ] }, "address.country": { "type": "string", "examples": [ "Australia" ] }, "address.country:raw": { "type": "string", "examples": [ "AUS" ] }, "address.city": { "type": "string", "examples": [ "Melbourne" ] }, "address.region": { "type": "string", "examples": [ "Victoria" ] }, "address.region:raw": { "type": "string", "examples": [ "VIC" ] }, "address.postcode": { "type": "string", "examples": [ "3000" ] }, "address.street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "address.street_address_2": { "type": "string", "examples": [ "" ] }, "address.street_address_3": { "type": "string", "examples": [ "" ] }, "address.latitude": { "type": "string", "examples": [ "-37.814000" ] }, "address.longitude": { "type": "string", "examples": [ "144.963100" ] }, "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 3:36 PM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "3:36 PM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+10:00 AEST)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 600 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "end_timestamp": { "type": "string", "examples": [ "Sep 17, 2026, 11:00 PM" ] }, "end_timestamp__date": { "type": "string", "examples": [ "Sep 17, 2026" ] }, "end_timestamp__time": { "type": "string", "examples": [ "11:00 PM" ] }, "end_timestamp__offset": { "type": "string", "examples": [ " (+10:00 AEST)" ] }, "end_timestamp__offset_minutes": { "type": "integer", "examples": [ 600 ] }, "end_timestamp__dayofweek": { "type": "string", "examples": [ "Thursday" ] }, "event_shift_template_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_template_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_template_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_type_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_type_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_type_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "is_virtual": { "type": "string", "examples": [ "No" ] }, "minimum_age": { "type": "string", "examples": [ "" ] }, "name": { "type": "string", "examples": [ "" ] }, "no_shift_time": { "type": "string", "examples": [ "No" ] }, "post_feedback_form": { "type": [ "string", "null" ], "examples": [ null ] }, "post_feedback_form:value": { "type": [ "string", "null" ], "examples": [ null ] }, "post_feedback_form:array": { "type": [ "string", "null" ], "examples": [ null ] }, "public": { "type": "string", "examples": [ "No" ] }, "publish": { "type": "string", "examples": [ "No" ] }, "role_offer_address": { "type": "string", "examples": [ "No" ] }, "role_offer_id": { "type": [ "string", "null" ], "examples": [ null ] }, "role_offer_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "role_offer_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "self_checkin": { "type": "string", "examples": [ "No" ] }, "shift_application_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "start_timestamp": { "type": "string", "examples": [ "Sep 17, 2026, 3:00 PM" ] }, "start_timestamp__date": { "type": "string", "examples": [ "Sep 17, 2026" ] }, "start_timestamp__time": { "type": "string", "examples": [ "3:00 PM" ] }, "start_timestamp__offset": { "type": "string", "examples": [ " (+10:00 AEST)" ] }, "start_timestamp__offset_minutes": { "type": "integer", "examples": [ 600 ] }, "start_timestamp__dayofweek": { "type": "string", "examples": [ "Thursday" ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 3:36 PM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "3:36 PM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+10:00 AEST)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 600 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "visibility_hide_groups": { "type": "string", "examples": [ "" ] }, "visibility_show_groups": { "type": "string", "examples": [ "" ] }, "visibility_show_roleoffer": { "type": "string", "examples": [ "" ] }, "info": { "type": "string", "examples": [ " - " ] }, "event_shift_link_id": { "type": "integer", "examples": [ 1 ] }, "event_shift_link_repeat": { "type": "integer", "examples": [ 1 ] }, "event_shift_link_name": { "type": "string", "examples": [ "test shift link" ] }, "shift_status_default_id": { "type": "integer", "examples": [ 1 ] }, "length": { "type": "integer", "examples": [ 8 ] }, "account_id": { "type": "integer", "examples": [ 20000 ] }, "account_url": { "type": "string", "examples": [ "https://example.rosterfy.com/" ] }, "is_any_leader": { "type": "boolean", "examples": [ false ] }, "post_shift_feedback_form_completed_at": { "type": "string", "examples": [ "" ] }, "pre_checkin_form_completed_at": { "type": "string", "examples": [ "" ] }, "event_name": { "type": [ "string", "null" ], "examples": [ null ] } } }, "relations": { "type": "object", "properties": { "pivot": { "type": "object", "properties": { "event_shift_link_id": { "type": "integer", "examples": [ 3001 ] }, "event_shift_id": { "type": "integer", "examples": [ 2001 ] } } } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "apply": { "type": "boolean", "examples": [ false ] }, "apply_error": { "type": "string", "examples": [ "Shift applications not open" ] }, "apply_error_code": { "type": "string", "examples": [ "ES0056" ] }, "is_unavailable": { "type": "boolean", "examples": [ false ] }, "confirm": { "type": "boolean", "examples": [ false ] }, "reject": { "type": "boolean", "examples": [ false ] }, "selfCheckin": { "type": "boolean", "examples": [ false ] }, "selfCheckout": { "type": "boolean", "examples": [ false ] }, "submitAttendedForm": { "type": "boolean", "examples": [ false ] }, "precheckin": { "type": "boolean", "examples": [ false ] }, "applyWaitlist": { "type": "boolean", "examples": [ false ] } } }, "attributes": { "type": "array", "examples": [ [] ] } } }, "examples": [ [ { "object": { "id": 2001, "event_id": 1001, "event_shift_type_id": null, "event_shift_template_id": null, "journey_id": null, "min_demand": 10, "max_demand": 10, "leader_demand": 1, "start_timestamp": "2026-09-17 05:00:00", "end_timestamp": "2026-09-17 13:00:00", "timezone": "Australia/Melbourne", "no_shift_time": 0, "apps_open_timestamp": null, "apps_close_timestamp": null, "headcount_location_venue_id": null, "shift_confirmed_status_default": 3, "shift_rejected_status_default": 6, "journey_complete_status": null, "shift_can_withdraw_default": 1, "shift_can_confirm": 1, "shift_can_confirm_limit": 0, "shift_can_withdraw_limit": 0, "shift_checked_in_status_default": 4, "shift_checked_out_status_default": 4, "certificate_id": null, "shift_application_form_id": null, "allow_application_form_resubmit": 0, "shift_checkin_form_id": null, "shift_attended_form_id": null, "shift_checkout_form_id": null, "shift_precheckin_form_id": null, "shift_withdraw_form_id": null, "training_ids": null, "visibility_show_groups": [], "visibility_hide_groups": [], "visibility_show_roleoffer": [], "role_offer_id": null, "role_offer_address": 0, "checkin_visible_attributes": [], "shift_enable_waitlist_default": 0, "max_waitlist": 0, "group_booking_ttl": null, "max_group_demand": null, "max_group_size": null, "reserved_expiry": null, "minimum_dob": null, "minimum_age": null, "maximum_dob": null, "maximum_age": null, "self_checkin": 0, "self_checkin_open": 1800, "self_checkin_close": 1800, "self_checkout_close": 1800, "checkin_close": 0, "shift_precheckin_open": 0, "break": 0, "post_feedback_form": null, "shift_leader_feedback_form_id": null, "is_virtual": 0, "geofence_checkin_limit": null, "tax": null, "price_excluding_tax": 0, "tax_percentage": null, "publish": 0, "public": 0, "sort_order": 0, "is_cancelled": 0, "deleted_at": null, "is_erased": 0, "is_draft": false, "created_at": "2026-06-09T05:36:10.000000Z", "updated_at": "2026-06-09T05:36:10.000000Z", "deleted_by": null, "address": { "iso": "AUS", "region_code": "VIC", "coordinates": { "latitude": "-37.814000", "longitude": "144.963100" }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "Melbourne", "postcode": "3000", "region": "VIC", "country": "AU", "latitude": "-37.814000", "longitude": "144.963100" } }, "nice": { "rrn": "rrn:example:20000:shift:2001", "address": "1 Example Street\nMelbourne\nVictoria\nAustralia\n3000", "address_oneline": "1 Example Street, Melbourne, Victoria, Australia, 3000", "address.country": "Australia", "address.country:raw": "AUS", "address.city": "Melbourne", "address.region": "Victoria", "address.region:raw": "VIC", "address.postcode": "3000", "address.street_address_1": "1 Example Street", "address.street_address_2": "", "address.street_address_3": "", "address.latitude": "-37.814000", "address.longitude": "144.963100", "created_at": "Jun 9, 2026, 3:36 PM", "created_at__date": "Jun 9, 2026", "created_at__time": "3:36 PM", "created_at__offset": " (+10:00 AEST)", "created_at__offset_minutes": 600, "created_at__dayofweek": "Tuesday", "end_timestamp": "Sep 17, 2026, 11:00 PM", "end_timestamp__date": "Sep 17, 2026", "end_timestamp__time": "11:00 PM", "end_timestamp__offset": " (+10:00 AEST)", "end_timestamp__offset_minutes": 600, "end_timestamp__dayofweek": "Thursday", "event_shift_template_id": null, "event_shift_template_id:value": null, "event_shift_template_id:array": null, "event_shift_type_id": null, "event_shift_type_id:value": null, "event_shift_type_id:array": null, "headcount_location_venue_id": null, "headcount_location_venue_id:value": null, "headcount_location_venue_id:array": null, "is_virtual": "No", "minimum_age": "", "name": "", "no_shift_time": "No", "post_feedback_form": null, "post_feedback_form:value": null, "post_feedback_form:array": null, "public": "No", "publish": "No", "role_offer_address": "No", "role_offer_id": null, "role_offer_id:value": null, "role_offer_id:array": null, "self_checkin": "No", "shift_application_form_id": null, "shift_application_form_id:value": null, "shift_application_form_id:array": null, "shift_attended_form_id": null, "shift_attended_form_id:value": null, "shift_attended_form_id:array": null, "shift_checkin_form_id": null, "shift_checkin_form_id:value": null, "shift_checkin_form_id:array": null, "shift_checkout_form_id": null, "shift_checkout_form_id:value": null, "shift_checkout_form_id:array": null, "shift_precheckin_form_id": null, "shift_precheckin_form_id:value": null, "shift_precheckin_form_id:array": null, "shift_withdraw_form_id": null, "shift_withdraw_form_id:value": null, "shift_withdraw_form_id:array": null, "start_timestamp": "Sep 17, 2026, 3:00 PM", "start_timestamp__date": "Sep 17, 2026", "start_timestamp__time": "3:00 PM", "start_timestamp__offset": " (+10:00 AEST)", "start_timestamp__offset_minutes": 600, "start_timestamp__dayofweek": "Thursday", "updated_at": "Jun 9, 2026, 3:36 PM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "3:36 PM", "updated_at__offset": " (+10:00 AEST)", "updated_at__offset_minutes": 600, "updated_at__dayofweek": "Tuesday", "visibility_hide_groups": "", "visibility_show_groups": "", "visibility_show_roleoffer": "", "info": " - ", "event_shift_link_id": 1, "event_shift_link_repeat": 1, "event_shift_link_name": "test shift link", "shift_status_default_id": 1, "length": 8, "account_id": 20000, "account_url": "https://example.rosterfy.com/", "is_any_leader": false, "post_shift_feedback_form_completed_at": "", "pre_checkin_form_completed_at": "", "event_name": null }, "relations": { "pivot": { "event_shift_link_id": 3001, "event_shift_id": 2001 } }, "permissions": { "read": true, "update": true, "delete": true, "apply": false, "apply_error": "Shift applications not open", "apply_error_code": "ES0056", "is_unavailable": false, "confirm": false, "reject": false, "selfCheckin": false, "selfCheckout": false, "submitAttendedForm": false, "precheckin": false, "applyWaitlist": false }, "attributes": [] }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/event/{event}/shift/link/{link}/shift?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/event/{event}/shift/link/{link}/shift?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/event/{event}/shift/link/{link}/shift" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 2001, "event_id": 1001, "event_shift_type_id": null, "event_shift_template_id": null, "journey_id": null, "min_demand": 10, "max_demand": 10, "leader_demand": 1, "start_timestamp": "2026-09-17 05:00:00", "end_timestamp": "2026-09-17 13:00:00", "timezone": "Australia/Melbourne", "no_shift_time": 0, "apps_open_timestamp": null, "apps_close_timestamp": null, "headcount_location_venue_id": null, "shift_confirmed_status_default": 3, "shift_rejected_status_default": 6, "journey_complete_status": null, "shift_can_withdraw_default": 1, "shift_can_confirm": 1, "shift_can_confirm_limit": 0, "shift_can_withdraw_limit": 0, "shift_checked_in_status_default": 4, "shift_checked_out_status_default": 4, "certificate_id": null, "shift_application_form_id": null, "allow_application_form_resubmit": 0, "shift_checkin_form_id": null, "shift_attended_form_id": null, "shift_checkout_form_id": null, "shift_precheckin_form_id": null, "shift_withdraw_form_id": null, "training_ids": null, "visibility_show_groups": [], "visibility_hide_groups": [], "visibility_show_roleoffer": [], "role_offer_id": null, "role_offer_address": 0, "checkin_visible_attributes": [], "shift_enable_waitlist_default": 0, "max_waitlist": 0, "group_booking_ttl": null, "max_group_demand": null, "max_group_size": null, "reserved_expiry": null, "minimum_dob": null, "minimum_age": null, "maximum_dob": null, "maximum_age": null, "self_checkin": 0, "self_checkin_open": 1800, "self_checkin_close": 1800, "self_checkout_close": 1800, "checkin_close": 0, "shift_precheckin_open": 0, "break": 0, "post_feedback_form": null, "shift_leader_feedback_form_id": null, "is_virtual": 0, "geofence_checkin_limit": null, "tax": null, "price_excluding_tax": 0, "tax_percentage": null, "publish": 0, "public": 0, "sort_order": 0, "is_cancelled": 0, "deleted_at": null, "is_erased": 0, "is_draft": false, "created_at": "2026-06-09T05:36:10.000000Z", "updated_at": "2026-06-09T05:36:10.000000Z", "deleted_by": null, "address": { "iso": "AUS", "region_code": "VIC", "coordinates": { "latitude": "-37.814000", "longitude": "144.963100" }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "Melbourne", "postcode": "3000", "region": "VIC", "country": "AU", "latitude": "-37.814000", "longitude": "144.963100" } }, "nice": { "rrn": "rrn:example:20000:shift:2001", "address": "1 Example Street\nMelbourne\nVictoria\nAustralia\n3000", "address_oneline": "1 Example Street, Melbourne, Victoria, Australia, 3000", "address.country": "Australia", "address.country:raw": "AUS", "address.city": "Melbourne", "address.region": "Victoria", "address.region:raw": "VIC", "address.postcode": "3000", "address.street_address_1": "1 Example Street", "address.street_address_2": "", "address.street_address_3": "", "address.latitude": "-37.814000", "address.longitude": "144.963100", "created_at": "Jun 9, 2026, 3:36 PM", "created_at__date": "Jun 9, 2026", "created_at__time": "3:36 PM", "created_at__offset": " (+10:00 AEST)", "created_at__offset_minutes": 600, "created_at__dayofweek": "Tuesday", "end_timestamp": "Sep 17, 2026, 11:00 PM", "end_timestamp__date": "Sep 17, 2026", "end_timestamp__time": "11:00 PM", "end_timestamp__offset": " (+10:00 AEST)", "end_timestamp__offset_minutes": 600, "end_timestamp__dayofweek": "Thursday", "event_shift_template_id": null, "event_shift_template_id:value": null, "event_shift_template_id:array": null, "event_shift_type_id": null, "event_shift_type_id:value": null, "event_shift_type_id:array": null, "headcount_location_venue_id": null, "headcount_location_venue_id:value": null, "headcount_location_venue_id:array": null, "is_virtual": "No", "minimum_age": "", "name": "", "no_shift_time": "No", "post_feedback_form": null, "post_feedback_form:value": null, "post_feedback_form:array": null, "public": "No", "publish": "No", "role_offer_address": "No", "role_offer_id": null, "role_offer_id:value": null, "role_offer_id:array": null, "self_checkin": "No", "shift_application_form_id": null, "shift_application_form_id:value": null, "shift_application_form_id:array": null, "shift_attended_form_id": null, "shift_attended_form_id:value": null, "shift_attended_form_id:array": null, "shift_checkin_form_id": null, "shift_checkin_form_id:value": null, "shift_checkin_form_id:array": null, "shift_checkout_form_id": null, "shift_checkout_form_id:value": null, "shift_checkout_form_id:array": null, "shift_precheckin_form_id": null, "shift_precheckin_form_id:value": null, "shift_precheckin_form_id:array": null, "shift_withdraw_form_id": null, "shift_withdraw_form_id:value": null, "shift_withdraw_form_id:array": null, "start_timestamp": "Sep 17, 2026, 3:00 PM", "start_timestamp__date": "Sep 17, 2026", "start_timestamp__time": "3:00 PM", "start_timestamp__offset": " (+10:00 AEST)", "start_timestamp__offset_minutes": 600, "start_timestamp__dayofweek": "Thursday", "updated_at": "Jun 9, 2026, 3:36 PM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "3:36 PM", "updated_at__offset": " (+10:00 AEST)", "updated_at__offset_minutes": 600, "updated_at__dayofweek": "Tuesday", "visibility_hide_groups": "", "visibility_show_groups": "", "visibility_show_roleoffer": "", "info": " - ", "event_shift_link_id": 1, "event_shift_link_repeat": 1, "event_shift_link_name": "test shift link", "shift_status_default_id": 1, "length": 8, "account_id": 20000, "account_url": "https://example.rosterfy.com/", "is_any_leader": false, "post_shift_feedback_form_completed_at": "", "pre_checkin_form_completed_at": "", "event_name": null }, "relations": { "pivot": { "event_shift_link_id": 3001, "event_shift_id": 2001 } }, "permissions": { "read": true, "update": true, "delete": true, "apply": false, "apply_error": "Shift applications not open", "apply_error_code": "ES0056", "is_unavailable": false, "confirm": false, "reject": false, "selfCheckin": false, "selfCheckout": false, "submitAttendedForm": false, "precheckin": false, "applyWaitlist": false }, "attributes": [] }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/event/{event}/shift/link/{link}/shift?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/event/{event}/shift/link/{link}/shift?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/event/{event}/shift/link/{link}/shift", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Shift Module" ] }, "parameters": [ { "in": "path", "name": "event_id", "description": "The ID of the event.", "required": true, "schema": { "type": "integer", "examples": [ 1001 ] } }, { "in": "path", "name": "link_id", "description": "The ID of the shift link.", "required": true, "schema": { "type": "integer", "examples": [ 3001 ] } } ] }, "/api/v2/event/{event_id}/shift/link/{id}": { "get": { "summary": "Read a shift link", "operationId": "readAShiftLink", "description": "Returns one shift link. A shift link is the series a repeating shift belongs to - the\nthing that makes a run of Saturday shifts one recurring commitment rather than a dozen\nunrelated ones. It holds the names the series is known by and the pattern its shifts\nwere generated from; the shifts themselves are read from the listing below.\n\n`object` holds the stored values and `nice` the same values rendered for display.\n`permissions` says what the caller may do with this series.\n\n`rules` describes the repeat the series was built on - `days` holds the days of the week\nit covers, as integers with Sunday at `0`. `repeat` says whether the series is still\ngenerating shifts, and `end_date` when it stops.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 3001 ] }, "event_id": { "type": "integer", "examples": [ 1001 ] }, "event_shift_pattern_id": { "type": [ "string", "null" ], "examples": [ null ] }, "name": { "type": "string", "examples": [ "Saturday gate crew" ] }, "frontend_name": { "type": "string", "examples": [ "Saturday gate crew" ] }, "repeat": { "type": "integer", "examples": [ 1 ] }, "end_date": { "type": [ "string", "null" ], "examples": [ null ] }, "rules": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1, 2, 3, 4, 5, 6, 0 ] ] } } }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:10.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:10.000000Z" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 3001, "event_id": 1001, "event_shift_pattern_id": null, "name": "Saturday gate crew", "frontend_name": "Saturday gate crew", "repeat": 1, "end_date": null, "rules": { "days": [ 1, 2, 3, 4, 5, 6, 0 ] }, "created_at": "2026-06-09T05:36:10.000000Z", "updated_at": "2026-06-09T05:36:10.000000Z" }, "nice": [], "relations": [], "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Shift Module" ] }, "put": { "summary": "Update a shift link", "operationId": "updateAShiftLink", "description": "Renames a shift link and returns it. Only the two names can be changed here - the repeat\nthe series was built on is fixed once its shifts exist, and the shifts themselves are\nchanged through the shift endpoints.\n\nBoth fields are optional and an update carrying neither is accepted; send only what you\nare changing. `name` may be shortened or rewritten but not emptied - sending it as `null`\nor as more than 255 characters is a 422.\n\nThe link has to belong to the event in the URL; a mismatch is a 404.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 3001 ] }, "event_id": { "type": "integer", "examples": [ 1001 ] }, "event_shift_pattern_id": { "type": [ "string", "null" ], "examples": [ null ] }, "name": { "type": "string", "examples": [ "Saturday gate crew" ] }, "frontend_name": { "type": "string", "examples": [ "Saturday gate crew" ] }, "repeat": { "type": "integer", "examples": [ 1 ] }, "end_date": { "type": [ "string", "null" ], "examples": [ null ] }, "rules": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "integer" }, "examples": [ [ 1, 2, 3, 4, 5, 6, 0 ] ] } } }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:10.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:10.000000Z" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] } } } }, "examples": [ { "object": { "id": 3001, "event_id": 1001, "event_shift_pattern_id": null, "name": "Saturday gate crew", "frontend_name": "Saturday gate crew", "repeat": 1, "end_date": null, "rules": { "days": [ 1, 2, 3, 4, 5, 6, 0 ] }, "created_at": "2026-06-09T05:36:10.000000Z", "updated_at": "2026-06-09T05:36:10.000000Z" }, "nice": [], "relations": [], "permissions": { "read": true, "update": true, "delete": true } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Shift Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the series, as it reads to your team. Up to 255 characters, and it may not be emptied.", "examples": [ null ] }, "frontend_name": { "type": "object", "description": "The name of the series as volunteers see it, keyed by locale code - for example `{\"en-US\": \"Saturday gate crew\"}`. Only the locales you send are replaced; any others already stored are kept. A plain string is also accepted and is filed under the locale the request is being read in.", "properties": {}, "examples": [ "{}" ] } } } } } } }, "delete": { "summary": "Delete a shift link", "operationId": "deleteAShiftLink", "description": "Breaks up a series. The shifts that belonged to it are **not** deleted - they stay on the\nevent exactly as they were, and simply stop being part of a series, so anyone rostered\nonto them keeps their place.\n\nThis is a hard delete: the series cannot be restored, and rebuilding it means recreating\nthe link and its shifts.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "204": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "examples": [ {} ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Shift Module" ] }, "parameters": [ { "in": "path", "name": "event_id", "description": "The ID of the event.", "required": true, "schema": { "type": "integer", "examples": [ 1001 ] } }, { "in": "path", "name": "id", "description": "The ID of the shift link.", "required": true, "schema": { "type": "integer", "examples": [ 3001 ] } } ] }, "/api/v2/event/{event_id}/shift/{shift_id}/add-to-cart": { "post": { "summary": "Check a shift before adding it to the cart", "operationId": "checkAShiftBeforeAddingItToTheCart", "description": "Asks whether you can take this shift, given the shifts already in your cart.\nNothing is applied for and nothing is stored - this is the check the portal runs as\na shift goes into the cart, so that a shift you cannot take is refused there rather\nthan at the end.\n\nA 200 with an empty body means yes. A refusal is a 422 whose `errors` names the\nshift and says why: the shift is full, its applications are not open, it clashes\nwith something else in the cart, or you already hold a place on it.\n\nSend the cart's other shifts in `cartItems` so clashes between them and this one\nare caught. They are checked against this shift but are not themselves re-checked.\n\nApplying for the shifts once the cart is settled is a separate call - see\napply to many shifts.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "examples": [ {} ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "" ] }, "errors": { "type": "array", "items": { "type": "object", "properties": { "event_shift_id": { "type": "integer", "examples": [ 2001 ] }, "message": { "type": "string", "examples": [ "Unable to apply to this Shift" ] } } }, "examples": [ [ { "event_shift_id": 2001, "message": "Unable to apply to this Shift" } ] ] } }, "examples": [ { "message": "", "errors": [ { "event_shift_id": 2001, "message": "Unable to apply to this Shift" } ] } ] } } } } }, "tags": [ "Shift Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "cartItems": { "type": "array", "description": "The shifts already in the cart, so they are taken into account when checking whether this one can be added. Unpublished shifts and shifts outside the account are dropped from the list. The name is camelCase because that is what the endpoint reads.", "items": { "type": "integer" }, "examples": [ [] ] }, "asLeader": { "type": "boolean", "description": "Check whether the person can take this shift as its leader rather than as an ordinary place. The name is camelCase because that is what the endpoint reads.", "examples": [ true ] } } } } } } }, "parameters": [ { "in": "path", "name": "event_id", "description": "The ID of the event.", "required": true, "schema": { "type": "integer", "examples": [ 1001 ] } }, { "in": "path", "name": "shift_id", "description": "The ID of the shift being added.", "required": true, "schema": { "type": "integer", "examples": [ 2001 ] } } ] }, "/api/v2/event/{event_id}/shift/{shift_id}/cancel": { "get": { "summary": "Cancel a shift", "operationId": "cancelAShift", "description": "Calls the shift off. It is marked as cancelled, it stops being published, and\neveryone holding a place on it is moved to a cancelled status - which is what\ntriggers whatever your account has set up to tell them.\n\nThe work is queued and the response is a token for the queued job, so **nothing has\nchanged by the time it comes back**. The token is not something you can poll; read\nthe shift back to confirm. **This is a GET that changes things**, which is unusual\nfor this API and worth knowing before you put it behind a link or a prefetch.\n\nA shift can only be cancelled while it is published, has not started and is not\nalready cancelled; otherwise the call is a 404. Cancelling is not deleting - the\nshift stays, and it can be un-cancelled afterwards.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "queue": { "type": "string", "examples": [ "qRVHdJcK2U9ZFMVUBEdqsdVt" ] } }, "examples": [ { "queue": "qRVHdJcK2U9ZFMVUBEdqsdVt" } ] } } } } }, "tags": [ "Shift Module" ] }, "parameters": [ { "in": "path", "name": "event_id", "description": "The ID of the event.", "required": true, "schema": { "type": "integer", "examples": [ 1001 ] } }, { "in": "path", "name": "shift_id", "description": "The ID of the shift to cancel.", "required": true, "schema": { "type": "integer", "examples": [ 2001 ] } } ] }, "/api/v2/event/{event_id}/shift": { "put": { "summary": "Update many shifts at once", "operationId": "updateManyShiftsAtOnce", "description": "Queues the work of applying one set of changes to many shifts and returns a token\nfor the queued job. **Nothing has changed by the time the response comes back**,\nand the token is not something you can poll - read the shifts back to confirm.\n\nChoose the shifts with `applyTo`: `selected` acts on the ids in `selected`,\nanything else acts on every shift in the event, narrowed by `filter` if one is\nsent. `applyTo` is required and a request without it is a 422.\n\nEvery other field is a value to set on each shift, and takes the same shapes as on\na single update. Two suffixes change how a field is treated: `:use_default`\nas true drops that field from the update and leaves each shift's own value alone,\nand `:override` as true replaces a value a shift's template locks, for a\ncaller allowed to override locked fields. Shifts the caller cannot update are\nskipped, as are shifts whose own validation refuses the change; neither is\nreported back.\n\n**This endpoint also accepts file uploads**, for the fields that hold one - send\nthe request as `multipart/form-data` with the file under the field's own name and\nthe rest of the fields alongside it, and the field is set to the URL the file was\nstored at. The body is documented as JSON below because an operation carries one\ncontent type and JSON is the common case; the multipart form takes the same fields.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "queue": { "type": "string", "examples": [ "vqWN9bLNDXJKR4jSnf5efYTc" ] } }, "examples": [ { "queue": "vqWN9bLNDXJKR4jSnf5efYTc" } ] } } } } }, "tags": [ "Shift Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "What the shift is called. Shown to people choosing shifts.", "examples": [ null ] }, "timezone": { "type": "string", "description": "The timezone the start and end times are given in, as an IANA name such as `Australia/Melbourne`.", "examples": [ null ] }, "min_demand": { "type": "integer", "description": "The fewest people the shift needs. Defaults to 1.", "examples": [ 1 ] }, "max_demand": { "type": "integer", "description": "The most people the shift can take. Applications are refused once it is full.", "examples": [ 1 ] }, "leader_demand": { "type": "integer", "description": "How many of those places are for leaders. Defaults to 0.", "examples": [ 1 ] }, "start_timestamp": { "type": "string", "description": "When the shift starts, as `YYYY-MM-DD HH:MM:SS` in the shift's timezone.", "examples": [ null ] }, "end_timestamp": { "type": "string", "description": "When the shift ends, as `YYYY-MM-DD HH:MM:SS` in the shift's timezone.", "examples": [ null ] }, "is_virtual": { "type": "boolean", "description": "Whether the shift happens online rather than at a place.", "examples": [ true ] }, "event_shift_type_id": { "type": "integer", "description": "The shift type, which groups shifts for reporting and for the per-type application limits an event can set.", "examples": [ 1 ] }, "shift_status_default": { "type": "integer", "description": "The status a new application on this shift starts at.", "examples": [ 1 ] }, "shift_confirmed_status_default": { "type": "integer", "description": "The status an application moves to when it is confirmed.", "examples": [ 1 ] }, "shift_rejected_status_default": { "type": "integer", "description": "The status an application moves to when it is rejected.", "examples": [ 1 ] }, "shift_can_withdraw_default": { "type": "boolean", "description": "Whether people can withdraw from the shift themselves.", "examples": [ true ] }, "shift_can_withdraw_limit": { "type": "integer", "description": "How long before the shift starts withdrawing stops being allowed, in seconds.", "examples": [ 1 ] }, "shift_can_confirm": { "type": "boolean", "description": "Whether people can confirm their own place on the shift.", "examples": [ true ] }, "shift_can_confirm_limit": { "type": "integer", "description": "How long before the shift starts confirming stops being allowed, in seconds.", "examples": [ 1 ] }, "shift_checked_in_status_default": { "type": "integer", "description": "The status an assignment moves to on check-in.", "examples": [ 1 ] }, "shift_checked_out_status_default": { "type": "integer", "description": "The status an assignment moves to on check-out.", "examples": [ 1 ] }, "address": { "type": "object", "description": "Where the shift happens, as an address object. Required on a create unless the shift is virtual or takes its location from a venue.", "properties": { "street_address_1": { "type": "string", "description": "", "examples": [ null ] }, "street_address_2": { "type": "string", "description": "", "examples": [ null ] }, "street_address_3": { "type": "string", "description": "", "examples": [ null ] }, "city": { "type": "string", "description": "", "examples": [ null ] }, "postcode": { "type": "string", "description": "", "examples": [ null ] }, "region": { "type": "string", "description": "", "examples": [ null ] }, "country": { "type": "string", "description": "", "examples": [ null ] }, "latitude": { "type": "string", "description": "", "examples": [ null ] }, "longitude": { "type": "string", "description": "", "examples": [ null ] } }, "examples": [ "{}" ] }, "headcount_location_venue_id": { "type": "integer", "description": "The venue the shift happens at. Sending one takes the location from the venue instead of from `address`.", "examples": [ 1 ] }, "certificate_id": { "type": "integer", "description": "A certificate awarded for attending the shift.", "examples": [ 1 ] }, "shift_application_form_id": { "type": "integer", "description": "The form someone fills in when applying for this shift.", "examples": [ 1 ] }, "allow_application_form_resubmit": { "type": "boolean", "description": "Whether someone can submit the application form again.", "examples": [ true ] }, "shift_precheckin_form_id": { "type": "integer", "description": "The form filled in at pre-check-in.", "examples": [ 1 ] }, "shift_checkin_form_id": { "type": "integer", "description": "The form filled in at check-in.", "examples": [ 1 ] }, "shift_attended_form_id": { "type": "integer", "description": "The form filled in once the shift has been attended.", "examples": [ 1 ] }, "shift_checkout_form_id": { "type": "integer", "description": "The form filled in at check-out.", "examples": [ 1 ] }, "shift_withdraw_form_id": { "type": "integer", "description": "The form filled in when withdrawing.", "examples": [ 1 ] }, "visibility_show_groups": { "type": "array", "description": "Only members of these groups can see the shift.", "items": { "type": "integer" }, "examples": [ [] ] }, "visibility_hide_groups": { "type": "array", "description": "Members of these groups cannot see the shift.", "items": { "type": "integer" }, "examples": [ [] ] }, "visibility_show_roleoffer": { "type": "array", "description": "Only people holding one of these role offers can see the shift.", "items": { "type": "integer" }, "examples": [ [] ] }, "apps_open_timestamp": { "type": "string", "description": "When applications open. Before this, applying is refused.", "examples": [ null ] }, "apps_close_timestamp": { "type": "string", "description": "When applications close. After this, applying is refused.", "examples": [ null ] }, "role_offer_id": { "type": "integer", "description": "The role offer this shift belongs to.", "examples": [ 1 ] }, "role_offer_address": { "type": "boolean", "description": "Take the shift's location from the role offer rather than from `address`.", "examples": [ true ] }, "shift_precheckin_open": { "type": "integer", "description": "How long before the shift starts pre-check-in opens, in seconds.", "examples": [ 1 ] }, "max_group_demand": { "type": "integer", "description": "How many places a single group booking can take.", "examples": [ 1 ] }, "group_booking_ttl": { "type": "integer", "description": "How long a group booking is held before it lapses, in seconds.", "examples": [ 1 ] }, "max_group_size": { "type": "integer", "description": "The largest group that can book onto the shift.", "examples": [ 1 ] }, "reserved_expiry": { "type": "integer", "description": "How long a reserved place is held before it lapses, in seconds.", "examples": [ 1 ] }, "self_checkin": { "type": "boolean", "description": "Whether people can check themselves in to the shift.", "examples": [ true ] }, "self_checkin_open": { "type": "integer", "description": "How long before the shift starts self check-in opens, in seconds.", "examples": [ 1 ] }, "self_checkin_close": { "type": "integer", "description": "How long after the shift starts self check-in closes, in seconds.", "examples": [ 1 ] }, "self_checkout_close": { "type": "integer", "description": "How long after the shift ends self check-out closes, in seconds.", "examples": [ 1 ] }, "checkin_close": { "type": "integer", "description": "How long after the shift ends check-in closes, in seconds.", "examples": [ 1 ] }, "geofence_checkin_limit": { "type": "integer", "description": "How close to the shift's location someone has to be to check in, in metres.", "examples": [ 1 ] }, "checkin_visible_attributes": { "type": "array", "description": "Which of a person's attributes are shown on the check-in screen.", "items": { "type": "integer" }, "examples": [ [] ] }, "training_ids": { "type": "array", "description": "Training people must have completed before they can be placed on the shift.", "items": { "type": "integer" }, "examples": [ [] ] }, "post_feedback_form": { "type": "integer", "description": "The form people fill in about the shift afterwards.", "examples": [ 1 ] }, "shift_leader_feedback_form_id": { "type": "integer", "description": "The form a leader fills in about the shift.", "examples": [ 1 ] }, "shift_enable_waitlist_default": { "type": "boolean", "description": "Whether people can join a waitlist once the shift is full.", "examples": [ true ] }, "max_waitlist": { "type": "integer", "description": "How many people the waitlist holds.", "examples": [ 1 ] }, "publish": { "type": "boolean", "description": "Whether the shift is visible to people who can apply for it. Ignored from a caller who cannot publish shifts.", "examples": [ true ] }, "public": { "type": "boolean", "description": "Whether the shift can be seen without signing in, on a public event.", "examples": [ true ] }, "is_cancelled": { "type": "boolean", "description": "Whether the shift is cancelled. Cancelling this way does not move anyone already on the shift; use the cancel endpoint for that.", "examples": [ true ] }, "sort_order": { "type": "integer", "description": "Where the shift sits when shifts are shown in a fixed order.", "examples": [ 1 ] }, "minimum_dob": { "type": "string", "description": "Latest date of birth allowed on the shift. Cannot be sent together with `minimum_age`.", "examples": [ null ] }, "minimum_age": { "type": "string", "description": "Youngest age allowed on the shift, as `years:months`.", "examples": [ null ] }, "maximum_dob": { "type": "string", "description": "Earliest date of birth allowed on the shift. Cannot be sent together with `maximum_age`.", "examples": [ null ] }, "maximum_age": { "type": "string", "description": "Oldest age allowed on the shift, as `years:months`.", "examples": [ null ] }, "price_excluding_tax": { "type": "number", "description": "What taking this shift costs the person, before tax.", "examples": [ 1.23 ] }, "tax_percentage": { "type": "integer", "description": "Tax charged on the price, as a percentage between 0 and 100.", "examples": [ 1 ] }, "cost_description": { "type": "string", "description": "Free text shown alongside the price.", "examples": [ null ] }, "applyTo": { "type": "string", "description": "Send `selected` to act only on the shifts named in `selected`. Any other value acts on every shift the caller can see, narrowed by `filter` if one is sent, and narrowed to the event in the URL. Required, but the value is not checked against a list, so a typo is accepted and treated as \"everything\".", "examples": [ null ] }, "selected": { "type": "array", "description": "The IDs of the shifts to update. Required in practice when `applyTo` is `selected`, but nothing validates that: omitting it still returns a queue token and the background work then does nothing.", "items": { "type": "integer" }, "examples": [ [] ] }, "filter": { "type": "object", "description": "The same filter object the listing takes, used to choose the shifts to act on when `applyTo` is not `selected`.", "properties": {}, "examples": [ "{}" ] }, "custom_*": { "type": "string", "description": "A custom attribute, named by its code - custom_shirt_size, for example. The value follows the attribute's own type, so it may be a string, a number, a boolean or a list. See the custom attributes documentation.", "examples": [ null ] } }, "required": [ "applyTo" ] } } } } }, "get": { "summary": "List an event's shifts", "operationId": "listAnEventsShifts", "description": "Returns the shifts belonging to one event, with the demand figures for each and\nwhat the caller is allowed to do with it.\n\nA shift is a block of time on an event that people are rostered onto. `min_demand`\nand `max_demand` are how many people it needs and how many it can take,\n`leader_demand` how many of those places are for leaders. The rows carry those\nfigures and the shift's own settings; they carry nobody's name. To see who is on a\nshift, read its assignments.\n\nThe response is only wrapped in a paginated envelope when a `page` parameter is\nsent. Without one, every match comes back as a flat array. The envelope carries no\n`total` and no `last_page` - page until `next_page_url` is null rather than\ncounting pages up front.\n\n**This listing can be read without signing in**, and it is the only endpoint in\nthis group that can. Without a token it returns the published, public shifts of a\npublic, published event and nothing else; a signed-in caller who cannot read\nshifts gets the same narrowing.", "parameters": [ { "in": "query", "name": "applied", "description": "Keep only shifts the signed-in person has applied for.", "required": false, "schema": { "type": "boolean", "description": "Keep only shifts the signed-in person has applied for.", "examples": [ true ] } }, { "in": "query", "name": "accepted", "description": "Keep only shifts the signed-in person holds a place on.", "required": false, "schema": { "type": "boolean", "description": "Keep only shifts the signed-in person holds a place on.", "examples": [ true ] } }, { "in": "query", "name": "leader", "description": "Keep only shifts the signed-in person leads.", "required": false, "schema": { "type": "boolean", "description": "Keep only shifts the signed-in person leads.", "examples": [ true ] } }, { "in": "query", "name": "notOnShift", "description": "Keep only shifts the signed-in person is not already\non. Named in camelCase because that is what the endpoint reads.", "required": false, "schema": { "type": "boolean", "description": "Keep only shifts the signed-in person is not already\non. Named in camelCase because that is what the endpoint reads.", "examples": [ true ] } }, { "in": "query", "name": "noLinkedShifts", "description": "Keep only shifts that do not belong to a linked\nseries. Named in camelCase because that is what the endpoint reads.", "required": false, "schema": { "type": "boolean", "description": "Keep only shifts that do not belong to a linked\nseries. Named in camelCase because that is what the endpoint reads.", "examples": [ true ] } }, { "in": "query", "name": "eventEoi", "description": "Keep only shifts on events the signed-in person has\nregistered interest in. Named in camelCase because that is what the endpoint reads.", "required": false, "schema": { "type": "boolean", "description": "Keep only shifts on events the signed-in person has\nregistered interest in. Named in camelCase because that is what the endpoint reads.", "examples": [ true ] } }, { "in": "query", "name": "intentToSwap", "description": "Work out each shift's `permissions.apply` as though\nthe person were swapping out of a shift they already hold, rather than taking an\nextra one. Named in camelCase because that is what the endpoint reads.", "required": false, "schema": { "type": "boolean", "description": "Work out each shift's `permissions.apply` as though\nthe person were swapping out of a shift they already hold, rather than taking an\nextra one. Named in camelCase because that is what the endpoint reads.", "examples": [ true ] } }, { "in": "query", "name": "currentId", "description": "The shift being swapped out of, used with\n`intentToSwap`. Named in camelCase because that is what the endpoint reads.", "required": false, "schema": { "type": "integer", "description": "The shift being swapped out of, used with\n`intentToSwap`. Named in camelCase because that is what the endpoint reads.", "examples": [ 2001 ] } }, { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "query", "name": "extras", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "required": false, "schema": { "type": "array", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "items": { "type": "string", "enum": [ "group_stats", "stats", "upcoming_shift_attributes", "certificate_stats" ] }, "examples": [ [ "group_stats" ] ] } }, { "in": "query", "name": "with", "description": "A list of relations to include in the response. May be single records or collections.\nIt is often more efficient to retrieve this way, to avoid follow-up API calls.", "required": false, "schema": { "type": "array", "description": "A list of relations to include in the response. May be single records or collections.\nIt is often more efficient to retrieve this way, to avoid follow-up API calls.", "items": { "type": "string", "enum": [ "location_type", "hasManyDeepFromRelationsWithConstraints", "hasOneDeepFromRelationsWithConstraints", "hasManyDeepFromReverse", "hasOneDeepFromReverse" ] }, "examples": [ [ "location_type" ] ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 2001 ] }, "event_id": { "type": "integer", "examples": [ 1001 ] }, "event_shift_type_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_template_id": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_id": { "type": [ "string", "null" ], "examples": [ null ] }, "min_demand": { "type": "integer", "examples": [ 10 ] }, "max_demand": { "type": "integer", "examples": [ 10 ] }, "leader_demand": { "type": "integer", "examples": [ 1 ] }, "start_timestamp": { "type": "string", "examples": [ "2026-09-17 05:00:00" ] }, "end_timestamp": { "type": "string", "examples": [ "2026-09-17 13:00:00" ] }, "timezone": { "type": "string", "examples": [ "Australia/Melbourne" ] }, "no_shift_time": { "type": "integer", "examples": [ 0 ] }, "apps_open_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "apps_close_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_confirmed_status_default": { "type": "integer", "examples": [ 3 ] }, "shift_rejected_status_default": { "type": "integer", "examples": [ 6 ] }, "journey_complete_status": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_can_withdraw_default": { "type": "integer", "examples": [ 1 ] }, "shift_can_confirm": { "type": "integer", "examples": [ 1 ] }, "shift_can_confirm_limit": { "type": "integer", "examples": [ 0 ] }, "shift_can_withdraw_limit": { "type": "integer", "examples": [ 0 ] }, "shift_checked_in_status_default": { "type": "integer", "examples": [ 4 ] }, "shift_checked_out_status_default": { "type": "integer", "examples": [ 4 ] }, "certificate_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "allow_application_form_resubmit": { "type": "integer", "examples": [ 0 ] }, "shift_checkin_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "training_ids": { "type": [ "string", "null" ], "examples": [ null ] }, "visibility_show_groups": { "type": "array", "examples": [ [] ] }, "visibility_hide_groups": { "type": "array", "examples": [ [] ] }, "visibility_show_roleoffer": { "type": "array", "examples": [ [] ] }, "role_offer_id": { "type": [ "string", "null" ], "examples": [ null ] }, "role_offer_address": { "type": "integer", "examples": [ 0 ] }, "checkin_visible_attributes": { "type": "array", "examples": [ [] ] }, "shift_enable_waitlist_default": { "type": "integer", "examples": [ 0 ] }, "max_waitlist": { "type": "integer", "examples": [ 0 ] }, "group_booking_ttl": { "type": [ "string", "null" ], "examples": [ null ] }, "max_group_demand": { "type": [ "string", "null" ], "examples": [ null ] }, "max_group_size": { "type": [ "string", "null" ], "examples": [ null ] }, "reserved_expiry": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "self_checkin": { "type": "integer", "examples": [ 0 ] }, "self_checkin_open": { "type": "integer", "examples": [ 1800 ] }, "self_checkin_close": { "type": "integer", "examples": [ 1800 ] }, "self_checkout_close": { "type": "integer", "examples": [ 1800 ] }, "checkin_close": { "type": "integer", "examples": [ 0 ] }, "shift_precheckin_open": { "type": "integer", "examples": [ 0 ] }, "break": { "type": "integer", "examples": [ 0 ] }, "post_feedback_form": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_leader_feedback_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "is_virtual": { "type": "integer", "examples": [ 0 ] }, "geofence_checkin_limit": { "type": [ "string", "null" ], "examples": [ null ] }, "tax": { "type": [ "string", "null" ], "examples": [ null ] }, "price_excluding_tax": { "type": "integer", "examples": [ 0 ] }, "tax_percentage": { "type": [ "string", "null" ], "examples": [ null ] }, "publish": { "type": "integer", "examples": [ 0 ] }, "public": { "type": "integer", "examples": [ 0 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "is_cancelled": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "is_draft": { "type": "boolean", "examples": [ false ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:10.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:10.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "address": { "type": "object", "properties": { "iso": { "type": "string", "examples": [ "AUS" ] }, "region_code": { "type": "string", "examples": [ "VIC" ] }, "coordinates": { "type": "object", "properties": { "latitude": { "type": "string", "examples": [ "-37.814000" ] }, "longitude": { "type": "string", "examples": [ "144.963100" ] } } }, "street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "city": { "type": "string", "examples": [ "Melbourne" ] }, "postcode": { "type": "string", "examples": [ "3000" ] }, "region": { "type": "string", "examples": [ "VIC" ] }, "country": { "type": "string", "examples": [ "AU" ] }, "latitude": { "type": "string", "examples": [ "-37.814000" ] }, "longitude": { "type": "string", "examples": [ "144.963100" ] } } } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:example:20000:shift:2001" ] }, "address": { "type": "string", "examples": [ "1 Example Street\nMelbourne\nVictoria\nAustralia\n3000" ] }, "address_oneline": { "type": "string", "examples": [ "1 Example Street, Melbourne, Victoria, Australia, 3000" ] }, "address.country": { "type": "string", "examples": [ "Australia" ] }, "address.country:raw": { "type": "string", "examples": [ "AUS" ] }, "address.city": { "type": "string", "examples": [ "Melbourne" ] }, "address.region": { "type": "string", "examples": [ "Victoria" ] }, "address.region:raw": { "type": "string", "examples": [ "VIC" ] }, "address.postcode": { "type": "string", "examples": [ "3000" ] }, "address.street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "address.street_address_2": { "type": "string", "examples": [ "" ] }, "address.street_address_3": { "type": "string", "examples": [ "" ] }, "address.latitude": { "type": "string", "examples": [ "-37.814000" ] }, "address.longitude": { "type": "string", "examples": [ "144.963100" ] }, "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 3:36 PM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "3:36 PM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+10:00 AEST)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 600 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "end_timestamp": { "type": "string", "examples": [ "Sep 17, 2026, 11:00 PM" ] }, "end_timestamp__date": { "type": "string", "examples": [ "Sep 17, 2026" ] }, "end_timestamp__time": { "type": "string", "examples": [ "11:00 PM" ] }, "end_timestamp__offset": { "type": "string", "examples": [ " (+10:00 AEST)" ] }, "end_timestamp__offset_minutes": { "type": "integer", "examples": [ 600 ] }, "end_timestamp__dayofweek": { "type": "string", "examples": [ "Thursday" ] }, "event_shift_template_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_template_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_template_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_type_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_type_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_type_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "is_virtual": { "type": "string", "examples": [ "No" ] }, "minimum_age": { "type": "string", "examples": [ "" ] }, "name": { "type": "string", "examples": [ "" ] }, "no_shift_time": { "type": "string", "examples": [ "No" ] }, "post_feedback_form": { "type": [ "string", "null" ], "examples": [ null ] }, "post_feedback_form:value": { "type": [ "string", "null" ], "examples": [ null ] }, "post_feedback_form:array": { "type": [ "string", "null" ], "examples": [ null ] }, "public": { "type": "string", "examples": [ "No" ] }, "publish": { "type": "string", "examples": [ "No" ] }, "role_offer_address": { "type": "string", "examples": [ "No" ] }, "role_offer_id": { "type": [ "string", "null" ], "examples": [ null ] }, "role_offer_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "role_offer_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "self_checkin": { "type": "string", "examples": [ "No" ] }, "shift_application_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "start_timestamp": { "type": "string", "examples": [ "Sep 17, 2026, 3:00 PM" ] }, "start_timestamp__date": { "type": "string", "examples": [ "Sep 17, 2026" ] }, "start_timestamp__time": { "type": "string", "examples": [ "3:00 PM" ] }, "start_timestamp__offset": { "type": "string", "examples": [ " (+10:00 AEST)" ] }, "start_timestamp__offset_minutes": { "type": "integer", "examples": [ 600 ] }, "start_timestamp__dayofweek": { "type": "string", "examples": [ "Thursday" ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 3:36 PM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "3:36 PM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+10:00 AEST)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 600 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "visibility_hide_groups": { "type": "string", "examples": [ "" ] }, "visibility_show_groups": { "type": "string", "examples": [ "" ] }, "visibility_show_roleoffer": { "type": "string", "examples": [ "" ] }, "info": { "type": "string", "examples": [ " - " ] }, "event_shift_link_id": { "type": "integer", "examples": [ 1 ] }, "event_shift_link_repeat": { "type": "integer", "examples": [ 1 ] }, "event_shift_link_name": { "type": "string", "examples": [ "test shift link" ] }, "shift_status_default_id": { "type": "integer", "examples": [ 1 ] }, "length": { "type": "integer", "examples": [ 8 ] }, "account_id": { "type": "integer", "examples": [ 20000 ] }, "account_url": { "type": "string", "examples": [ "https://example.rosterfy.com/" ] }, "is_any_leader": { "type": "boolean", "examples": [ false ] }, "post_shift_feedback_form_completed_at": { "type": "string", "examples": [ "" ] }, "pre_checkin_form_completed_at": { "type": "string", "examples": [ "" ] }, "event_name": { "type": [ "string", "null" ], "examples": [ null ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "apply": { "type": "boolean", "examples": [ false ] }, "apply_error": { "type": "string", "examples": [ "Shift applications not open" ] }, "apply_error_code": { "type": "string", "examples": [ "ES0056" ] }, "is_unavailable": { "type": "boolean", "examples": [ false ] }, "confirm": { "type": "boolean", "examples": [ false ] }, "reject": { "type": "boolean", "examples": [ false ] }, "selfCheckin": { "type": "boolean", "examples": [ false ] }, "selfCheckout": { "type": "boolean", "examples": [ false ] }, "submitAttendedForm": { "type": "boolean", "examples": [ false ] }, "precheckin": { "type": "boolean", "examples": [ false ] }, "applyWaitlist": { "type": "boolean", "examples": [ false ] } } }, "attributes": { "type": "array", "examples": [ [] ] } } }, "examples": [ [ { "object": { "id": 2001, "event_id": 1001, "event_shift_type_id": null, "event_shift_template_id": null, "journey_id": null, "min_demand": 10, "max_demand": 10, "leader_demand": 1, "start_timestamp": "2026-09-17 05:00:00", "end_timestamp": "2026-09-17 13:00:00", "timezone": "Australia/Melbourne", "no_shift_time": 0, "apps_open_timestamp": null, "apps_close_timestamp": null, "headcount_location_venue_id": null, "shift_confirmed_status_default": 3, "shift_rejected_status_default": 6, "journey_complete_status": null, "shift_can_withdraw_default": 1, "shift_can_confirm": 1, "shift_can_confirm_limit": 0, "shift_can_withdraw_limit": 0, "shift_checked_in_status_default": 4, "shift_checked_out_status_default": 4, "certificate_id": null, "shift_application_form_id": null, "allow_application_form_resubmit": 0, "shift_checkin_form_id": null, "shift_attended_form_id": null, "shift_checkout_form_id": null, "shift_precheckin_form_id": null, "shift_withdraw_form_id": null, "training_ids": null, "visibility_show_groups": [], "visibility_hide_groups": [], "visibility_show_roleoffer": [], "role_offer_id": null, "role_offer_address": 0, "checkin_visible_attributes": [], "shift_enable_waitlist_default": 0, "max_waitlist": 0, "group_booking_ttl": null, "max_group_demand": null, "max_group_size": null, "reserved_expiry": null, "minimum_dob": null, "minimum_age": null, "maximum_dob": null, "maximum_age": null, "self_checkin": 0, "self_checkin_open": 1800, "self_checkin_close": 1800, "self_checkout_close": 1800, "checkin_close": 0, "shift_precheckin_open": 0, "break": 0, "post_feedback_form": null, "shift_leader_feedback_form_id": null, "is_virtual": 0, "geofence_checkin_limit": null, "tax": null, "price_excluding_tax": 0, "tax_percentage": null, "publish": 0, "public": 0, "sort_order": 0, "is_cancelled": 0, "deleted_at": null, "is_erased": 0, "is_draft": false, "created_at": "2026-06-09T05:36:10.000000Z", "updated_at": "2026-06-09T05:36:10.000000Z", "deleted_by": null, "address": { "iso": "AUS", "region_code": "VIC", "coordinates": { "latitude": "-37.814000", "longitude": "144.963100" }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "Melbourne", "postcode": "3000", "region": "VIC", "country": "AU", "latitude": "-37.814000", "longitude": "144.963100" } }, "nice": { "rrn": "rrn:example:20000:shift:2001", "address": "1 Example Street\nMelbourne\nVictoria\nAustralia\n3000", "address_oneline": "1 Example Street, Melbourne, Victoria, Australia, 3000", "address.country": "Australia", "address.country:raw": "AUS", "address.city": "Melbourne", "address.region": "Victoria", "address.region:raw": "VIC", "address.postcode": "3000", "address.street_address_1": "1 Example Street", "address.street_address_2": "", "address.street_address_3": "", "address.latitude": "-37.814000", "address.longitude": "144.963100", "created_at": "Jun 9, 2026, 3:36 PM", "created_at__date": "Jun 9, 2026", "created_at__time": "3:36 PM", "created_at__offset": " (+10:00 AEST)", "created_at__offset_minutes": 600, "created_at__dayofweek": "Tuesday", "end_timestamp": "Sep 17, 2026, 11:00 PM", "end_timestamp__date": "Sep 17, 2026", "end_timestamp__time": "11:00 PM", "end_timestamp__offset": " (+10:00 AEST)", "end_timestamp__offset_minutes": 600, "end_timestamp__dayofweek": "Thursday", "event_shift_template_id": null, "event_shift_template_id:value": null, "event_shift_template_id:array": null, "event_shift_type_id": null, "event_shift_type_id:value": null, "event_shift_type_id:array": null, "headcount_location_venue_id": null, "headcount_location_venue_id:value": null, "headcount_location_venue_id:array": null, "is_virtual": "No", "minimum_age": "", "name": "", "no_shift_time": "No", "post_feedback_form": null, "post_feedback_form:value": null, "post_feedback_form:array": null, "public": "No", "publish": "No", "role_offer_address": "No", "role_offer_id": null, "role_offer_id:value": null, "role_offer_id:array": null, "self_checkin": "No", "shift_application_form_id": null, "shift_application_form_id:value": null, "shift_application_form_id:array": null, "shift_attended_form_id": null, "shift_attended_form_id:value": null, "shift_attended_form_id:array": null, "shift_checkin_form_id": null, "shift_checkin_form_id:value": null, "shift_checkin_form_id:array": null, "shift_checkout_form_id": null, "shift_checkout_form_id:value": null, "shift_checkout_form_id:array": null, "shift_precheckin_form_id": null, "shift_precheckin_form_id:value": null, "shift_precheckin_form_id:array": null, "shift_withdraw_form_id": null, "shift_withdraw_form_id:value": null, "shift_withdraw_form_id:array": null, "start_timestamp": "Sep 17, 2026, 3:00 PM", "start_timestamp__date": "Sep 17, 2026", "start_timestamp__time": "3:00 PM", "start_timestamp__offset": " (+10:00 AEST)", "start_timestamp__offset_minutes": 600, "start_timestamp__dayofweek": "Thursday", "updated_at": "Jun 9, 2026, 3:36 PM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "3:36 PM", "updated_at__offset": " (+10:00 AEST)", "updated_at__offset_minutes": 600, "updated_at__dayofweek": "Tuesday", "visibility_hide_groups": "", "visibility_show_groups": "", "visibility_show_roleoffer": "", "info": " - ", "event_shift_link_id": 1, "event_shift_link_repeat": 1, "event_shift_link_name": "test shift link", "shift_status_default_id": 1, "length": 8, "account_id": 20000, "account_url": "https://example.rosterfy.com/", "is_any_leader": false, "post_shift_feedback_form_completed_at": "", "pre_checkin_form_completed_at": "", "event_name": null }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "apply": false, "apply_error": "Shift applications not open", "apply_error_code": "ES0056", "is_unavailable": false, "confirm": false, "reject": false, "selfCheckin": false, "selfCheckout": false, "submitAttendedForm": false, "precheckin": false, "applyWaitlist": false }, "attributes": [] }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/event/{event}/shift?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/event/{event}/shift?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/event/{event}/shift" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 2001, "event_id": 1001, "event_shift_type_id": null, "event_shift_template_id": null, "journey_id": null, "min_demand": 10, "max_demand": 10, "leader_demand": 1, "start_timestamp": "2026-09-17 05:00:00", "end_timestamp": "2026-09-17 13:00:00", "timezone": "Australia/Melbourne", "no_shift_time": 0, "apps_open_timestamp": null, "apps_close_timestamp": null, "headcount_location_venue_id": null, "shift_confirmed_status_default": 3, "shift_rejected_status_default": 6, "journey_complete_status": null, "shift_can_withdraw_default": 1, "shift_can_confirm": 1, "shift_can_confirm_limit": 0, "shift_can_withdraw_limit": 0, "shift_checked_in_status_default": 4, "shift_checked_out_status_default": 4, "certificate_id": null, "shift_application_form_id": null, "allow_application_form_resubmit": 0, "shift_checkin_form_id": null, "shift_attended_form_id": null, "shift_checkout_form_id": null, "shift_precheckin_form_id": null, "shift_withdraw_form_id": null, "training_ids": null, "visibility_show_groups": [], "visibility_hide_groups": [], "visibility_show_roleoffer": [], "role_offer_id": null, "role_offer_address": 0, "checkin_visible_attributes": [], "shift_enable_waitlist_default": 0, "max_waitlist": 0, "group_booking_ttl": null, "max_group_demand": null, "max_group_size": null, "reserved_expiry": null, "minimum_dob": null, "minimum_age": null, "maximum_dob": null, "maximum_age": null, "self_checkin": 0, "self_checkin_open": 1800, "self_checkin_close": 1800, "self_checkout_close": 1800, "checkin_close": 0, "shift_precheckin_open": 0, "break": 0, "post_feedback_form": null, "shift_leader_feedback_form_id": null, "is_virtual": 0, "geofence_checkin_limit": null, "tax": null, "price_excluding_tax": 0, "tax_percentage": null, "publish": 0, "public": 0, "sort_order": 0, "is_cancelled": 0, "deleted_at": null, "is_erased": 0, "is_draft": false, "created_at": "2026-06-09T05:36:10.000000Z", "updated_at": "2026-06-09T05:36:10.000000Z", "deleted_by": null, "address": { "iso": "AUS", "region_code": "VIC", "coordinates": { "latitude": "-37.814000", "longitude": "144.963100" }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "Melbourne", "postcode": "3000", "region": "VIC", "country": "AU", "latitude": "-37.814000", "longitude": "144.963100" } }, "nice": { "rrn": "rrn:example:20000:shift:2001", "address": "1 Example Street\nMelbourne\nVictoria\nAustralia\n3000", "address_oneline": "1 Example Street, Melbourne, Victoria, Australia, 3000", "address.country": "Australia", "address.country:raw": "AUS", "address.city": "Melbourne", "address.region": "Victoria", "address.region:raw": "VIC", "address.postcode": "3000", "address.street_address_1": "1 Example Street", "address.street_address_2": "", "address.street_address_3": "", "address.latitude": "-37.814000", "address.longitude": "144.963100", "created_at": "Jun 9, 2026, 3:36 PM", "created_at__date": "Jun 9, 2026", "created_at__time": "3:36 PM", "created_at__offset": " (+10:00 AEST)", "created_at__offset_minutes": 600, "created_at__dayofweek": "Tuesday", "end_timestamp": "Sep 17, 2026, 11:00 PM", "end_timestamp__date": "Sep 17, 2026", "end_timestamp__time": "11:00 PM", "end_timestamp__offset": " (+10:00 AEST)", "end_timestamp__offset_minutes": 600, "end_timestamp__dayofweek": "Thursday", "event_shift_template_id": null, "event_shift_template_id:value": null, "event_shift_template_id:array": null, "event_shift_type_id": null, "event_shift_type_id:value": null, "event_shift_type_id:array": null, "headcount_location_venue_id": null, "headcount_location_venue_id:value": null, "headcount_location_venue_id:array": null, "is_virtual": "No", "minimum_age": "", "name": "", "no_shift_time": "No", "post_feedback_form": null, "post_feedback_form:value": null, "post_feedback_form:array": null, "public": "No", "publish": "No", "role_offer_address": "No", "role_offer_id": null, "role_offer_id:value": null, "role_offer_id:array": null, "self_checkin": "No", "shift_application_form_id": null, "shift_application_form_id:value": null, "shift_application_form_id:array": null, "shift_attended_form_id": null, "shift_attended_form_id:value": null, "shift_attended_form_id:array": null, "shift_checkin_form_id": null, "shift_checkin_form_id:value": null, "shift_checkin_form_id:array": null, "shift_checkout_form_id": null, "shift_checkout_form_id:value": null, "shift_checkout_form_id:array": null, "shift_precheckin_form_id": null, "shift_precheckin_form_id:value": null, "shift_precheckin_form_id:array": null, "shift_withdraw_form_id": null, "shift_withdraw_form_id:value": null, "shift_withdraw_form_id:array": null, "start_timestamp": "Sep 17, 2026, 3:00 PM", "start_timestamp__date": "Sep 17, 2026", "start_timestamp__time": "3:00 PM", "start_timestamp__offset": " (+10:00 AEST)", "start_timestamp__offset_minutes": 600, "start_timestamp__dayofweek": "Thursday", "updated_at": "Jun 9, 2026, 3:36 PM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "3:36 PM", "updated_at__offset": " (+10:00 AEST)", "updated_at__offset_minutes": 600, "updated_at__dayofweek": "Tuesday", "visibility_hide_groups": "", "visibility_show_groups": "", "visibility_show_roleoffer": "", "info": " - ", "event_shift_link_id": 1, "event_shift_link_repeat": 1, "event_shift_link_name": "test shift link", "shift_status_default_id": 1, "length": 8, "account_id": 20000, "account_url": "https://example.rosterfy.com/", "is_any_leader": false, "post_shift_feedback_form_completed_at": "", "pre_checkin_form_completed_at": "", "event_name": null }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "apply": false, "apply_error": "Shift applications not open", "apply_error_code": "ES0056", "is_unavailable": false, "confirm": false, "reject": false, "selfCheckin": false, "selfCheckout": false, "submitAttendedForm": false, "precheckin": false, "applyWaitlist": false }, "attributes": [] }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/event/{event}/shift?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/event/{event}/shift?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/event/{event}/shift", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Shift Module" ] }, "post": { "summary": "Create a shift", "operationId": "createAShift", "description": "Adds a shift to an event and returns it. The created shift carries only the fields\nthe create set, so it is a smaller object than the one a read returns - read it\nback if you need the whole record.\n\nA full create is a long body: a shift needs times, demand figures, a location and a\nstatus for each point of its lifecycle. **Send `all_default` to avoid most of it** -\nthe shift is then filled in from the event it belongs to, and anything you send\nexplicitly still wins. Without it, a create missing any required field is a 422\nnaming the fields.\n\nSending `event_shift_template_id` builds the shift from a template, and the\ntemplate's values replace what you send for the fields it defines.\n\nAny attribute your account has configured for a shift is accepted here alongside\nthe fields below, under the code you gave it.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "name": { "type": "string", "examples": [ "Probe shift" ] }, "timezone": { "type": "string", "examples": [ "Australia/Melbourne" ] }, "min_demand": { "type": "integer", "examples": [ 1 ] }, "max_demand": { "type": "integer", "examples": [ 1 ] }, "leader_demand": { "type": "integer", "examples": [ 0 ] }, "start_timestamp": { "type": "string", "examples": [ "2027-01-01 09:00:00" ] }, "end_timestamp": { "type": "string", "examples": [ "2027-01-01 17:00:00" ] }, "is_virtual": { "type": "integer", "examples": [ 0 ] }, "shift_status_default": { "type": "integer", "examples": [ 1 ] }, "shift_confirmed_status_default": { "type": "integer", "examples": [ 3 ] }, "shift_rejected_status_default": { "type": "integer", "examples": [ 6 ] }, "shift_can_withdraw_default": { "type": "integer", "examples": [ 1 ] }, "shift_can_withdraw_limit": { "type": "integer", "examples": [ 0 ] }, "shift_can_confirm": { "type": "integer", "examples": [ 1 ] }, "shift_can_confirm_limit": { "type": "integer", "examples": [ 0 ] }, "shift_checked_in_status_default": { "type": "integer", "examples": [ 4 ] }, "shift_checked_out_status_default": { "type": "integer", "examples": [ 4 ] }, "visibility_show_groups": { "type": "array", "examples": [ [] ] }, "visibility_hide_groups": { "type": "array", "examples": [ [] ] }, "visibility_show_roleoffer": { "type": "array", "examples": [ [] ] }, "role_offer_address": { "type": "integer", "examples": [ 0 ] }, "shift_precheckin_open": { "type": "integer", "examples": [ 0 ] }, "self_checkin": { "type": "integer", "examples": [ 0 ] }, "self_checkin_open": { "type": "integer", "examples": [ 1800 ] }, "self_checkin_close": { "type": "integer", "examples": [ 1800 ] }, "self_checkout_close": { "type": "integer", "examples": [ 1800 ] }, "checkin_close": { "type": "integer", "examples": [ 0 ] }, "checkin_visible_attributes": { "type": "array", "examples": [ [] ] }, "publish": { "type": "integer", "examples": [ 1 ] }, "public": { "type": "integer", "examples": [ 0 ] }, "shift_enable_waitlist_default": { "type": "integer", "examples": [ 0 ] }, "max_waitlist": { "type": "integer", "examples": [ 0 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "event_id": { "type": "integer", "examples": [ 1001 ] }, "updated_at": { "type": "string", "examples": [ "2026-08-12T04:57:59.000000Z" ] }, "created_at": { "type": "string", "examples": [ "2026-08-12T04:57:59.000000Z" ] }, "id": { "type": "integer", "examples": [ 2001 ] }, "cost_description": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_description": { "type": "string", "examples": [ "" ] }, "address": { "type": "object", "properties": { "iso": { "type": "string", "examples": [ "AUS" ] }, "region_code": { "type": "string", "examples": [ "VIC" ] }, "coordinates": { "type": "object", "properties": { "latitude": { "type": "string", "examples": [ "-37.814000" ] }, "longitude": { "type": "string", "examples": [ "144.963100" ] } } }, "street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "city": { "type": "string", "examples": [ "Melbourne" ] }, "postcode": { "type": "string", "examples": [ "3000" ] }, "region": { "type": "string", "examples": [ "VIC" ] }, "country": { "type": "string", "examples": [ "AU" ] }, "latitude": { "type": "string", "examples": [ "-37.814000" ] }, "longitude": { "type": "string", "examples": [ "144.963100" ] } } } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:example:20000:shift:2001" ] }, "address": { "type": "string", "examples": [ "1 Example Street\nMelbourne\nVictoria\nAustralia\n3000" ] }, "address_oneline": { "type": "string", "examples": [ "1 Example Street, Melbourne, Victoria, Australia, 3000" ] }, "address.country": { "type": "string", "examples": [ "Australia" ] }, "address.country:raw": { "type": "string", "examples": [ "AUS" ] }, "address.city": { "type": "string", "examples": [ "Melbourne" ] }, "address.region": { "type": "string", "examples": [ "Victoria" ] }, "address.region:raw": { "type": "string", "examples": [ "VIC" ] }, "address.postcode": { "type": "string", "examples": [ "3000" ] }, "address.street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "address.street_address_2": { "type": "string", "examples": [ "" ] }, "address.street_address_3": { "type": "string", "examples": [ "" ] }, "address.latitude": { "type": "string", "examples": [ "-37.814000" ] }, "address.longitude": { "type": "string", "examples": [ "144.963100" ] }, "created_at": { "type": "string", "examples": [ "Aug 12, 2026, 2:57 PM" ] }, "created_at__date": { "type": "string", "examples": [ "Aug 12, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "2:57 PM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+10:00 AEST)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 600 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Wednesday" ] }, "end_timestamp": { "type": "string", "examples": [ "Jan 2, 2027, 4:00 AM" ] }, "end_timestamp__date": { "type": "string", "examples": [ "Jan 2, 2027" ] }, "end_timestamp__time": { "type": "string", "examples": [ "4:00 AM" ] }, "end_timestamp__offset": { "type": "string", "examples": [ " (+11:00 AEDT)" ] }, "end_timestamp__offset_minutes": { "type": "integer", "examples": [ 660 ] }, "end_timestamp__dayofweek": { "type": "string", "examples": [ "Saturday" ] }, "event_shift_template_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_template_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_template_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_type_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_type_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_type_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "is_virtual": { "type": "string", "examples": [ "No" ] }, "minimum_age": { "type": "string", "examples": [ "" ] }, "name": { "type": "string", "examples": [ "Probe shift" ] }, "no_shift_time": { "type": "string", "examples": [ "No" ] }, "post_feedback_form": { "type": [ "string", "null" ], "examples": [ null ] }, "post_feedback_form:value": { "type": [ "string", "null" ], "examples": [ null ] }, "post_feedback_form:array": { "type": [ "string", "null" ], "examples": [ null ] }, "public": { "type": "string", "examples": [ "No" ] }, "publish": { "type": "string", "examples": [ "Yes" ] }, "role_offer_address": { "type": "string", "examples": [ "No" ] }, "role_offer_id": { "type": [ "string", "null" ], "examples": [ null ] }, "role_offer_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "role_offer_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "self_checkin": { "type": "string", "examples": [ "No" ] }, "shift_application_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "start_timestamp": { "type": "string", "examples": [ "Jan 1, 2027, 8:00 PM" ] }, "start_timestamp__date": { "type": "string", "examples": [ "Jan 1, 2027" ] }, "start_timestamp__time": { "type": "string", "examples": [ "8:00 PM" ] }, "start_timestamp__offset": { "type": "string", "examples": [ " (+11:00 AEDT)" ] }, "start_timestamp__offset_minutes": { "type": "integer", "examples": [ 660 ] }, "start_timestamp__dayofweek": { "type": "string", "examples": [ "Friday" ] }, "updated_at": { "type": "string", "examples": [ "Aug 12, 2026, 2:57 PM" ] }, "updated_at__date": { "type": "string", "examples": [ "Aug 12, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "2:57 PM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+10:00 AEST)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 600 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Wednesday" ] }, "visibility_hide_groups": { "type": "string", "examples": [ "" ] }, "visibility_show_groups": { "type": "string", "examples": [ "" ] }, "visibility_show_roleoffer": { "type": "string", "examples": [ "" ] }, "info": { "type": "string", "examples": [ " - Probe shift" ] }, "event_shift_link_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_link_repeat": { "type": "integer", "examples": [ 0 ] }, "event_shift_link_name": { "type": "string", "examples": [ "" ] }, "shift_status_default_id": { "type": "integer", "examples": [ 1 ] }, "length": { "type": "integer", "examples": [ 8 ] }, "account_id": { "type": "integer", "examples": [ 20000 ] }, "account_url": { "type": "string", "examples": [ "https://example.rosterfy.com/" ] }, "is_any_leader": { "type": "boolean", "examples": [ false ] }, "post_shift_feedback_form_completed_at": { "type": "string", "examples": [ "" ] }, "pre_checkin_form_completed_at": { "type": "string", "examples": [ "" ] }, "event_name": { "type": [ "string", "null" ], "examples": [ null ] } } }, "relations": { "type": "object", "properties": {} }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "apply": { "type": "boolean", "examples": [ false ] }, "apply_error": { "type": "string", "examples": [ "Shift applications not open" ] }, "apply_error_code": { "type": "string", "examples": [ "ES0056" ] }, "is_unavailable": { "type": "boolean", "examples": [ false ] }, "confirm": { "type": "boolean", "examples": [ false ] }, "reject": { "type": "boolean", "examples": [ false ] }, "selfCheckin": { "type": "boolean", "examples": [ false ] }, "selfCheckout": { "type": "boolean", "examples": [ false ] }, "submitAttendedForm": { "type": "boolean", "examples": [ false ] }, "precheckin": { "type": "boolean", "examples": [ false ] }, "applyWaitlist": { "type": "boolean", "examples": [ false ] } } }, "attributes": { "type": "object", "properties": {} } }, "examples": [ { "object": { "name": "Probe shift", "timezone": "Australia/Melbourne", "min_demand": 1, "max_demand": 1, "leader_demand": 0, "start_timestamp": "2027-01-01 09:00:00", "end_timestamp": "2027-01-01 17:00:00", "is_virtual": 0, "shift_status_default": 1, "shift_confirmed_status_default": 3, "shift_rejected_status_default": 6, "shift_can_withdraw_default": 1, "shift_can_withdraw_limit": 0, "shift_can_confirm": 1, "shift_can_confirm_limit": 0, "shift_checked_in_status_default": 4, "shift_checked_out_status_default": 4, "visibility_show_groups": [], "visibility_hide_groups": [], "visibility_show_roleoffer": [], "role_offer_address": 0, "shift_precheckin_open": 0, "self_checkin": 0, "self_checkin_open": 1800, "self_checkin_close": 1800, "self_checkout_close": 1800, "checkin_close": 0, "checkin_visible_attributes": [], "publish": 1, "public": 0, "shift_enable_waitlist_default": 0, "max_waitlist": 0, "sort_order": 0, "event_id": 1001, "updated_at": "2026-08-12T04:57:59.000000Z", "created_at": "2026-08-12T04:57:59.000000Z", "id": 2001, "cost_description": null, "event_shift_description": "", "address": { "iso": "AUS", "region_code": "VIC", "coordinates": { "latitude": "-37.814000", "longitude": "144.963100" }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "Melbourne", "postcode": "3000", "region": "VIC", "country": "AU", "latitude": "-37.814000", "longitude": "144.963100" } }, "nice": { "rrn": "rrn:example:20000:shift:2001", "address": "1 Example Street\nMelbourne\nVictoria\nAustralia\n3000", "address_oneline": "1 Example Street, Melbourne, Victoria, Australia, 3000", "address.country": "Australia", "address.country:raw": "AUS", "address.city": "Melbourne", "address.region": "Victoria", "address.region:raw": "VIC", "address.postcode": "3000", "address.street_address_1": "1 Example Street", "address.street_address_2": "", "address.street_address_3": "", "address.latitude": "-37.814000", "address.longitude": "144.963100", "created_at": "Aug 12, 2026, 2:57 PM", "created_at__date": "Aug 12, 2026", "created_at__time": "2:57 PM", "created_at__offset": " (+10:00 AEST)", "created_at__offset_minutes": 600, "created_at__dayofweek": "Wednesday", "end_timestamp": "Jan 2, 2027, 4:00 AM", "end_timestamp__date": "Jan 2, 2027", "end_timestamp__time": "4:00 AM", "end_timestamp__offset": " (+11:00 AEDT)", "end_timestamp__offset_minutes": 660, "end_timestamp__dayofweek": "Saturday", "event_shift_template_id": null, "event_shift_template_id:value": null, "event_shift_template_id:array": null, "event_shift_type_id": null, "event_shift_type_id:value": null, "event_shift_type_id:array": null, "headcount_location_venue_id": null, "headcount_location_venue_id:value": null, "headcount_location_venue_id:array": null, "is_virtual": "No", "minimum_age": "", "name": "Probe shift", "no_shift_time": "No", "post_feedback_form": null, "post_feedback_form:value": null, "post_feedback_form:array": null, "public": "No", "publish": "Yes", "role_offer_address": "No", "role_offer_id": null, "role_offer_id:value": null, "role_offer_id:array": null, "self_checkin": "No", "shift_application_form_id": null, "shift_application_form_id:value": null, "shift_application_form_id:array": null, "shift_attended_form_id": null, "shift_attended_form_id:value": null, "shift_attended_form_id:array": null, "shift_checkin_form_id": null, "shift_checkin_form_id:value": null, "shift_checkin_form_id:array": null, "shift_checkout_form_id": null, "shift_checkout_form_id:value": null, "shift_checkout_form_id:array": null, "shift_precheckin_form_id": null, "shift_precheckin_form_id:value": null, "shift_precheckin_form_id:array": null, "shift_withdraw_form_id": null, "shift_withdraw_form_id:value": null, "shift_withdraw_form_id:array": null, "start_timestamp": "Jan 1, 2027, 8:00 PM", "start_timestamp__date": "Jan 1, 2027", "start_timestamp__time": "8:00 PM", "start_timestamp__offset": " (+11:00 AEDT)", "start_timestamp__offset_minutes": 660, "start_timestamp__dayofweek": "Friday", "updated_at": "Aug 12, 2026, 2:57 PM", "updated_at__date": "Aug 12, 2026", "updated_at__time": "2:57 PM", "updated_at__offset": " (+10:00 AEST)", "updated_at__offset_minutes": 600, "updated_at__dayofweek": "Wednesday", "visibility_hide_groups": "", "visibility_show_groups": "", "visibility_show_roleoffer": "", "info": " - Probe shift", "event_shift_link_id": null, "event_shift_link_repeat": 0, "event_shift_link_name": "", "shift_status_default_id": 1, "length": 8, "account_id": 20000, "account_url": "https://example.rosterfy.com/", "is_any_leader": false, "post_shift_feedback_form_completed_at": "", "pre_checkin_form_completed_at": "", "event_name": null }, "relations": {}, "permissions": { "read": true, "update": true, "delete": true, "apply": false, "apply_error": "Shift applications not open", "apply_error_code": "ES0056", "is_unavailable": false, "confirm": false, "reject": false, "selfCheckin": false, "selfCheckout": false, "submitAttendedForm": false, "precheckin": false, "applyWaitlist": false }, "attributes": {} } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Shift Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "What the shift is called. Shown to people choosing shifts.", "examples": [ null ] }, "timezone": { "type": "string", "description": "The timezone the start and end times are given in, as an IANA name such as `Australia/Melbourne`.", "examples": [ null ] }, "min_demand": { "type": "integer", "description": "The fewest people the shift needs. Defaults to 1.", "examples": [ 1 ] }, "max_demand": { "type": "integer", "description": "The most people the shift can take. Applications are refused once it is full.", "examples": [ 1 ] }, "leader_demand": { "type": "integer", "description": "How many of those places are for leaders. Defaults to 0.", "examples": [ 1 ] }, "start_timestamp": { "type": "string", "description": "When the shift starts, as `YYYY-MM-DD HH:MM:SS` in the shift's timezone.", "examples": [ null ] }, "end_timestamp": { "type": "string", "description": "When the shift ends, as `YYYY-MM-DD HH:MM:SS` in the shift's timezone.", "examples": [ null ] }, "is_virtual": { "type": "boolean", "description": "Whether the shift happens online rather than at a place.", "examples": [ true ] }, "event_shift_type_id": { "type": "integer", "description": "The shift type, which groups shifts for reporting and for the per-type application limits an event can set.", "examples": [ 1 ] }, "event_shift_template_id": { "type": "integer", "description": "A shift template to build the shift from. The template's values replace anything you send for the fields it defines, unless you also send `:override` as true and are allowed to override locked fields.", "examples": [ 1 ] }, "shift_status_default": { "type": "integer", "description": "The status a new application on this shift starts at.", "examples": [ 1 ] }, "shift_confirmed_status_default": { "type": "integer", "description": "The status an application moves to when it is confirmed.", "examples": [ 1 ] }, "shift_rejected_status_default": { "type": "integer", "description": "The status an application moves to when it is rejected.", "examples": [ 1 ] }, "shift_can_withdraw_default": { "type": "boolean", "description": "Whether people can withdraw from the shift themselves.", "examples": [ true ] }, "shift_can_withdraw_limit": { "type": "integer", "description": "How long before the shift starts withdrawing stops being allowed, in seconds.", "examples": [ 1 ] }, "shift_can_confirm": { "type": "boolean", "description": "Whether people can confirm their own place on the shift.", "examples": [ true ] }, "shift_can_confirm_limit": { "type": "integer", "description": "How long before the shift starts confirming stops being allowed, in seconds.", "examples": [ 1 ] }, "shift_checked_in_status_default": { "type": "integer", "description": "The status an assignment moves to on check-in.", "examples": [ 1 ] }, "shift_checked_out_status_default": { "type": "integer", "description": "The status an assignment moves to on check-out.", "examples": [ 1 ] }, "address": { "type": "object", "description": "Where the shift happens, as an address object. Required on a create unless the shift is virtual or takes its location from a venue.", "properties": {}, "examples": [ "{}" ] }, "headcount_location_venue_id": { "type": "integer", "description": "The venue the shift happens at. Sending one takes the location from the venue instead of from `address`.", "examples": [ 1 ] }, "certificate_id": { "type": "integer", "description": "A certificate awarded for attending the shift.", "examples": [ 1 ] }, "visibility_show_groups": { "type": "array", "description": "Only members of these groups can see the shift.", "items": { "type": "integer" }, "examples": [ [] ] }, "visibility_hide_groups": { "type": "array", "description": "Members of these groups cannot see the shift.", "items": { "type": "integer" }, "examples": [ [] ] }, "visibility_show_roleoffer": { "type": "array", "description": "Only people holding one of these role offers can see the shift.", "items": { "type": "integer" }, "examples": [ [] ] }, "apps_open_timestamp": { "type": "string", "description": "When applications open. Before this, applying is refused.", "examples": [ null ] }, "apps_close_timestamp": { "type": "string", "description": "When applications close. After this, applying is refused.", "examples": [ null ] }, "role_offer_id": { "type": "integer", "description": "The role offer this shift belongs to.", "examples": [ 1 ] }, "role_offer_address": { "type": "boolean", "description": "Take the shift's location from the role offer rather than from `address`.", "examples": [ true ] }, "shift_application_form_id": { "type": "integer", "description": "The form someone fills in when applying for this shift.", "examples": [ 1 ] }, "allow_application_form_resubmit": { "type": "boolean", "description": "Whether someone can submit the application form again.", "examples": [ true ] }, "shift_precheckin_form_id": { "type": "integer", "description": "The form filled in at pre-check-in.", "examples": [ 1 ] }, "shift_checkin_form_id": { "type": "integer", "description": "The form filled in at check-in.", "examples": [ 1 ] }, "shift_attended_form_id": { "type": "integer", "description": "The form filled in once the shift has been attended.", "examples": [ 1 ] }, "shift_checkout_form_id": { "type": "integer", "description": "The form filled in at check-out.", "examples": [ 1 ] }, "shift_withdraw_form_id": { "type": "integer", "description": "The form filled in when withdrawing.", "examples": [ 1 ] }, "shift_precheckin_open": { "type": "integer", "description": "How long before the shift starts pre-check-in opens, in seconds.", "examples": [ 1 ] }, "max_group_demand": { "type": "integer", "description": "How many places a single group booking can take.", "examples": [ 1 ] }, "group_booking_ttl": { "type": "integer", "description": "How long a group booking is held before it lapses, in seconds.", "examples": [ 1 ] }, "self_checkin": { "type": "boolean", "description": "Whether people can check themselves in to the shift.", "examples": [ true ] }, "self_checkin_open": { "type": "integer", "description": "How long before the shift starts self check-in opens, in seconds.", "examples": [ 1 ] }, "self_checkin_close": { "type": "integer", "description": "How long after the shift starts self check-in closes, in seconds.", "examples": [ 1 ] }, "self_checkout_close": { "type": "integer", "description": "How long after the shift ends self check-out closes, in seconds.", "examples": [ 1 ] }, "checkin_close": { "type": "integer", "description": "How long after the shift ends check-in closes, in seconds.", "examples": [ 1 ] }, "geofence_checkin_limit": { "type": "integer", "description": "How close to the shift's location someone has to be to check in, in metres.", "examples": [ 1 ] }, "checkin_visible_attributes": { "type": "array", "description": "Which of a person's attributes are shown on the check-in screen.", "items": { "type": "integer" }, "examples": [ [] ] }, "training_ids": { "type": "array", "description": "Training people must have completed before they can be placed on the shift.", "items": { "type": "integer" }, "examples": [ [] ] }, "publish": { "type": "boolean", "description": "Whether the shift is visible to people who can apply for it. Ignored from a caller who cannot publish shifts.", "examples": [ true ] }, "public": { "type": "boolean", "description": "Whether the shift can be seen without signing in, on a public event.", "examples": [ true ] }, "post_feedback_form": { "type": "integer", "description": "The form people fill in about the shift afterwards.", "examples": [ 1 ] }, "shift_leader_feedback_form_id": { "type": "integer", "description": "The form a leader fills in about the shift.", "examples": [ 1 ] }, "shift_enable_waitlist_default": { "type": "boolean", "description": "Whether people can join a waitlist once the shift is full.", "examples": [ true ] }, "max_waitlist": { "type": "integer", "description": "How many people the waitlist holds.", "examples": [ 1 ] }, "sort_order": { "type": "integer", "description": "Where the shift sits when shifts are shown in a fixed order.", "examples": [ 1 ] }, "minimum_dob": { "type": "string", "description": "Latest date of birth allowed on the shift. Cannot be sent together with `minimum_age`.", "examples": [ null ] }, "minimum_age": { "type": "string", "description": "Youngest age allowed on the shift, as `years:months`.", "examples": [ null ] }, "maximum_dob": { "type": "string", "description": "Earliest date of birth allowed on the shift. Cannot be sent together with `maximum_age`.", "examples": [ null ] }, "maximum_age": { "type": "string", "description": "Oldest age allowed on the shift, as `years:months`.", "examples": [ null ] }, "price_excluding_tax": { "type": "number", "description": "What taking this shift costs the person, before tax.", "examples": [ 1.23 ] }, "tax_percentage": { "type": "integer", "description": "Tax charged on the price, as a percentage between 0 and 100.", "examples": [ 1 ] }, "cost_description": { "type": "string", "description": "Free text shown alongside the price.", "examples": [ null ] }, "all_default": { "type": "boolean", "description": "Fill the shift in from the event: the event's address and its shift defaults, plus `publish` 1, `max_demand` 1, `min_demand` 1 and `leader_demand` 0. Anything you send explicitly wins over the value this would have supplied, so it is a starting point rather than an override. Without it a create needs the full body.", "examples": [ true ] }, "no_shift_time": { "type": "boolean", "description": "Treat the shift as all-day: the times you send are reduced to dates and the shift is stored spanning them.", "examples": [ true ] }, "has_age_limit": { "type": "boolean", "description": "Send `false` to clear all four age limits on the shift. Read and then discarded; it is not stored.", "examples": [ true ] }, "published": { "type": "boolean", "description": "An accepted alias for `publish`, used only if `publish` itself is absent.", "examples": [ true ] }, "custom_*": { "type": "string", "description": "A custom attribute, named by its code - custom_shirt_size, for example. The value follows the attribute's own type, so it may be a string, a number, a boolean or a list. See the custom attributes documentation.", "examples": [ null ] } }, "required": [ "name", "timezone", "min_demand", "max_demand", "leader_demand", "start_timestamp", "end_timestamp", "shift_status_default", "shift_confirmed_status_default", "shift_rejected_status_default", "shift_checked_in_status_default", "shift_checked_out_status_default", "address", "publish" ] } } } } }, "parameters": [ { "in": "path", "name": "event_id", "description": "The ID of the event.", "required": true, "schema": { "type": "integer", "examples": [ 1001 ] } } ] }, "/api/v2/event/{event_id}/shift/{id}": { "get": { "summary": "Read a shift", "operationId": "readAShift", "description": "Returns one shift with its times, demand figures, location and the settings that\ngovern applying, checking in and checking out.\n\n`object` holds the stored values and `nice` the same values rendered for display -\ndates formatted in the shift's timezone, ids resolved to the names they point at.\n`permissions` says what the caller may do with this shift, and `apply_error` says\nwhy applying is refused when it is.\n\nThe shift has to belong to the event in the URL; a mismatch is a 404.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 2001 ] }, "event_id": { "type": "integer", "examples": [ 1001 ] }, "event_shift_type_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_template_id": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_id": { "type": [ "string", "null" ], "examples": [ null ] }, "min_demand": { "type": "integer", "examples": [ 10 ] }, "max_demand": { "type": "integer", "examples": [ 10 ] }, "leader_demand": { "type": "integer", "examples": [ 1 ] }, "start_timestamp": { "type": "string", "examples": [ "2026-09-17 05:00:00" ] }, "end_timestamp": { "type": "string", "examples": [ "2026-09-17 13:00:00" ] }, "timezone": { "type": "string", "examples": [ "Australia/Melbourne" ] }, "no_shift_time": { "type": "integer", "examples": [ 0 ] }, "apps_open_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "apps_close_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_confirmed_status_default": { "type": "integer", "examples": [ 3 ] }, "shift_rejected_status_default": { "type": "integer", "examples": [ 6 ] }, "journey_complete_status": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_can_withdraw_default": { "type": "integer", "examples": [ 1 ] }, "shift_can_confirm": { "type": "integer", "examples": [ 1 ] }, "shift_can_confirm_limit": { "type": "integer", "examples": [ 0 ] }, "shift_can_withdraw_limit": { "type": "integer", "examples": [ 0 ] }, "shift_checked_in_status_default": { "type": "integer", "examples": [ 4 ] }, "shift_checked_out_status_default": { "type": "integer", "examples": [ 4 ] }, "certificate_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "allow_application_form_resubmit": { "type": "integer", "examples": [ 0 ] }, "shift_checkin_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "training_ids": { "type": [ "string", "null" ], "examples": [ null ] }, "visibility_show_groups": { "type": "array", "examples": [ [] ] }, "visibility_hide_groups": { "type": "array", "examples": [ [] ] }, "visibility_show_roleoffer": { "type": "array", "examples": [ [] ] }, "role_offer_id": { "type": [ "string", "null" ], "examples": [ null ] }, "role_offer_address": { "type": "integer", "examples": [ 0 ] }, "checkin_visible_attributes": { "type": "array", "examples": [ [] ] }, "shift_enable_waitlist_default": { "type": "integer", "examples": [ 0 ] }, "max_waitlist": { "type": "integer", "examples": [ 0 ] }, "group_booking_ttl": { "type": [ "string", "null" ], "examples": [ null ] }, "max_group_demand": { "type": [ "string", "null" ], "examples": [ null ] }, "max_group_size": { "type": [ "string", "null" ], "examples": [ null ] }, "reserved_expiry": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "self_checkin": { "type": "integer", "examples": [ 0 ] }, "self_checkin_open": { "type": "integer", "examples": [ 1800 ] }, "self_checkin_close": { "type": "integer", "examples": [ 1800 ] }, "self_checkout_close": { "type": "integer", "examples": [ 1800 ] }, "checkin_close": { "type": "integer", "examples": [ 0 ] }, "shift_precheckin_open": { "type": "integer", "examples": [ 0 ] }, "break": { "type": "integer", "examples": [ 0 ] }, "post_feedback_form": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_leader_feedback_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "is_virtual": { "type": "integer", "examples": [ 0 ] }, "geofence_checkin_limit": { "type": [ "string", "null" ], "examples": [ null ] }, "tax": { "type": [ "string", "null" ], "examples": [ null ] }, "price_excluding_tax": { "type": "integer", "examples": [ 0 ] }, "tax_percentage": { "type": [ "string", "null" ], "examples": [ null ] }, "publish": { "type": "integer", "examples": [ 0 ] }, "public": { "type": "integer", "examples": [ 0 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "is_cancelled": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "is_draft": { "type": "boolean", "examples": [ false ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:10.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:10.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "cost_description": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_description": { "type": "string", "examples": [ "" ] }, "name": { "type": [ "string", "null" ], "examples": [ null ] }, "address": { "type": "object", "properties": { "iso": { "type": "string", "examples": [ "AUS" ] }, "region_code": { "type": "string", "examples": [ "VIC" ] }, "coordinates": { "type": "object", "properties": { "latitude": { "type": "string", "examples": [ "-37.814000" ] }, "longitude": { "type": "string", "examples": [ "144.963100" ] } } }, "street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "city": { "type": "string", "examples": [ "Melbourne" ] }, "postcode": { "type": "string", "examples": [ "3000" ] }, "region": { "type": "string", "examples": [ "VIC" ] }, "country": { "type": "string", "examples": [ "AU" ] }, "latitude": { "type": "string", "examples": [ "-37.814000" ] }, "longitude": { "type": "string", "examples": [ "144.963100" ] } } } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:example:20000:shift:2001" ] }, "address": { "type": "string", "examples": [ "1 Example Street\nMelbourne\nVictoria\nAustralia\n3000" ] }, "address_oneline": { "type": "string", "examples": [ "1 Example Street, Melbourne, Victoria, Australia, 3000" ] }, "address.country": { "type": "string", "examples": [ "Australia" ] }, "address.country:raw": { "type": "string", "examples": [ "AUS" ] }, "address.city": { "type": "string", "examples": [ "Melbourne" ] }, "address.region": { "type": "string", "examples": [ "Victoria" ] }, "address.region:raw": { "type": "string", "examples": [ "VIC" ] }, "address.postcode": { "type": "string", "examples": [ "3000" ] }, "address.street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "address.street_address_2": { "type": "string", "examples": [ "" ] }, "address.street_address_3": { "type": "string", "examples": [ "" ] }, "address.latitude": { "type": "string", "examples": [ "-37.814000" ] }, "address.longitude": { "type": "string", "examples": [ "144.963100" ] }, "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 3:36 PM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "3:36 PM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+10:00 AEST)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 600 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "end_timestamp": { "type": "string", "examples": [ "Sep 17, 2026, 11:00 PM" ] }, "end_timestamp__date": { "type": "string", "examples": [ "Sep 17, 2026" ] }, "end_timestamp__time": { "type": "string", "examples": [ "11:00 PM" ] }, "end_timestamp__offset": { "type": "string", "examples": [ " (+10:00 AEST)" ] }, "end_timestamp__offset_minutes": { "type": "integer", "examples": [ 600 ] }, "end_timestamp__dayofweek": { "type": "string", "examples": [ "Thursday" ] }, "event_shift_template_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_template_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_template_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_type_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_type_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_type_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "is_virtual": { "type": "string", "examples": [ "No" ] }, "minimum_age": { "type": "string", "examples": [ "" ] }, "name": { "type": "string", "examples": [ "" ] }, "no_shift_time": { "type": "string", "examples": [ "No" ] }, "post_feedback_form": { "type": [ "string", "null" ], "examples": [ null ] }, "post_feedback_form:value": { "type": [ "string", "null" ], "examples": [ null ] }, "post_feedback_form:array": { "type": [ "string", "null" ], "examples": [ null ] }, "public": { "type": "string", "examples": [ "No" ] }, "publish": { "type": "string", "examples": [ "No" ] }, "role_offer_address": { "type": "string", "examples": [ "No" ] }, "role_offer_id": { "type": [ "string", "null" ], "examples": [ null ] }, "role_offer_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "role_offer_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "self_checkin": { "type": "string", "examples": [ "No" ] }, "shift_application_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "start_timestamp": { "type": "string", "examples": [ "Sep 17, 2026, 3:00 PM" ] }, "start_timestamp__date": { "type": "string", "examples": [ "Sep 17, 2026" ] }, "start_timestamp__time": { "type": "string", "examples": [ "3:00 PM" ] }, "start_timestamp__offset": { "type": "string", "examples": [ " (+10:00 AEST)" ] }, "start_timestamp__offset_minutes": { "type": "integer", "examples": [ 600 ] }, "start_timestamp__dayofweek": { "type": "string", "examples": [ "Thursday" ] }, "updated_at": { "type": "string", "examples": [ "Jun 9, 2026, 3:36 PM" ] }, "updated_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "3:36 PM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+10:00 AEST)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 600 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "visibility_hide_groups": { "type": "string", "examples": [ "" ] }, "visibility_show_groups": { "type": "string", "examples": [ "" ] }, "visibility_show_roleoffer": { "type": "string", "examples": [ "" ] }, "info": { "type": "string", "examples": [ " - " ] }, "event_shift_link_id": { "type": "integer", "examples": [ 1 ] }, "event_shift_link_repeat": { "type": "integer", "examples": [ 1 ] }, "event_shift_link_name": { "type": "string", "examples": [ "test shift link" ] }, "shift_status_default_id": { "type": "integer", "examples": [ 1 ] }, "length": { "type": "integer", "examples": [ 8 ] }, "account_id": { "type": "integer", "examples": [ 20000 ] }, "account_url": { "type": "string", "examples": [ "https://example.rosterfy.com/" ] }, "is_any_leader": { "type": "boolean", "examples": [ false ] }, "post_shift_feedback_form_completed_at": { "type": "string", "examples": [ "" ] }, "pre_checkin_form_completed_at": { "type": "string", "examples": [ "" ] }, "event_name": { "type": [ "string", "null" ], "examples": [ null ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "apply": { "type": "boolean", "examples": [ false ] }, "apply_error": { "type": "string", "examples": [ "Shift applications not open" ] }, "apply_error_code": { "type": "string", "examples": [ "ES0056" ] }, "is_unavailable": { "type": "boolean", "examples": [ false ] }, "confirm": { "type": "boolean", "examples": [ false ] }, "reject": { "type": "boolean", "examples": [ false ] }, "selfCheckin": { "type": "boolean", "examples": [ false ] }, "selfCheckout": { "type": "boolean", "examples": [ false ] }, "submitAttendedForm": { "type": "boolean", "examples": [ false ] }, "precheckin": { "type": "boolean", "examples": [ false ] }, "applyWaitlist": { "type": "boolean", "examples": [ false ] } } }, "attributes": { "type": "object", "properties": {} } }, "examples": [ { "object": { "id": 2001, "event_id": 1001, "event_shift_type_id": null, "event_shift_template_id": null, "journey_id": null, "min_demand": 10, "max_demand": 10, "leader_demand": 1, "start_timestamp": "2026-09-17 05:00:00", "end_timestamp": "2026-09-17 13:00:00", "timezone": "Australia/Melbourne", "no_shift_time": 0, "apps_open_timestamp": null, "apps_close_timestamp": null, "headcount_location_venue_id": null, "shift_confirmed_status_default": 3, "shift_rejected_status_default": 6, "journey_complete_status": null, "shift_can_withdraw_default": 1, "shift_can_confirm": 1, "shift_can_confirm_limit": 0, "shift_can_withdraw_limit": 0, "shift_checked_in_status_default": 4, "shift_checked_out_status_default": 4, "certificate_id": null, "shift_application_form_id": null, "allow_application_form_resubmit": 0, "shift_checkin_form_id": null, "shift_attended_form_id": null, "shift_checkout_form_id": null, "shift_precheckin_form_id": null, "shift_withdraw_form_id": null, "training_ids": null, "visibility_show_groups": [], "visibility_hide_groups": [], "visibility_show_roleoffer": [], "role_offer_id": null, "role_offer_address": 0, "checkin_visible_attributes": [], "shift_enable_waitlist_default": 0, "max_waitlist": 0, "group_booking_ttl": null, "max_group_demand": null, "max_group_size": null, "reserved_expiry": null, "minimum_dob": null, "minimum_age": null, "maximum_dob": null, "maximum_age": null, "self_checkin": 0, "self_checkin_open": 1800, "self_checkin_close": 1800, "self_checkout_close": 1800, "checkin_close": 0, "shift_precheckin_open": 0, "break": 0, "post_feedback_form": null, "shift_leader_feedback_form_id": null, "is_virtual": 0, "geofence_checkin_limit": null, "tax": null, "price_excluding_tax": 0, "tax_percentage": null, "publish": 0, "public": 0, "sort_order": 0, "is_cancelled": 0, "deleted_at": null, "is_erased": 0, "is_draft": false, "created_at": "2026-06-09T05:36:10.000000Z", "updated_at": "2026-06-09T05:36:10.000000Z", "deleted_by": null, "cost_description": null, "event_shift_description": "", "name": null, "address": { "iso": "AUS", "region_code": "VIC", "coordinates": { "latitude": "-37.814000", "longitude": "144.963100" }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "Melbourne", "postcode": "3000", "region": "VIC", "country": "AU", "latitude": "-37.814000", "longitude": "144.963100" } }, "nice": { "rrn": "rrn:example:20000:shift:2001", "address": "1 Example Street\nMelbourne\nVictoria\nAustralia\n3000", "address_oneline": "1 Example Street, Melbourne, Victoria, Australia, 3000", "address.country": "Australia", "address.country:raw": "AUS", "address.city": "Melbourne", "address.region": "Victoria", "address.region:raw": "VIC", "address.postcode": "3000", "address.street_address_1": "1 Example Street", "address.street_address_2": "", "address.street_address_3": "", "address.latitude": "-37.814000", "address.longitude": "144.963100", "created_at": "Jun 9, 2026, 3:36 PM", "created_at__date": "Jun 9, 2026", "created_at__time": "3:36 PM", "created_at__offset": " (+10:00 AEST)", "created_at__offset_minutes": 600, "created_at__dayofweek": "Tuesday", "end_timestamp": "Sep 17, 2026, 11:00 PM", "end_timestamp__date": "Sep 17, 2026", "end_timestamp__time": "11:00 PM", "end_timestamp__offset": " (+10:00 AEST)", "end_timestamp__offset_minutes": 600, "end_timestamp__dayofweek": "Thursday", "event_shift_template_id": null, "event_shift_template_id:value": null, "event_shift_template_id:array": null, "event_shift_type_id": null, "event_shift_type_id:value": null, "event_shift_type_id:array": null, "headcount_location_venue_id": null, "headcount_location_venue_id:value": null, "headcount_location_venue_id:array": null, "is_virtual": "No", "minimum_age": "", "name": "", "no_shift_time": "No", "post_feedback_form": null, "post_feedback_form:value": null, "post_feedback_form:array": null, "public": "No", "publish": "No", "role_offer_address": "No", "role_offer_id": null, "role_offer_id:value": null, "role_offer_id:array": null, "self_checkin": "No", "shift_application_form_id": null, "shift_application_form_id:value": null, "shift_application_form_id:array": null, "shift_attended_form_id": null, "shift_attended_form_id:value": null, "shift_attended_form_id:array": null, "shift_checkin_form_id": null, "shift_checkin_form_id:value": null, "shift_checkin_form_id:array": null, "shift_checkout_form_id": null, "shift_checkout_form_id:value": null, "shift_checkout_form_id:array": null, "shift_precheckin_form_id": null, "shift_precheckin_form_id:value": null, "shift_precheckin_form_id:array": null, "shift_withdraw_form_id": null, "shift_withdraw_form_id:value": null, "shift_withdraw_form_id:array": null, "start_timestamp": "Sep 17, 2026, 3:00 PM", "start_timestamp__date": "Sep 17, 2026", "start_timestamp__time": "3:00 PM", "start_timestamp__offset": " (+10:00 AEST)", "start_timestamp__offset_minutes": 600, "start_timestamp__dayofweek": "Thursday", "updated_at": "Jun 9, 2026, 3:36 PM", "updated_at__date": "Jun 9, 2026", "updated_at__time": "3:36 PM", "updated_at__offset": " (+10:00 AEST)", "updated_at__offset_minutes": 600, "updated_at__dayofweek": "Tuesday", "visibility_hide_groups": "", "visibility_show_groups": "", "visibility_show_roleoffer": "", "info": " - ", "event_shift_link_id": 1, "event_shift_link_repeat": 1, "event_shift_link_name": "test shift link", "shift_status_default_id": 1, "length": 8, "account_id": 20000, "account_url": "https://example.rosterfy.com/", "is_any_leader": false, "post_shift_feedback_form_completed_at": "", "pre_checkin_form_completed_at": "", "event_name": null }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "apply": false, "apply_error": "Shift applications not open", "apply_error_code": "ES0056", "is_unavailable": false, "confirm": false, "reject": false, "selfCheckin": false, "selfCheckout": false, "submitAttendedForm": false, "precheckin": false, "applyWaitlist": false }, "attributes": {} } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Shift Module" ] }, "put": { "summary": "Update a shift", "operationId": "updateAShift", "description": "Changes one shift and returns it. Every field is optional; send only what you are\nchanging.\n\n**A shift in a linked series cannot be updated without saying what to do about the\nrest of the series.** The first attempt comes back as a 400 carrying\n`reference: \"_options.update_linked_shifts\"` - a prompt rather than an error.\nAnswer it by sending `_options.update_linked_shifts`: false changes this shift\nalone and returns it, true also changes the shifts linked to it, and **that form\nreturns `{\"queue\": \"\"}` instead of the shift**, because the rest of the\nseries is changed in the background. The token is not something you can poll; read\nthe shifts back to confirm.\n\nWhere the shift was built from a template, the template's values replace what you\nsend for the fields it locks, unless you also send `:override` as true and\nare allowed to override locked fields.\n\nAny attribute your account has configured for a shift is accepted here alongside\nthe fields below, under the code you gave it. The shift has to belong to the event\nin the URL; a mismatch is a 404.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 2001 ] }, "event_id": { "type": "integer", "examples": [ 1001 ] }, "event_shift_type_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_template_id": { "type": [ "string", "null" ], "examples": [ null ] }, "journey_id": { "type": [ "string", "null" ], "examples": [ null ] }, "min_demand": { "type": "integer", "examples": [ 2 ] }, "max_demand": { "type": "integer", "examples": [ 10 ] }, "leader_demand": { "type": "integer", "examples": [ 1 ] }, "start_timestamp": { "type": "string", "examples": [ "2026-09-17 05:00:00" ] }, "end_timestamp": { "type": "string", "examples": [ "2026-09-17 13:00:00" ] }, "timezone": { "type": "string", "examples": [ "Australia/Melbourne" ] }, "no_shift_time": { "type": "integer", "examples": [ 0 ] }, "apps_open_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "apps_close_timestamp": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_status_default": { "type": "integer", "examples": [ 1 ] }, "shift_confirmed_status_default": { "type": "integer", "examples": [ 3 ] }, "shift_rejected_status_default": { "type": "integer", "examples": [ 6 ] }, "journey_complete_status": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_can_withdraw_default": { "type": "integer", "examples": [ 1 ] }, "shift_can_confirm": { "type": "integer", "examples": [ 1 ] }, "shift_can_confirm_limit": { "type": "integer", "examples": [ 0 ] }, "shift_can_withdraw_limit": { "type": "integer", "examples": [ 0 ] }, "shift_checked_in_status_default": { "type": "integer", "examples": [ 4 ] }, "shift_checked_out_status_default": { "type": "integer", "examples": [ 4 ] }, "certificate_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "allow_application_form_resubmit": { "type": "integer", "examples": [ 0 ] }, "shift_checkin_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "training_ids": { "type": [ "string", "null" ], "examples": [ null ] }, "visibility_show_groups": { "type": "array", "examples": [ [] ] }, "visibility_hide_groups": { "type": "array", "examples": [ [] ] }, "visibility_show_roleoffer": { "type": "array", "examples": [ [] ] }, "role_offer_id": { "type": [ "string", "null" ], "examples": [ null ] }, "role_offer_address": { "type": "integer", "examples": [ 0 ] }, "checkin_visible_attributes": { "type": "array", "examples": [ [] ] }, "shift_enable_waitlist_default": { "type": "integer", "examples": [ 0 ] }, "max_waitlist": { "type": "integer", "examples": [ 0 ] }, "group_booking_ttl": { "type": [ "string", "null" ], "examples": [ null ] }, "max_group_demand": { "type": [ "string", "null" ], "examples": [ null ] }, "max_group_size": { "type": [ "string", "null" ], "examples": [ null ] }, "reserved_expiry": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "minimum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_dob": { "type": [ "string", "null" ], "examples": [ null ] }, "maximum_age": { "type": [ "string", "null" ], "examples": [ null ] }, "self_checkin": { "type": "integer", "examples": [ 0 ] }, "self_checkin_open": { "type": "integer", "examples": [ 1800 ] }, "self_checkin_close": { "type": "integer", "examples": [ 1800 ] }, "self_checkout_close": { "type": "integer", "examples": [ 1800 ] }, "checkin_close": { "type": "integer", "examples": [ 0 ] }, "shift_precheckin_open": { "type": "integer", "examples": [ 0 ] }, "break": { "type": "integer", "examples": [ 0 ] }, "post_feedback_form": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_leader_feedback_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "is_virtual": { "type": "integer", "examples": [ 0 ] }, "geofence_checkin_limit": { "type": [ "string", "null" ], "examples": [ null ] }, "tax": { "type": [ "string", "null" ], "examples": [ null ] }, "price_excluding_tax": { "type": "integer", "examples": [ 0 ] }, "tax_percentage": { "type": [ "string", "null" ], "examples": [ null ] }, "publish": { "type": "integer", "examples": [ 0 ] }, "public": { "type": "integer", "examples": [ 0 ] }, "sort_order": { "type": "integer", "examples": [ 0 ] }, "is_cancelled": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "is_draft": { "type": "boolean", "examples": [ false ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:11.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-08-12T05:00:00.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] }, "cost_description": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_description": { "type": "string", "examples": [ "" ] }, "name": { "type": [ "string", "null" ], "examples": [ null ] }, "address": { "type": "object", "properties": { "iso": { "type": "string", "examples": [ "AUS" ] }, "region_code": { "type": "string", "examples": [ "VIC" ] }, "coordinates": { "type": "object", "properties": { "latitude": { "type": "string", "examples": [ "-37.814000" ] }, "longitude": { "type": "string", "examples": [ "144.963100" ] } } }, "street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "street_address_2": { "type": [ "string", "null" ], "examples": [ null ] }, "street_address_3": { "type": [ "string", "null" ], "examples": [ null ] }, "city": { "type": "string", "examples": [ "Melbourne" ] }, "postcode": { "type": "string", "examples": [ "3000" ] }, "region": { "type": "string", "examples": [ "VIC" ] }, "country": { "type": "string", "examples": [ "AU" ] }, "latitude": { "type": "string", "examples": [ "-37.814000" ] }, "longitude": { "type": "string", "examples": [ "144.963100" ] } } } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:example:20000:shift:2001" ] }, "address": { "type": "string", "examples": [ "1 Example Street\nMelbourne\nVictoria\nAustralia\n3000" ] }, "address_oneline": { "type": "string", "examples": [ "1 Example Street, Melbourne, Victoria, Australia, 3000" ] }, "address.country": { "type": "string", "examples": [ "Australia" ] }, "address.country:raw": { "type": "string", "examples": [ "AUS" ] }, "address.city": { "type": "string", "examples": [ "Melbourne" ] }, "address.region": { "type": "string", "examples": [ "Victoria" ] }, "address.region:raw": { "type": "string", "examples": [ "VIC" ] }, "address.postcode": { "type": "string", "examples": [ "3000" ] }, "address.street_address_1": { "type": "string", "examples": [ "1 Example Street" ] }, "address.street_address_2": { "type": "string", "examples": [ "" ] }, "address.street_address_3": { "type": "string", "examples": [ "" ] }, "address.latitude": { "type": "string", "examples": [ "-37.814000" ] }, "address.longitude": { "type": "string", "examples": [ "144.963100" ] }, "created_at": { "type": "string", "examples": [ "Jun 9, 2026, 3:36 PM" ] }, "created_at__date": { "type": "string", "examples": [ "Jun 9, 2026" ] }, "created_at__time": { "type": "string", "examples": [ "3:36 PM" ] }, "created_at__offset": { "type": "string", "examples": [ " (+10:00 AEST)" ] }, "created_at__offset_minutes": { "type": "integer", "examples": [ 600 ] }, "created_at__dayofweek": { "type": "string", "examples": [ "Tuesday" ] }, "end_timestamp": { "type": "string", "examples": [ "Sep 17, 2026, 11:00 PM" ] }, "end_timestamp__date": { "type": "string", "examples": [ "Sep 17, 2026" ] }, "end_timestamp__time": { "type": "string", "examples": [ "11:00 PM" ] }, "end_timestamp__offset": { "type": "string", "examples": [ " (+10:00 AEST)" ] }, "end_timestamp__offset_minutes": { "type": "integer", "examples": [ 600 ] }, "end_timestamp__dayofweek": { "type": "string", "examples": [ "Thursday" ] }, "event_shift_template_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_template_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_template_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_type_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_type_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_type_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "headcount_location_venue_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "is_virtual": { "type": "string", "examples": [ "No" ] }, "minimum_age": { "type": "string", "examples": [ "" ] }, "name": { "type": "string", "examples": [ "" ] }, "no_shift_time": { "type": "string", "examples": [ "No" ] }, "post_feedback_form": { "type": [ "string", "null" ], "examples": [ null ] }, "post_feedback_form:value": { "type": [ "string", "null" ], "examples": [ null ] }, "post_feedback_form:array": { "type": [ "string", "null" ], "examples": [ null ] }, "public": { "type": "string", "examples": [ "No" ] }, "publish": { "type": "string", "examples": [ "No" ] }, "role_offer_address": { "type": "string", "examples": [ "No" ] }, "role_offer_id": { "type": [ "string", "null" ], "examples": [ null ] }, "role_offer_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "role_offer_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "self_checkin": { "type": "string", "examples": [ "No" ] }, "shift_application_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_application_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_attended_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkin_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_checkout_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_precheckin_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id:value": { "type": [ "string", "null" ], "examples": [ null ] }, "shift_withdraw_form_id:array": { "type": [ "string", "null" ], "examples": [ null ] }, "start_timestamp": { "type": "string", "examples": [ "Sep 17, 2026, 3:00 PM" ] }, "start_timestamp__date": { "type": "string", "examples": [ "Sep 17, 2026" ] }, "start_timestamp__time": { "type": "string", "examples": [ "3:00 PM" ] }, "start_timestamp__offset": { "type": "string", "examples": [ " (+10:00 AEST)" ] }, "start_timestamp__offset_minutes": { "type": "integer", "examples": [ 600 ] }, "start_timestamp__dayofweek": { "type": "string", "examples": [ "Thursday" ] }, "updated_at": { "type": "string", "examples": [ "Aug 12, 2026, 3:00 PM" ] }, "updated_at__date": { "type": "string", "examples": [ "Aug 12, 2026" ] }, "updated_at__time": { "type": "string", "examples": [ "3:00 PM" ] }, "updated_at__offset": { "type": "string", "examples": [ " (+10:00 AEST)" ] }, "updated_at__offset_minutes": { "type": "integer", "examples": [ 600 ] }, "updated_at__dayofweek": { "type": "string", "examples": [ "Wednesday" ] }, "visibility_hide_groups": { "type": "string", "examples": [ "" ] }, "visibility_show_groups": { "type": "string", "examples": [ "" ] }, "visibility_show_roleoffer": { "type": "string", "examples": [ "" ] }, "info": { "type": "string", "examples": [ " - " ] }, "event_shift_link_id": { "type": [ "string", "null" ], "examples": [ null ] }, "event_shift_link_repeat": { "type": "integer", "examples": [ 0 ] }, "event_shift_link_name": { "type": "string", "examples": [ "" ] }, "shift_status_default_id": { "type": "integer", "examples": [ 1 ] }, "length": { "type": "integer", "examples": [ 8 ] }, "account_id": { "type": "integer", "examples": [ 20000 ] }, "account_url": { "type": "string", "examples": [ "https://example.rosterfy.com/" ] }, "is_any_leader": { "type": "boolean", "examples": [ false ] }, "post_shift_feedback_form_completed_at": { "type": "string", "examples": [ "" ] }, "pre_checkin_form_completed_at": { "type": "string", "examples": [ "" ] }, "event_name": { "type": [ "string", "null" ], "examples": [ null ] } } }, "relations": { "type": "object", "properties": {} }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "apply": { "type": "boolean", "examples": [ false ] }, "apply_error": { "type": "string", "examples": [ "Shift applications not open" ] }, "apply_error_code": { "type": "string", "examples": [ "ES0056" ] }, "is_unavailable": { "type": "boolean", "examples": [ false ] }, "confirm": { "type": "boolean", "examples": [ false ] }, "reject": { "type": "boolean", "examples": [ false ] }, "selfCheckin": { "type": "boolean", "examples": [ false ] }, "selfCheckout": { "type": "boolean", "examples": [ false ] }, "submitAttendedForm": { "type": "boolean", "examples": [ false ] }, "precheckin": { "type": "boolean", "examples": [ false ] }, "applyWaitlist": { "type": "boolean", "examples": [ false ] } } }, "attributes": { "type": "object", "properties": {} } }, "examples": [ { "object": { "id": 2001, "event_id": 1001, "event_shift_type_id": null, "event_shift_template_id": null, "journey_id": null, "min_demand": 2, "max_demand": 10, "leader_demand": 1, "start_timestamp": "2026-09-17 05:00:00", "end_timestamp": "2026-09-17 13:00:00", "timezone": "Australia/Melbourne", "no_shift_time": 0, "apps_open_timestamp": null, "apps_close_timestamp": null, "headcount_location_venue_id": null, "shift_status_default": 1, "shift_confirmed_status_default": 3, "shift_rejected_status_default": 6, "journey_complete_status": null, "shift_can_withdraw_default": 1, "shift_can_confirm": 1, "shift_can_confirm_limit": 0, "shift_can_withdraw_limit": 0, "shift_checked_in_status_default": 4, "shift_checked_out_status_default": 4, "certificate_id": null, "shift_application_form_id": null, "allow_application_form_resubmit": 0, "shift_checkin_form_id": null, "shift_attended_form_id": null, "shift_checkout_form_id": null, "shift_precheckin_form_id": null, "shift_withdraw_form_id": null, "training_ids": null, "visibility_show_groups": [], "visibility_hide_groups": [], "visibility_show_roleoffer": [], "role_offer_id": null, "role_offer_address": 0, "checkin_visible_attributes": [], "shift_enable_waitlist_default": 0, "max_waitlist": 0, "group_booking_ttl": null, "max_group_demand": null, "max_group_size": null, "reserved_expiry": null, "minimum_dob": null, "minimum_age": null, "maximum_dob": null, "maximum_age": null, "self_checkin": 0, "self_checkin_open": 1800, "self_checkin_close": 1800, "self_checkout_close": 1800, "checkin_close": 0, "shift_precheckin_open": 0, "break": 0, "post_feedback_form": null, "shift_leader_feedback_form_id": null, "is_virtual": 0, "geofence_checkin_limit": null, "tax": null, "price_excluding_tax": 0, "tax_percentage": null, "publish": 0, "public": 0, "sort_order": 0, "is_cancelled": 0, "deleted_at": null, "is_erased": 0, "is_draft": false, "created_at": "2026-06-09T05:36:11.000000Z", "updated_at": "2026-08-12T05:00:00.000000Z", "deleted_by": null, "cost_description": null, "event_shift_description": "", "name": null, "address": { "iso": "AUS", "region_code": "VIC", "coordinates": { "latitude": "-37.814000", "longitude": "144.963100" }, "street_address_1": "1 Example Street", "street_address_2": null, "street_address_3": null, "city": "Melbourne", "postcode": "3000", "region": "VIC", "country": "AU", "latitude": "-37.814000", "longitude": "144.963100" } }, "nice": { "rrn": "rrn:example:20000:shift:2001", "address": "1 Example Street\nMelbourne\nVictoria\nAustralia\n3000", "address_oneline": "1 Example Street, Melbourne, Victoria, Australia, 3000", "address.country": "Australia", "address.country:raw": "AUS", "address.city": "Melbourne", "address.region": "Victoria", "address.region:raw": "VIC", "address.postcode": "3000", "address.street_address_1": "1 Example Street", "address.street_address_2": "", "address.street_address_3": "", "address.latitude": "-37.814000", "address.longitude": "144.963100", "created_at": "Jun 9, 2026, 3:36 PM", "created_at__date": "Jun 9, 2026", "created_at__time": "3:36 PM", "created_at__offset": " (+10:00 AEST)", "created_at__offset_minutes": 600, "created_at__dayofweek": "Tuesday", "end_timestamp": "Sep 17, 2026, 11:00 PM", "end_timestamp__date": "Sep 17, 2026", "end_timestamp__time": "11:00 PM", "end_timestamp__offset": " (+10:00 AEST)", "end_timestamp__offset_minutes": 600, "end_timestamp__dayofweek": "Thursday", "event_shift_template_id": null, "event_shift_template_id:value": null, "event_shift_template_id:array": null, "event_shift_type_id": null, "event_shift_type_id:value": null, "event_shift_type_id:array": null, "headcount_location_venue_id": null, "headcount_location_venue_id:value": null, "headcount_location_venue_id:array": null, "is_virtual": "No", "minimum_age": "", "name": "", "no_shift_time": "No", "post_feedback_form": null, "post_feedback_form:value": null, "post_feedback_form:array": null, "public": "No", "publish": "No", "role_offer_address": "No", "role_offer_id": null, "role_offer_id:value": null, "role_offer_id:array": null, "self_checkin": "No", "shift_application_form_id": null, "shift_application_form_id:value": null, "shift_application_form_id:array": null, "shift_attended_form_id": null, "shift_attended_form_id:value": null, "shift_attended_form_id:array": null, "shift_checkin_form_id": null, "shift_checkin_form_id:value": null, "shift_checkin_form_id:array": null, "shift_checkout_form_id": null, "shift_checkout_form_id:value": null, "shift_checkout_form_id:array": null, "shift_precheckin_form_id": null, "shift_precheckin_form_id:value": null, "shift_precheckin_form_id:array": null, "shift_withdraw_form_id": null, "shift_withdraw_form_id:value": null, "shift_withdraw_form_id:array": null, "start_timestamp": "Sep 17, 2026, 3:00 PM", "start_timestamp__date": "Sep 17, 2026", "start_timestamp__time": "3:00 PM", "start_timestamp__offset": " (+10:00 AEST)", "start_timestamp__offset_minutes": 600, "start_timestamp__dayofweek": "Thursday", "updated_at": "Aug 12, 2026, 3:00 PM", "updated_at__date": "Aug 12, 2026", "updated_at__time": "3:00 PM", "updated_at__offset": " (+10:00 AEST)", "updated_at__offset_minutes": 600, "updated_at__dayofweek": "Wednesday", "visibility_hide_groups": "", "visibility_show_groups": "", "visibility_show_roleoffer": "", "info": " - ", "event_shift_link_id": null, "event_shift_link_repeat": 0, "event_shift_link_name": "", "shift_status_default_id": 1, "length": 8, "account_id": 20000, "account_url": "https://example.rosterfy.com/", "is_any_leader": false, "post_shift_feedback_form_completed_at": "", "pre_checkin_form_completed_at": "", "event_name": null }, "relations": {}, "permissions": { "read": true, "update": true, "delete": true, "apply": false, "apply_error": "Shift applications not open", "apply_error_code": "ES0056", "is_unavailable": false, "confirm": false, "reject": false, "selfCheckin": false, "selfCheckout": false, "submitAttendedForm": false, "precheckin": false, "applyWaitlist": false }, "attributes": {} } ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Do you want to also update the linked Shifts?" ] }, "reference": { "type": "string", "examples": [ "_options.update_linked_shifts" ] } }, "examples": [ { "message": "Do you want to also update the linked Shifts?", "reference": "_options.update_linked_shifts" } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Shift Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "What the shift is called. Shown to people choosing shifts.", "examples": [ null ] }, "timezone": { "type": "string", "description": "The timezone the start and end times are given in, as an IANA name such as `Australia/Melbourne`.", "examples": [ null ] }, "min_demand": { "type": "integer", "description": "The fewest people the shift needs. Defaults to 1.", "examples": [ 1 ] }, "max_demand": { "type": "integer", "description": "The most people the shift can take. Applications are refused once it is full.", "examples": [ 1 ] }, "leader_demand": { "type": "integer", "description": "How many of those places are for leaders. Defaults to 0.", "examples": [ 1 ] }, "start_timestamp": { "type": "string", "description": "When the shift starts, as `YYYY-MM-DD HH:MM:SS` in the shift's timezone.", "examples": [ null ] }, "end_timestamp": { "type": "string", "description": "When the shift ends, as `YYYY-MM-DD HH:MM:SS` in the shift's timezone.", "examples": [ null ] }, "is_virtual": { "type": "boolean", "description": "Whether the shift happens online rather than at a place.", "examples": [ true ] }, "event_shift_type_id": { "type": "integer", "description": "The shift type, which groups shifts for reporting and for the per-type application limits an event can set.", "examples": [ 1 ] }, "shift_status_default": { "type": "integer", "description": "The status a new application on this shift starts at.", "examples": [ 1 ] }, "shift_confirmed_status_default": { "type": "integer", "description": "The status an application moves to when it is confirmed.", "examples": [ 1 ] }, "shift_rejected_status_default": { "type": "integer", "description": "The status an application moves to when it is rejected.", "examples": [ 1 ] }, "shift_can_withdraw_default": { "type": "boolean", "description": "Whether people can withdraw from the shift themselves.", "examples": [ true ] }, "shift_can_withdraw_limit": { "type": "integer", "description": "How long before the shift starts withdrawing stops being allowed, in seconds.", "examples": [ 1 ] }, "shift_can_confirm": { "type": "boolean", "description": "Whether people can confirm their own place on the shift.", "examples": [ true ] }, "shift_can_confirm_limit": { "type": "integer", "description": "How long before the shift starts confirming stops being allowed, in seconds.", "examples": [ 1 ] }, "shift_checked_in_status_default": { "type": "integer", "description": "The status an assignment moves to on check-in.", "examples": [ 1 ] }, "shift_checked_out_status_default": { "type": "integer", "description": "The status an assignment moves to on check-out.", "examples": [ 1 ] }, "address": { "type": "object", "description": "Where the shift happens, as an address object. Required on a create unless the shift is virtual or takes its location from a venue.", "properties": {}, "examples": [ "{}" ] }, "headcount_location_venue_id": { "type": "integer", "description": "The venue the shift happens at. Sending one takes the location from the venue instead of from `address`.", "examples": [ 1 ] }, "certificate_id": { "type": "integer", "description": "A certificate awarded for attending the shift.", "examples": [ 1 ] }, "shift_application_form_id": { "type": "integer", "description": "The form someone fills in when applying for this shift.", "examples": [ 1 ] }, "allow_application_form_resubmit": { "type": "boolean", "description": "Whether someone can submit the application form again.", "examples": [ true ] }, "shift_precheckin_form_id": { "type": "integer", "description": "The form filled in at pre-check-in.", "examples": [ 1 ] }, "shift_checkin_form_id": { "type": "integer", "description": "The form filled in at check-in.", "examples": [ 1 ] }, "shift_attended_form_id": { "type": "integer", "description": "The form filled in once the shift has been attended.", "examples": [ 1 ] }, "shift_checkout_form_id": { "type": "integer", "description": "The form filled in at check-out.", "examples": [ 1 ] }, "shift_withdraw_form_id": { "type": "integer", "description": "The form filled in when withdrawing.", "examples": [ 1 ] }, "visibility_show_groups": { "type": "array", "description": "Only members of these groups can see the shift.", "items": { "type": "integer" }, "examples": [ [] ] }, "visibility_hide_groups": { "type": "array", "description": "Members of these groups cannot see the shift.", "items": { "type": "integer" }, "examples": [ [] ] }, "visibility_show_roleoffer": { "type": "array", "description": "Only people holding one of these role offers can see the shift.", "items": { "type": "integer" }, "examples": [ [] ] }, "apps_open_timestamp": { "type": "string", "description": "When applications open. Before this, applying is refused.", "examples": [ null ] }, "apps_close_timestamp": { "type": "string", "description": "When applications close. After this, applying is refused.", "examples": [ null ] }, "role_offer_id": { "type": "integer", "description": "The role offer this shift belongs to.", "examples": [ 1 ] }, "role_offer_address": { "type": "boolean", "description": "Take the shift's location from the role offer rather than from `address`.", "examples": [ true ] }, "shift_precheckin_open": { "type": "integer", "description": "How long before the shift starts pre-check-in opens, in seconds.", "examples": [ 1 ] }, "max_group_demand": { "type": "integer", "description": "How many places a single group booking can take.", "examples": [ 1 ] }, "group_booking_ttl": { "type": "integer", "description": "How long a group booking is held before it lapses, in seconds.", "examples": [ 1 ] }, "max_group_size": { "type": "integer", "description": "The largest group that can book onto the shift.", "examples": [ 1 ] }, "reserved_expiry": { "type": "integer", "description": "How long a reserved place is held before it lapses, in seconds.", "examples": [ 1 ] }, "self_checkin": { "type": "boolean", "description": "Whether people can check themselves in to the shift.", "examples": [ true ] }, "self_checkin_open": { "type": "integer", "description": "How long before the shift starts self check-in opens, in seconds.", "examples": [ 1 ] }, "self_checkin_close": { "type": "integer", "description": "How long after the shift starts self check-in closes, in seconds.", "examples": [ 1 ] }, "self_checkout_close": { "type": "integer", "description": "How long after the shift ends self check-out closes, in seconds.", "examples": [ 1 ] }, "checkin_close": { "type": "integer", "description": "How long after the shift ends check-in closes, in seconds.", "examples": [ 1 ] }, "geofence_checkin_limit": { "type": "integer", "description": "How close to the shift's location someone has to be to check in, in metres.", "examples": [ 1 ] }, "checkin_visible_attributes": { "type": "array", "description": "Which of a person's attributes are shown on the check-in screen.", "items": { "type": "integer" }, "examples": [ [] ] }, "training_ids": { "type": "array", "description": "Training people must have completed before they can be placed on the shift.", "items": { "type": "integer" }, "examples": [ [] ] }, "post_feedback_form": { "type": "integer", "description": "The form people fill in about the shift afterwards.", "examples": [ 1 ] }, "shift_leader_feedback_form_id": { "type": "integer", "description": "The form a leader fills in about the shift.", "examples": [ 1 ] }, "shift_enable_waitlist_default": { "type": "boolean", "description": "Whether people can join a waitlist once the shift is full.", "examples": [ true ] }, "max_waitlist": { "type": "integer", "description": "How many people the waitlist holds.", "examples": [ 1 ] }, "publish": { "type": "boolean", "description": "Whether the shift is visible to people who can apply for it. Ignored from a caller who cannot publish shifts.", "examples": [ true ] }, "public": { "type": "boolean", "description": "Whether the shift can be seen without signing in, on a public event.", "examples": [ true ] }, "is_cancelled": { "type": "boolean", "description": "Whether the shift is cancelled. Cancelling this way does not move anyone already on the shift; use the cancel endpoint for that.", "examples": [ true ] }, "sort_order": { "type": "integer", "description": "Where the shift sits when shifts are shown in a fixed order.", "examples": [ 1 ] }, "minimum_dob": { "type": "string", "description": "Latest date of birth allowed on the shift. Cannot be sent together with `minimum_age`.", "examples": [ null ] }, "minimum_age": { "type": "string", "description": "Youngest age allowed on the shift, as `years:months`.", "examples": [ null ] }, "maximum_dob": { "type": "string", "description": "Earliest date of birth allowed on the shift. Cannot be sent together with `maximum_age`.", "examples": [ null ] }, "maximum_age": { "type": "string", "description": "Oldest age allowed on the shift, as `years:months`.", "examples": [ null ] }, "price_excluding_tax": { "type": "number", "description": "What taking this shift costs the person, before tax.", "examples": [ 1.23 ] }, "tax_percentage": { "type": "integer", "description": "Tax charged on the price, as a percentage between 0 and 100.", "examples": [ 1 ] }, "cost_description": { "type": "string", "description": "Free text shown alongside the price.", "examples": [ null ] }, "custom_*": { "type": "string", "description": "A custom attribute, named by its code - custom_shirt_size, for example. The value follows the attribute's own type, so it may be a string, a number, a boolean or a list. See the custom attributes documentation.", "examples": [ null ] } } } } } } }, "delete": { "summary": "Delete a shift", "operationId": "deleteAShift", "description": "Removes a shift from the event.\n\n**This returns a 200 carrying `{\"messages\": null}`, not the 204 the rest of the API\nreturns for a delete.** `messages` is normally null and carries a note when\nsomething about the deletion is worth telling the caller.\n\nTwo things can interrupt it, and both are questions rather than failures.\n\nA shift in a linked series comes back as a 400 carrying `reference: \"repeat\"`,\nwhich you answer by sending `repeat`: true also deletes every later shift in the\nseries and drops the people following it, false deletes this shift alone.\n\nA shift people already hold places on comes back as a 405 saying how many they are\nand carrying the key to confirm with in `reference`. Send that key back **in the\nquery string, as an array**, keeping the rest of the request the same:\n`?override[]=event.shift.delete.demand`. Two things to know about it. The key in\n`reference` is prefixed - send the part after `override_system_limits.`, not the\nwhole string. And it has to be the array form: `?override=event.shift.delete.demand`\nis a 500, and sending it in the JSON body is not seen at all and simply repeats the\n405.\n\nThe shift has to belong to the event in the URL; a mismatch is a 404.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": [ "string", "null" ], "examples": [ null ] } }, "examples": [ { "messages": null } ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Do you want to delete all linked Shifts after this one?" ] }, "reference": { "type": "string", "examples": [ "repeat" ] } }, "examples": [ { "message": "Do you want to delete all linked Shifts after this one?", "reference": "repeat" } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } }, "405": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "There are 1 Users still scheduled onto this Shift" ] }, "reference": { "type": "string", "examples": [ "override_system_limits.event.shift.delete.demand" ] } }, "examples": [ { "message": "There are 1 Users still scheduled onto this Shift", "reference": "override_system_limits.event.shift.delete.demand" } ] } } } } }, "tags": [ "Shift Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "repeat": { "type": "boolean", "description": "Also delete every later shift linked to this one. Only meaningful on a shift that belongs to a linked series, and required there - see the description.", "examples": [ true ] } } } } } } }, "parameters": [ { "in": "path", "name": "event_id", "description": "The ID of the event.", "required": true, "schema": { "type": "integer", "examples": [ 1001 ] } }, { "in": "path", "name": "id", "description": "The ID of the shift.", "required": true, "schema": { "type": "integer", "examples": [ 2001 ] } } ] }, "/api/v2/reward-point/user/{id}": { "get": { "summary": "Read a reward point balance", "operationId": "readARewardPointBalance", "description": "Returns one user's reward point balance: how many points they hold now, and\nwho they belong to.\n\nThe record is the running total only. It does not carry the transactions that\nproduced it, and there is no history in this response - read the reward point\ntransactions for that.\n\nThe ID in the URL is the balance record's own ID, not the user's. To go from a\nuser to their balance, list the balances and filter on `user_id`.\n\n`permissions` always reports update and delete as unavailable: a balance is\nderived from the transactions recorded against it and is not writable through\nthe API.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "account_id": { "type": "integer", "examples": [ 20101 ] }, "user_id": { "type": "integer", "examples": [ 1234 ] }, "balance": { "type": "integer", "examples": [ 1250 ] }, "created_at": { "type": "string", "examples": [ "2026-08-06T01:07:51.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-08-06T01:07:51.000000Z" ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "relations": { "type": "object", "properties": {} }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ false ] }, "delete": { "type": "boolean", "examples": [ false ] } } } }, "examples": [ { "object": { "id": 1, "account_id": 20101, "user_id": 1234, "balance": 1250, "created_at": "2026-08-06T01:07:51.000000Z", "updated_at": "2026-08-06T01:07:51.000000Z", "deleted_at": null }, "nice": [], "relations": {}, "permissions": { "read": true, "update": false, "delete": false } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Reward Point" ] }, "parameters": [ { "in": "path", "name": "id", "description": "The ID of the reward point balance record.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/automatic-rostering/event-shift": { "put": { "summary": "Roster people onto shifts", "operationId": "rosterPeopleOntoShifts", "description": "Fills a set of an event's shifts from a pool of people - a user group, the\naccepted applicants of a role offer, or an uploaded file - creating a shift\napplication for each person placed.\n\n**This write is queued, and the response carries no way to follow it.** A 200\nmeans the request passed validation and the work was handed off, nothing more.\nThe body is a fixed confirmation message with no identifier in it, so there is\nno request to poll and no way to be told when the rostering has finished or\nwhat it did. Confirm the outcome by listing the event's shift applications and\nlooking for the new rows. Do not treat the response as meaning anyone has been\nrostered.\n\nChoose the shifts either way round:\n\n- Send `applyTo` as `selected` with `selected` holding the shift IDs to fill.\n- Send any other `applyTo` value to fill every shift on the event the caller can\n see, narrowed by an optional `filter`.\n\nThen choose the people with `source`, and supply whichever field that source\nneeds: `group_id` for `group`, `role_offer_id` for `role_offer`, `file` for\n`import`. A `source` that is none of those three is accepted and rosters nobody.\n\nHow many people go onto each shift is decided by that shift's own demand, so a\nshift that is already full takes nobody. Running the same request twice is\ntherefore close to safe, though it will consider the same people again unless\n`bypass_scheduled` is set.\n\nInvalid input returns a 422 before anything is queued.\n\nNote that `applyTo` is spelled in camelCase, unlike every other parameter on\nthis endpoint.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Mass operation succeeded" ] } }, "examples": [ { "message": "Mass operation succeeded" } ] } } } } }, "tags": [ "Automatic Rostering" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_id": { "type": "integer", "description": "The event whose shifts are to be filled. Required in practice - a request without it is accepted and then rosters nobody.", "examples": [ 1 ] }, "group_id": { "type": "integer", "description": "The user group to roster from. Required when source is `group`.", "examples": [ 1 ] }, "headcount_functional_area_id": { "type": "array", "description": "Limits rostering to shifts in these functional areas. Applies when source is `role_offer` and specific_role is not set.", "items": { "type": "integer" }, "examples": [ [] ] }, "role_offer_id": { "type": "integer", "description": "The role offer whose accepted applicants are rostered. Used when source is `role_offer`. Leave it out to roster each shift from whichever role offer that shift is already tied to.", "examples": [ 1 ] }, "specific_role": { "type": "boolean", "description": "Send `1` with source `role_offer` to roster only the role offer named in role_offer_id, rather than matching each shift to its own role offer.", "examples": [ true ] }, "event_shift_status_id": { "type": "integer", "description": "The status each new shift application is created with, from the event_shift_status option set. This is what decides whether the people rostered are placed as confirmed, pending approval, or something else.", "examples": [ 1 ] }, "applyTo": { "type": "string", "description": "Send `selected` to fill only the shifts named in selected. Any other value fills every shift on the event that the caller can see, narrowed by filter if one is sent.", "examples": [ null ] }, "selected": { "type": "array", "description": "The IDs of the shifts to fill. Read when applyTo is `selected`, and ignored otherwise.", "items": { "type": "integer" }, "examples": [ [] ] }, "bypass_scheduled": { "type": "boolean", "description": "Send `1` to skip anyone already rostered onto the shifts in scope, so a repeated request does not consider them again.", "examples": [ true ] }, "source": { "type": "string", "description": "Where the people come from: `group` to use a user group, `role_offer` to use the accepted applicants of a role offer, or `import` to upload a file of them. Any other value is accepted and rosters nobody.", "examples": [ null ] }, "filter": { "type": "array", "description": "Narrows which of the event's shifts are filled, in the same form the shift listing accepts. Read only when applyTo is not `selected`.", "items": { "type": "object" }, "examples": [ [] ] }, "file": { "type": "string", "description": "The file of people to roster, as a multipart upload. Required when source is `import`, rejected as an unsupported format otherwise. Accepts the same spreadsheet and CSV formats as an import.", "examples": [ null ] } }, "required": [ "event_id", "event_shift_status_id", "applyTo", "source" ] } } } } } }, "/api/v2/helpers/source/{module}": { "get": { "summary": "Read an option set", "operationId": "readAnOptionSet", "description": "Returns the values a given field accepts, as a flat list of `value` and `text`\npairs. `value` is what you send back on a write; `text` is the label the same\nthing is shown under in the console. Use this instead of hard-coding IDs, which\ndiffer from one account to the next.\n\nThe list is not paginated and carries no envelope - the whole set comes back in\none array, ordered as the option set defines.\n\nThe set named in the URL decides what you get. Common ones are:\n\n| Option set | Values for |\n|---|---|\n| `event_type` | An event's type |\n| `event_template` | The template an event can be created from |\n| `event_shift_status` | A shift application's status |\n| `event_shift_type` | A shift's type |\n| `event_shift_status_type` | The category a shift status belongs to |\n| `shift_template` | The template a shift can be created from |\n| `user_type` | A user's type |\n| `user_group`, `user_group_type` | A user's group, and the group's type |\n| `user_checkpoint`, `user_checkpoint_type` | A user's checkpoint, and its type |\n| `training_type` | A training module's type |\n| `form_type`, `form_category` | A form's type and category |\n| `report_category` | A report's category |\n| `blog_article_type` | An article's type |\n| `item_category` | An inventory item's category |\n| `headcount_functionalarea` | A functional area |\n| `headcount_functionalarea_type` | A functional area's type |\n| `headcount_functionalarea_job_title` | A job title within a functional area |\n| `headcount_location`, `headcount_location_type` | A location and its type |\n| `headcount_location_venue` | A venue within a location |\n| `headcount_journey` | A journey |\n\nFurther sets exist beyond this list, and which of them a caller can read depends\non the permissions that caller holds.\n\nA few sets are narrowed by a further value - `headcount_location_venue` by\n`headcount_location_id`, for instance, and `headcount_functionalarea_job_title`\nby `headcount_functional_area_id`. Send that value as a query parameter. Where\nthe narrowing value is mandatory and is missing, the response is an empty array\nrather than an error.", "parameters": [ { "in": "query", "name": "assoc", "description": "Send `0` to keep any extra keys an option set carries beyond value\n and text, such as the group a shift status belongs to. Defaults to 1, which returns value\n and text only.", "required": false, "schema": { "type": "integer", "description": "Send `0` to keep any extra keys an option set carries beyond value\n and text, such as the group a shift status belongs to. Defaults to 1, which returns value\n and text only.", "examples": [ 0 ] } }, { "in": "query", "name": "active", "description": "Send `1` to limit the list to options that are currently in use.\n Not every option set distinguishes active options, and those that do not return the full\n list either way.", "required": false, "schema": { "type": "integer", "description": "Send `1` to limit the list to options that are currently in use.\n Not every option set distinguishes active options, and those that do not return the full\n list either way.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "Narrows the list, in the same form the listing endpoints accept.\n Only option sets backed by a record type support it; the rest ignore it.", "example": null, "required": false, "schema": { "type": "array", "description": "Narrows the list, in the same form the listing endpoints accept.\n Only option sets backed by a record type support it; the rest ignore it.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "integer", "examples": [ 1 ] }, "text": { "type": "string", "examples": [ "Applied" ] } } }, "examples": [ [ { "value": 1, "text": "Applied" }, { "value": 2, "text": "Pending" }, { "value": 3, "text": "Confirmed" }, { "value": 4, "text": "Attended" }, { "value": 5, "text": "Emergency" }, { "value": 6, "text": "Rejected" }, { "value": 7, "text": "Waitlist" }, { "value": 8, "text": "Cancelled" }, { "value": 9, "text": "Conflict" }, { "value": 10, "text": "No Show" }, { "value": 11, "text": "Checked In" }, { "value": 12, "text": "Not Approved" }, { "value": 13, "text": "Expired" } ] ] } } } } }, "tags": [ "Utilities" ] }, "parameters": [ { "in": "path", "name": "module", "description": "The option set to read.", "required": true, "schema": { "type": "string", "examples": [ "event_shift_status" ] } } ] }, "/api/v2/form": { "get": { "summary": "List forms", "operationId": "listForms", "description": "Returns the forms in the account you are calling as, together with the forms it\ninherits from the accounts above it.\n\nThis is an administration endpoint. It answers only for callers who may read\nforms and who are calling as the admin console; for anyone else it answers as\nthough it does not exist. A caller who only needs to fill a form in should read\nit through `GET /form/{id}/view` instead, or through the endpoint of whatever the\nform is attached to.\n\n`is_submissions_listing` and `is_admin_submissions_listing` narrow the result to\nthe forms behind the two submission listings, and are mutually exclusive - if\nboth are sent, the admin one wins.", "parameters": [ { "in": "query", "name": "is_submissions_listing", "description": "Return only forms whose submissions are\n collected from the people filling them in, excluding admin submission forms.", "required": false, "schema": { "type": "boolean", "description": "Return only forms whose submissions are\n collected from the people filling them in, excluding admin submission forms.", "examples": [ true ] } }, { "in": "query", "name": "is_admin_submissions_listing", "description": "Return only admin submission\n forms - the ones an administrator completes about somebody else.", "required": false, "schema": { "type": "boolean", "description": "Return only admin submission\n forms - the ones an administrator completes about somebody else.", "examples": [ true ] } }, { "in": "query", "name": "report_type_id", "description": "Narrow the result to the forms a report of this\n type can be built from.", "required": false, "schema": { "type": "integer", "description": "Narrow the result to the forms a report of this\n type can be built from.", "examples": [ 3 ] } }, { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 37 ] }, "form_type_id": { "type": "integer", "examples": [ 15 ] }, "name": { "type": "string", "examples": [ "Volunteer Application" ] }, "form_title": { "type": "string", "examples": [ "Volunteer Application" ] }, "form_category_id": { "type": [ "string", "null" ], "examples": [ null ] }, "success_content": { "type": "string", "examples": [ "" ] }, "close_content": { "type": "string", "examples": [ "" ] }, "options": { "type": "array", "examples": [ [] ] }, "rules": { "type": "array", "examples": [ [] ] }, "cost": { "type": "string", "examples": [ "0.00" ] }, "tax_percentage": { "type": "string", "examples": [ "0.00" ] }, "close_at": { "type": [ "string", "null" ], "examples": [ null ] }, "public": { "type": "integer", "examples": [ 0 ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "token": { "type": "string", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:25.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:25.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:form:37" ] }, "is_open": { "type": "string", "examples": [ "Yes" ] }, "close_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_foreign_account": { "type": "boolean", "examples": [ false ] } } }, "relations": { "type": "object", "properties": { "form_type": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 15 ] }, "name": { "type": "string", "examples": [ "User Interaction - New answers for new submissions" ] }, "code": { "type": "string", "examples": [ "user_submission" ] }, "main_entity": { "type": "string", "examples": [ "user_form_submission" ] }, "entities": { "type": "object", "properties": { "user_form_submission": { "type": "object", "properties": { "create": { "type": "boolean", "examples": [ true ] } } } } }, "public_field": { "type": "object", "properties": { "form_title": { "type": "object", "properties": { "rules": { "type": "string", "examples": [ "required|json" ] }, "validation": { "type": "string", "examples": [ "required" ] } } }, "close_content": { "type": "object", "properties": { "rules": { "type": "string", "examples": [ "nullable|json" ] }, "validation": { "type": "string", "examples": [ "string" ] } } }, "success_content": { "type": "object", "properties": { "rules": { "type": "string", "examples": [ "required|json" ] }, "validation": { "type": "string", "examples": [ "required" ] } } } } }, "access": { "type": "string", "examples": [ "form" ] } } } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ false ] }, "copy": { "type": "boolean", "examples": [ false ] } } } } }, "examples": [ [ { "object": { "id": 37, "form_type_id": 15, "name": "Volunteer Application", "form_title": "Volunteer Application", "form_category_id": null, "success_content": "", "close_content": "", "options": [], "rules": [], "cost": "0.00", "tax_percentage": "0.00", "close_at": null, "public": 0, "is_archived": 0, "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "deleted_at": null, "created_at": "2026-06-09T05:36:25.000000Z", "updated_at": "2026-06-09T05:36:25.000000Z", "deleted_by": null }, "nice": { "rrn": "rrn:local:20101:form:37", "is_open": "Yes", "close_at": null, "is_foreign_account": false }, "relations": { "form_type": { "id": 15, "name": "User Interaction - New answers for new submissions", "code": "user_submission", "main_entity": "user_form_submission", "entities": { "user_form_submission": { "create": true } }, "public_field": { "form_title": { "rules": "required|json", "validation": "required" }, "close_content": { "rules": "nullable|json", "validation": "string" }, "success_content": { "rules": "required|json", "validation": "required" } }, "access": "form" } }, "permissions": { "read": true, "update": true, "delete": false, "copy": false } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/form?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/form?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/form" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 37, "form_type_id": 15, "name": "Volunteer Application", "form_title": "Volunteer Application", "form_category_id": null, "success_content": "", "close_content": "", "options": [], "rules": [], "cost": "0.00", "tax_percentage": "0.00", "close_at": null, "public": 0, "is_archived": 0, "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "deleted_at": null, "created_at": "2026-06-09T05:36:25.000000Z", "updated_at": "2026-06-09T05:36:25.000000Z", "deleted_by": null }, "nice": { "rrn": "rrn:local:20101:form:37", "is_open": "Yes", "close_at": null, "is_foreign_account": false }, "relations": { "form_type": { "id": 15, "name": "User Interaction - New answers for new submissions", "code": "user_submission", "main_entity": "user_form_submission", "entities": { "user_form_submission": { "create": true } }, "public_field": { "form_title": { "rules": "required|json", "validation": "required" }, "close_content": { "rules": "nullable|json", "validation": "string" }, "success_content": { "rules": "required|json", "validation": "required" } }, "access": "form" } }, "permissions": { "read": true, "update": true, "delete": false, "copy": false } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/form?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/form?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/form", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Form Module" ] }, "post": { "summary": "Create a form", "operationId": "createAForm", "description": "Creates an empty form in the account you are calling as. The response is the\ncreated form, carrying only the fields the create set - read it back with\n`GET /form/{id}` for the full shape.\n\nA form is created with no fields. Add them through the field resource beneath it\nbefore publishing it, or send `_options[from_template]` to build it from one of\nthe account's form templates, which copies the template's name and type and\nsaves you sending either.\n\n`form_type_id` cannot be changed afterwards, so it is worth getting right: it\ndecides what submitting the form does. Sub-account registration forms\nadditionally require `options[account_type_id]`.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "options": { "type": "array", "examples": [ [] ] }, "rules": { "type": "array", "examples": [ [] ] }, "name": { "type": "string", "examples": [ "Volunteer Application" ] }, "form_type_id": { "type": "integer", "examples": [ 15 ] }, "token": { "type": "string", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] }, "updated_at": { "type": "string", "examples": [ "2026-08-17T04:58:45.000000Z" ] }, "created_at": { "type": "string", "examples": [ "2026-08-17T04:58:45.000000Z" ] }, "id": { "type": "integer", "examples": [ 47 ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:form:47" ] }, "is_open": { "type": "string", "examples": [ "Yes" ] }, "close_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_foreign_account": { "type": "boolean", "examples": [ false ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ true ] }, "copy": { "type": "boolean", "examples": [ false ] } } } }, "examples": [ { "object": { "options": [], "rules": [], "name": "Volunteer Application", "form_type_id": 15, "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "updated_at": "2026-08-17T04:58:45.000000Z", "created_at": "2026-08-17T04:58:45.000000Z", "id": 47 }, "nice": { "rrn": "rrn:local:20101:form:47", "is_open": "Yes", "close_at": null, "is_foreign_account": false }, "relations": [], "permissions": { "read": true, "update": true, "delete": true, "copy": false } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Form Module" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "_options": { "type": "object", "description": "Create-time options that are not stored on the form.", "properties": { "from_template": { "type": "integer", "description": "The id of a form template to build this\n form from. The template supplies the name and the form type, so neither has to\n be sent; a `name` you do send is kept.", "examples": [ 8 ] } }, "examples": [ [] ] }, "name": { "type": "string", "description": "The name administrators see for this form in the admin console. Not shown to the people filling it in.", "examples": [ "Volunteer Application" ] }, "form_type_id": { "type": "integer", "description": "What the form is for, and therefore what submitting it creates - a user registration, a standalone submission, an update to a user, and so on. Cannot be changed once the form exists. Read the available types from the form type resource.", "examples": [ 15 ] }, "form_title": { "type": "string", "description": "The title shown at the top of the form to the people filling it in. May be sent as a plain string, or as an object keyed by locale code to give each language its own title.", "examples": [ "Volunteer Application" ] }, "success_content": { "type": "string", "description": "HTML shown after the form is submitted successfully. Accepts a locale-keyed object in the same way as the title.", "examples": [ "" ] }, "close_content": { "type": "string", "description": "HTML shown in place of the form once it has closed. Accepts a locale-keyed object in the same way as the title.", "examples": [ "" ] }, "form_category_id": { "type": "integer", "description": "The category the form is filed under in the admin console.", "examples": [ 1 ] }, "options": { "type": "object", "description": "Form-wide settings. The keys available depend on the form type; send the object back as you read it, changing only what you mean to change.", "properties": {}, "examples": [ [] ] }, "rules": { "type": "object", "description": "Visibility rules deciding which fields are shown, keyed by field. Sending an invalid rule set is rejected rather than partially applied.", "properties": {}, "examples": [ [] ] }, "public": { "type": "boolean", "description": "Whether the form may be opened without signing in. Only takes effect on anonymous forms; every other type still requires a signed-in caller.", "examples": [ 0 ] }, "is_archived": { "type": "boolean", "description": "Whether the form is archived. Archived forms stay readable but are filtered out of the admin console listings.", "examples": [ 0 ] } }, "required": [ "name", "form_type_id" ] } } } } } }, "/api/v2/form/{id}": { "put": { "summary": "Update a form", "operationId": "updateAForm", "description": "Updates a form's settings and returns it, the same shape as reading it back.\nFields you leave out keep their current values, so a partial body is safe.\n\n**What is required depends on the form type.** Each type declares its own\nrequired settings on top of the rules below - most types require `form_title` and\n`success_content`, so a request that omits them is rejected even though nothing\nhere marks them required. Read the form first and send those values back with\nyour change.\n\n**`close_at` is only kept if `close_form` is sent with it.** Send both to schedule\na closing time; send neither and any existing closing time is cleared. This is the\none field on this endpoint that a partial body does not leave alone.\n\nThe form type itself cannot be changed after creation and is not accepted here.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 37 ] }, "form_type_id": { "type": "integer", "examples": [ 15 ] }, "name": { "type": "string", "examples": [ "Volunteer Application" ] }, "form_title": { "type": "string", "examples": [ "Volunteer Application" ] }, "form_category_id": { "type": [ "string", "null" ], "examples": [ null ] }, "success_content": { "type": "string", "examples": [ "" ] }, "close_content": { "type": "string", "examples": [ "" ] }, "options": { "type": "array", "examples": [ [] ] }, "rules": { "type": "array", "examples": [ [] ] }, "cost": { "type": "string", "examples": [ "0.00" ] }, "tax_percentage": { "type": "string", "examples": [ "0.00" ] }, "close_at": { "type": [ "string", "null" ], "examples": [ null ] }, "public": { "type": "integer", "examples": [ 0 ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "token": { "type": "string", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:25.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:25.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:form:37" ] }, "is_open": { "type": "string", "examples": [ "Yes" ] }, "close_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_foreign_account": { "type": "boolean", "examples": [ false ] } } }, "relations": { "type": "object", "properties": { "form_type": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 15 ] }, "name": { "type": "string", "examples": [ "User Interaction - New answers for new submissions" ] }, "code": { "type": "string", "examples": [ "user_submission" ] }, "main_entity": { "type": "string", "examples": [ "user_form_submission" ] }, "entities": { "type": "object", "properties": { "user_form_submission": { "type": "object", "properties": { "create": { "type": "boolean", "examples": [ true ] } } } } }, "public_field": { "type": "object", "properties": { "form_title": { "type": "object", "properties": { "rules": { "type": "string", "examples": [ "required|json" ] }, "validation": { "type": "string", "examples": [ "required" ] } } }, "close_content": { "type": "object", "properties": { "rules": { "type": "string", "examples": [ "nullable|json" ] }, "validation": { "type": "string", "examples": [ "string" ] } } }, "success_content": { "type": "object", "properties": { "rules": { "type": "string", "examples": [ "required|json" ] }, "validation": { "type": "string", "examples": [ "required" ] } } } } }, "access": { "type": "string", "examples": [ "form" ] } } } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ false ] }, "copy": { "type": "boolean", "examples": [ false ] } } } }, "examples": [ { "object": { "id": 37, "form_type_id": 15, "name": "Volunteer Application", "form_title": "Volunteer Application", "form_category_id": null, "success_content": "", "close_content": "", "options": [], "rules": [], "cost": "0.00", "tax_percentage": "0.00", "close_at": null, "public": 0, "is_archived": 0, "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "deleted_at": null, "created_at": "2026-06-09T05:36:25.000000Z", "updated_at": "2026-06-09T05:36:25.000000Z", "deleted_by": null }, "nice": { "rrn": "rrn:local:20101:form:37", "is_open": "Yes", "close_at": null, "is_foreign_account": false }, "relations": { "form_type": { "id": 15, "name": "User Interaction - New answers for new submissions", "code": "user_submission", "main_entity": "user_form_submission", "entities": { "user_form_submission": { "create": true } }, "public_field": { "form_title": { "rules": "required|json", "validation": "required" }, "close_content": { "rules": "nullable|json", "validation": "string" }, "success_content": { "rules": "required|json", "validation": "required" } }, "access": "form" } }, "permissions": { "read": true, "update": true, "delete": false, "copy": false } } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } } }, "tags": [ "Form Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "close_form": { "type": "boolean", "description": "Whether the form should close automatically. Send it\n together with `close_at`; without it the closing time is cleared.", "examples": [ true ] }, "name": { "type": "string", "description": "The name administrators see for this form in the admin console. Not shown to the people filling it in.", "examples": [ "Volunteer Application" ] }, "form_title": { "type": "string", "description": "The title shown at the top of the form to the people filling it in. May be sent as a plain string, or as an object keyed by locale code to give each language its own title.", "examples": [ "Volunteer Application" ] }, "success_content": { "type": "string", "description": "HTML shown after the form is submitted successfully. Accepts a locale-keyed object in the same way as the title.", "examples": [ "" ] }, "options": { "type": "object", "description": "Form-wide settings. The keys available depend on the form type; send the object back as you read it, changing only what you mean to change.", "properties": {}, "examples": [ [] ] }, "rules": { "type": "object", "description": "Visibility rules deciding which fields are shown, keyed by field. Sending an invalid rule set is rejected rather than partially applied.", "properties": {}, "examples": [ [] ] }, "public": { "type": "boolean", "description": "Whether the form may be opened without signing in. Only takes effect on anonymous forms; every other type still requires a signed-in caller.", "examples": [ 0 ] }, "is_archived": { "type": "boolean", "description": "Whether the form is archived. Archived forms stay readable but are filtered out of the admin console listings.", "examples": [ 0 ] }, "close_content": { "type": "string", "description": "HTML shown in place of the form once it has closed. Accepts a locale-keyed object in the same way as the title.", "examples": [ "" ] }, "form_category_id": { "type": "integer", "description": "The category the form is filed under in the admin console.", "examples": [ 1 ] }, "close_at": { "type": "string", "description": "When the form stops accepting submissions, as `YYYY-MM-DD HH:MM:SS`. Only honoured when `close_form` is sent with it; without that the value is cleared.", "examples": [ null ] }, "cost": { "type": "number", "description": "What submitting the form costs, for the form types that take a payment.", "examples": [ "0.00" ] }, "tax_percentage": { "type": "number", "description": "Tax applied to `cost`, as a percentage between 0 and 100.", "examples": [ "0.00" ] } } } } } } }, "delete": { "summary": "Delete a form", "operationId": "deleteAForm", "description": "Deletes a form. Its fields and its submissions go with it.\n\nA form that one of the account's settings points at cannot be deleted - the\nregistration form, the shift application form and the rest. Clear the setting\nfirst, or archive the form instead with `is_archived`.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "204": { "description": "No content, successful deletion", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": [ "object", "null" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Cannot delete form - it is being used in an account setting." ] } }, "examples": [ { "message": "Cannot delete form - it is being used in an account setting." } ] } } } } }, "tags": [ "Form Module" ] }, "parameters": [ { "in": "path", "name": "id", "description": "The ID of the form.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/form/{form_id}/view": { "get": { "summary": "Render a form", "operationId": "renderAForm", "description": "Returns everything needed to draw a form and fill it in: its fields in order, each\none's type, label, validation bounds and option list, the title and the content\nshown on success, and the values already held for whoever is asking. Submit the\nresult to `POST /form/{id}/process`.\n\n**This endpoint does not require a token.** Anonymous forms that the account has\nmarked public can be rendered by anyone holding the form's id or its token - that\nis what makes a public sign-up link work. Every other form, including an anonymous\nform that has not been made public, requires a signed-in caller who may use it,\nand answers as though it does not exist otherwise. When a form is rendered without\na token the response carries `recaptcha: true`, and the submission that follows\nmust include a reCAPTCHA response.\n\nEither the form's numeric id or its `token` may be used in the path.\n\nA form that has closed returns its closing content rather than its fields. An\nadministrator can still preview a closed form by sending `preview`.\n\nSend `user_id` to fill the form in on behalf of somebody else; the form type\ndecides which entity ids are required alongside it, and a request missing one is\nrejected. Send `user_form_submission_id` to reopen an existing submission - it\nmust belong to this form. Where the form's content contains merge fields, an\nexisting submission renders them against whoever originally submitted it rather\nthan against whoever is reading it.", "parameters": [ { "in": "query", "name": "user_id", "description": "Fill the form in on behalf of this user.", "required": false, "schema": { "type": "integer", "description": "Fill the form in on behalf of this user.", "examples": [ 23453473 ] } }, { "in": "query", "name": "user_form_submission_id", "description": "Reopen this existing submission. Must\n belong to the form in the path.", "required": false, "schema": { "type": "integer", "description": "Reopen this existing submission. Must\n belong to the form in the path.", "examples": [ 2 ] } }, { "in": "query", "name": "preview", "description": "Render a closed form anyway. Administrators only.", "required": false, "schema": { "type": "boolean", "description": "Render a closed form anyway. Administrators only.", "examples": [ true ] } }, { "in": "query", "name": "_locale", "description": "Render labels and content in this locale.", "required": false, "schema": { "type": "string", "description": "Render labels and content in this locale.", "examples": [ "en" ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "examples": [ "user:custom_textarea_attribute" ] }, "type": { "type": "string", "examples": [ "textarea" ] }, "required": { "type": "boolean", "examples": [ false ] }, "label": { "type": "string", "examples": [ "custom textarea attribute" ] } } }, "examples": [ [ { "name": "user:custom_textarea_attribute", "type": "textarea", "required": false, "label": "custom textarea attribute" }, { "name": "user:custom_text_attribute", "type": "text", "required": false, "label": "custom text attribute" }, { "name": "user:custom_select_attribute", "type": "select", "required": false, "label": "custom select attribute", "options": { "show_blank": true, "values": [ { "value": 63, "text": "AAAAAAAA", "source_value": "aaaaaaaaaa" }, { "value": 64, "text": "Rigger", "source_value": "user_select_item_1" }, { "value": 65, "text": "Physical Therapist Assistant", "source_value": "user_select_item_2" }, { "value": 66, "text": "Gas Plant Operator", "source_value": "user_select_item_3" }, { "value": 67, "text": "Forming Machine Operator", "source_value": "user_select_item_4" }, { "value": 68, "text": "Credit Authorizer", "source_value": "user_select_item_5" }, { "value": 69, "text": "Garment", "source_value": "user_select_item_6" }, { "value": 70, "text": "Ship Engineer", "source_value": "user_select_item_7" }, { "value": 71, "text": "Kindergarten Teacher", "source_value": "user_select_item_8" }, { "value": 72, "text": "Photographic Process Worker", "source_value": "user_select_item_9" }, { "value": 73, "text": "Decorator", "source_value": "user_select_item_10" } ] } }, { "name": "user:custom_number_attribute", "type": "number", "required": false, "label": "custom number attribute", "options": { "min": -999999.99, "max": 999999.99, "step": "0.01" } }, { "name": "user:custom_email_attribute", "type": "email", "required": false, "label": "custom email attribute" }, { "name": "user:custom_boolean_attribute", "type": "boolean", "required": false, "label": "custom boolean attribute" } ] ] }, "rrns": { "type": "object", "properties": { "user": { "type": "string", "examples": [ "rrn:local:20101:user:" ] } } }, "public": { "type": "integer", "examples": [ 1 ] }, "title": { "type": [ "string", "null" ], "examples": [ null ] }, "success_content": { "type": "string", "examples": [ "" ] }, "close_content": { "type": "string", "examples": [ "" ] }, "values": { "type": "array", "examples": [ [] ] }, "recaptcha": { "type": "boolean", "examples": [ true ] } }, "examples": [ { "fields": [ { "name": "user:custom_textarea_attribute", "type": "textarea", "required": false, "label": "custom textarea attribute" }, { "name": "user:custom_text_attribute", "type": "text", "required": false, "label": "custom text attribute" }, { "name": "user:custom_select_attribute", "type": "select", "required": false, "label": "custom select attribute", "options": { "show_blank": true, "values": [ { "value": 63, "text": "AAAAAAAA", "source_value": "aaaaaaaaaa" }, { "value": 64, "text": "Rigger", "source_value": "user_select_item_1" }, { "value": 65, "text": "Physical Therapist Assistant", "source_value": "user_select_item_2" }, { "value": 66, "text": "Gas Plant Operator", "source_value": "user_select_item_3" }, { "value": 67, "text": "Forming Machine Operator", "source_value": "user_select_item_4" }, { "value": 68, "text": "Credit Authorizer", "source_value": "user_select_item_5" }, { "value": 69, "text": "Garment", "source_value": "user_select_item_6" }, { "value": 70, "text": "Ship Engineer", "source_value": "user_select_item_7" }, { "value": 71, "text": "Kindergarten Teacher", "source_value": "user_select_item_8" }, { "value": 72, "text": "Photographic Process Worker", "source_value": "user_select_item_9" }, { "value": 73, "text": "Decorator", "source_value": "user_select_item_10" } ] } }, { "name": "user:custom_number_attribute", "type": "number", "required": false, "label": "custom number attribute", "options": { "min": -999999.99, "max": 999999.99, "step": "0.01" } }, { "name": "user:custom_email_attribute", "type": "email", "required": false, "label": "custom email attribute" }, { "name": "user:custom_boolean_attribute", "type": "boolean", "required": false, "label": "custom boolean attribute" } ], "rrns": { "user": "rrn:local:20101:user:" }, "public": 1, "title": null, "success_content": "", "close_content": "", "values": [], "recaptcha": true } ] } } } } }, "tags": [ "Form Module" ], "security": [] }, "parameters": [ { "in": "path", "name": "form_id", "description": "The id of the form, or its token.", "required": true, "schema": { "type": "string", "examples": [ "36" ] } } ] }, "/api/v2/form/{form_id}/process": { "post": { "summary": "Submit a form", "operationId": "submitAForm", "description": "Submits the form returned by `GET /form/{id}/view`, filled in by whoever is\ncalling. What it creates depends on the form's type: a user, an update to the\ncaller, or a submission stored on its own.\n\n**This endpoint does not require a token.** Anonymous forms the account has marked\npublic can be submitted by anyone holding the form's id or token, and those\nsubmissions must carry a `recaptcha` response. Every other form requires a\nsigned-in caller who may use it. Forms that create anything other than a user or a\nstandalone submission cannot be submitted here at all.\n\nThe body is the form's own fields, sent by the `name` each one carries in the\nrender response - `user:custom_email_attribute`, and so on. Validation errors come\nback keyed by field. Nothing is stored unless the whole submission validates.\n\nThe success response is the form rendered again, so the answers just stored can be\nshown back, with the caller's own previous submissions under `submissions`. Where\nthe form does not allow resubmission the response is the success content and a\nshort message instead, because there is no longer a form to render.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "oneOf": [ { "description": "no resubmission", "type": "object", "properties": { "success_content": { "type": "string", "examples": [ "Thanks!" ] }, "message": { "type": "string", "examples": [ "Form successfully submitted" ] } }, "examples": [ { "success_content": "Thanks!", "message": "Form successfully submitted" } ] }, { "description": "", "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "examples": [ "user:custom_textarea_attribute" ] }, "type": { "type": "string", "examples": [ "textarea" ] }, "required": { "type": "boolean", "examples": [ false ] }, "label": { "type": "string", "examples": [ "custom textarea attribute" ] } } }, "examples": [ [ { "name": "user:custom_textarea_attribute", "type": "textarea", "required": false, "label": "custom textarea attribute" }, { "name": "user:custom_text_attribute", "type": "text", "required": false, "label": "custom text attribute" }, { "name": "user:custom_select_attribute", "type": "select", "required": false, "label": "custom select attribute", "options": { "show_blank": true, "values": [ { "value": 63, "text": "AAAAAAAA", "source_value": "aaaaaaaaaa" }, { "value": 64, "text": "Rigger", "source_value": "user_select_item_1" }, { "value": 65, "text": "Physical Therapist Assistant", "source_value": "user_select_item_2" }, { "value": 66, "text": "Gas Plant Operator", "source_value": "user_select_item_3" }, { "value": 67, "text": "Forming Machine Operator", "source_value": "user_select_item_4" }, { "value": 68, "text": "Credit Authorizer", "source_value": "user_select_item_5" }, { "value": 69, "text": "Garment", "source_value": "user_select_item_6" }, { "value": 70, "text": "Ship Engineer", "source_value": "user_select_item_7" }, { "value": 71, "text": "Kindergarten Teacher", "source_value": "user_select_item_8" }, { "value": 72, "text": "Photographic Process Worker", "source_value": "user_select_item_9" }, { "value": 73, "text": "Decorator", "source_value": "user_select_item_10" } ] } }, { "name": "user:custom_number_attribute", "type": "number", "required": false, "label": "custom number attribute", "options": { "min": -999999.99, "max": 999999.99, "step": "0.01" } }, { "name": "user:custom_email_attribute", "type": "email", "required": false, "label": "custom email attribute" }, { "name": "user:custom_boolean_attribute", "type": "boolean", "required": false, "label": "custom boolean attribute" } ] ] }, "rrns": { "type": "object", "properties": { "user_form_submission": { "type": "string", "examples": [ "rrn:local:20101:user_form_submission:2" ] }, "user": { "type": "string", "examples": [ "rrn:local:20101:user:xxxxxxxxxxxxxxxxxxxxxxxx" ] } } }, "public": { "type": "integer", "examples": [ 0 ] }, "title": { "type": [ "string", "null" ], "examples": [ null ] }, "success_content": { "type": "string", "examples": [ "" ] }, "close_content": { "type": "string", "examples": [ "" ] }, "values": { "type": "array", "examples": [ [] ] }, "options": { "type": "object", "properties": { "resubmit": { "type": "boolean", "examples": [ true ] }, "read_only": { "type": "boolean", "examples": [ false ] } } }, "submissions": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 2 ] }, "form_id": { "type": "integer", "examples": [ 37 ] }, "user_id": { "type": "integer", "examples": [ 23453473 ] }, "entity": { "type": "string", "examples": [ "user_form_submission" ] }, "entity_id": { "type": "integer", "examples": [ 2 ] }, "data": { "type": "array", "examples": [ [] ] }, "requires_resubmission": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-08-17T04:57:55.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-08-17T04:57:55.000000Z" ] }, "custom_address_attribute": { "type": [ "string", "null" ], "examples": [ null ] }, "custom_boolean_attribute": { "type": [ "string", "null" ], "examples": [ null ] }, "custom_country_attribute": { "type": [ "string", "null" ], "examples": [ null ] }, "custom_date_attribute": { "type": [ "string", "null" ], "examples": [ null ] }, "custom_datetime_attribute": { "type": [ "string", "null" ], "examples": [ null ] }, "custom_document_attribute": { "type": [ "string", "null" ], "examples": [ null ] }, "custom_email_attribute": { "type": [ "string", "null" ], "examples": [ null ] }, "custom_file_attribute": { "type": [ "string", "null" ], "examples": [ null ] }, "custom_html_attribute": { "type": [ "string", "null" ], "examples": [ null ] }, "custom_image_attribute": { "type": [ "string", "null" ], "examples": [ null ] }, "custom_multiselect_attribute": { "type": [ "string", "null" ], "examples": [ null ] }, "custom_number_attribute": { "type": [ "string", "null" ], "examples": [ null ] }, "custom_rating_attribute": { "type": [ "string", "null" ], "examples": [ null ] }, "custom_select_attribute": { "type": [ "string", "null" ], "examples": [ null ] }, "custom_telephone_attribute": { "type": [ "string", "null" ], "examples": [ null ] }, "custom_text_attribute": { "type": [ "string", "null" ], "examples": [ null ] }, "custom_textarea_attribute": { "type": [ "string", "null" ], "examples": [ null ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:user_form_submission:2" ] } } }, "relations": { "type": "object", "properties": {} }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ false ] } } }, "attributes": { "type": "object", "properties": {} } } }, "examples": [ [ { "object": { "id": 2, "form_id": 37, "user_id": 23453473, "entity": "user_form_submission", "entity_id": 2, "data": [], "requires_resubmission": 0, "deleted_at": null, "is_erased": 0, "created_at": "2026-08-17T04:57:55.000000Z", "updated_at": "2026-08-17T04:57:55.000000Z", "custom_address_attribute": null, "custom_boolean_attribute": null, "custom_country_attribute": null, "custom_date_attribute": null, "custom_datetime_attribute": null, "custom_document_attribute": null, "custom_email_attribute": null, "custom_file_attribute": null, "custom_html_attribute": null, "custom_image_attribute": null, "custom_multiselect_attribute": null, "custom_number_attribute": null, "custom_rating_attribute": null, "custom_select_attribute": null, "custom_telephone_attribute": null, "custom_text_attribute": null, "custom_textarea_attribute": null }, "nice": { "rrn": "rrn:local:20101:user_form_submission:2" }, "relations": [], "permissions": { "read": true, "update": true, "delete": false }, "attributes": [] } ] ] } }, "examples": [ { "fields": [ { "name": "user:custom_textarea_attribute", "type": "textarea", "required": false, "label": "custom textarea attribute" }, { "name": "user:custom_text_attribute", "type": "text", "required": false, "label": "custom text attribute" }, { "name": "user:custom_select_attribute", "type": "select", "required": false, "label": "custom select attribute", "options": { "show_blank": true, "values": [ { "value": 63, "text": "AAAAAAAA", "source_value": "aaaaaaaaaa" }, { "value": 64, "text": "Rigger", "source_value": "user_select_item_1" }, { "value": 65, "text": "Physical Therapist Assistant", "source_value": "user_select_item_2" }, { "value": 66, "text": "Gas Plant Operator", "source_value": "user_select_item_3" }, { "value": 67, "text": "Forming Machine Operator", "source_value": "user_select_item_4" }, { "value": 68, "text": "Credit Authorizer", "source_value": "user_select_item_5" }, { "value": 69, "text": "Garment", "source_value": "user_select_item_6" }, { "value": 70, "text": "Ship Engineer", "source_value": "user_select_item_7" }, { "value": 71, "text": "Kindergarten Teacher", "source_value": "user_select_item_8" }, { "value": 72, "text": "Photographic Process Worker", "source_value": "user_select_item_9" }, { "value": 73, "text": "Decorator", "source_value": "user_select_item_10" } ] } }, { "name": "user:custom_number_attribute", "type": "number", "required": false, "label": "custom number attribute", "options": { "min": -999999.99, "max": 999999.99, "step": "0.01" } }, { "name": "user:custom_email_attribute", "type": "email", "required": false, "label": "custom email attribute" }, { "name": "user:custom_boolean_attribute", "type": "boolean", "required": false, "label": "custom boolean attribute" } ], "rrns": { "user_form_submission": "rrn:local:20101:user_form_submission:2", "user": "rrn:local:20101:user:xxxxxxxxxxxxxxxxxxxxxxxx" }, "public": 0, "title": null, "success_content": "", "close_content": "", "values": [], "options": { "resubmit": true, "read_only": false }, "submissions": [ { "object": { "id": 2, "form_id": 37, "user_id": 23453473, "entity": "user_form_submission", "entity_id": 2, "data": [], "requires_resubmission": 0, "deleted_at": null, "is_erased": 0, "created_at": "2026-08-17T04:57:55.000000Z", "updated_at": "2026-08-17T04:57:55.000000Z", "custom_address_attribute": null, "custom_boolean_attribute": null, "custom_country_attribute": null, "custom_date_attribute": null, "custom_datetime_attribute": null, "custom_document_attribute": null, "custom_email_attribute": null, "custom_file_attribute": null, "custom_html_attribute": null, "custom_image_attribute": null, "custom_multiselect_attribute": null, "custom_number_attribute": null, "custom_rating_attribute": null, "custom_select_attribute": null, "custom_telephone_attribute": null, "custom_text_attribute": null, "custom_textarea_attribute": null }, "nice": { "rrn": "rrn:local:20101:user_form_submission:2" }, "relations": {}, "permissions": { "read": true, "update": true, "delete": false }, "attributes": {} } ] } ] } ] } } } } }, "tags": [ "Form Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "user:{field}": { "type": "string", "description": "A field value, keyed by the `name` the render\n response gives it. The set of fields differs per form.", "examples": [ "Example answer" ] }, "recaptcha": { "type": "string", "description": "A reCAPTCHA response. Required when submitting a public\n form without signing in, and ignored otherwise.", "examples": [ "03AGdBq26..." ] } } } } } }, "security": [] }, "parameters": [ { "in": "path", "name": "form_id", "description": "The id of the form, or its token.", "required": true, "schema": { "type": "string", "examples": [ "37" ] } } ] }, "/api/v2/form/{form_id}/interact/{user_id}": { "get": { "summary": "Render a form about a user", "operationId": "renderAFormAboutAUser", "description": "Returns a form drawn for an administrator to complete about somebody else, with\nthe fields already carrying that user's current values. Submit the result to\n`PUT /form/{id}/interact/{user_id}`.\n\nThe caller must be able to read both the form and the user; if either is out of\nreach the endpoint answers as though it does not exist. A caller who may read the\nuser but not change them gets the form back with every field disabled, so it can\nbe shown but not submitted.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "examples": [ "user:custom_textarea_attribute" ] }, "type": { "type": "string", "examples": [ "textarea" ] }, "required": { "type": "boolean", "examples": [ false ] }, "label": { "type": "string", "examples": [ "custom textarea attribute" ] } } }, "examples": [ [ { "name": "user:custom_textarea_attribute", "type": "textarea", "required": false, "label": "custom textarea attribute" }, { "name": "user:custom_text_attribute", "type": "text", "required": false, "label": "custom text attribute" }, { "name": "user:custom_select_attribute", "type": "select", "required": false, "label": "custom select attribute", "options": { "show_blank": true, "values": [ { "value": 63, "text": "AAAAAAAA", "source_value": "aaaaaaaaaa" }, { "value": 64, "text": "Rigger", "source_value": "user_select_item_1" }, { "value": 65, "text": "Physical Therapist Assistant", "source_value": "user_select_item_2" }, { "value": 66, "text": "Gas Plant Operator", "source_value": "user_select_item_3" }, { "value": 67, "text": "Forming Machine Operator", "source_value": "user_select_item_4" }, { "value": 68, "text": "Credit Authorizer", "source_value": "user_select_item_5" }, { "value": 69, "text": "Garment", "source_value": "user_select_item_6" }, { "value": 70, "text": "Ship Engineer", "source_value": "user_select_item_7" }, { "value": 71, "text": "Kindergarten Teacher", "source_value": "user_select_item_8" }, { "value": 72, "text": "Photographic Process Worker", "source_value": "user_select_item_9" }, { "value": 73, "text": "Decorator", "source_value": "user_select_item_10" } ] } }, { "name": "user:custom_number_attribute", "type": "number", "required": false, "label": "custom number attribute", "options": { "min": -999999.99, "max": 999999.99, "step": "0.01" } }, { "name": "user:custom_email_attribute", "type": "email", "required": false, "label": "custom email attribute" }, { "name": "user:custom_boolean_attribute", "type": "boolean", "required": false, "label": "custom boolean attribute" } ] ] }, "rrns": { "type": "object", "properties": { "user": { "type": "string", "examples": [ "rrn:local:20101:user:xxxxxxxxxxxxxxxxxxxxxxxx" ] } } } }, "examples": [ { "fields": [ { "name": "user:custom_textarea_attribute", "type": "textarea", "required": false, "label": "custom textarea attribute" }, { "name": "user:custom_text_attribute", "type": "text", "required": false, "label": "custom text attribute" }, { "name": "user:custom_select_attribute", "type": "select", "required": false, "label": "custom select attribute", "options": { "show_blank": true, "values": [ { "value": 63, "text": "AAAAAAAA", "source_value": "aaaaaaaaaa" }, { "value": 64, "text": "Rigger", "source_value": "user_select_item_1" }, { "value": 65, "text": "Physical Therapist Assistant", "source_value": "user_select_item_2" }, { "value": 66, "text": "Gas Plant Operator", "source_value": "user_select_item_3" }, { "value": 67, "text": "Forming Machine Operator", "source_value": "user_select_item_4" }, { "value": 68, "text": "Credit Authorizer", "source_value": "user_select_item_5" }, { "value": 69, "text": "Garment", "source_value": "user_select_item_6" }, { "value": 70, "text": "Ship Engineer", "source_value": "user_select_item_7" }, { "value": 71, "text": "Kindergarten Teacher", "source_value": "user_select_item_8" }, { "value": 72, "text": "Photographic Process Worker", "source_value": "user_select_item_9" }, { "value": 73, "text": "Decorator", "source_value": "user_select_item_10" } ] } }, { "name": "user:custom_number_attribute", "type": "number", "required": false, "label": "custom number attribute", "options": { "min": -999999.99, "max": 999999.99, "step": "0.01" } }, { "name": "user:custom_email_attribute", "type": "email", "required": false, "label": "custom email attribute" }, { "name": "user:custom_boolean_attribute", "type": "boolean", "required": false, "label": "custom boolean attribute" } ], "rrns": { "user": "rrn:local:20101:user:xxxxxxxxxxxxxxxxxxxxxxxx" } } ] } } } } }, "tags": [ "Form Module" ] }, "put": { "summary": "Submit a form about a user", "operationId": "submitAFormAboutAUser", "description": "Submits the form returned by `GET /form/{id}/interact/{user_id}`, completed by an\nadministrator about the user in the path. The caller must be able to change that\nuser; otherwise the endpoint answers as though it does not exist.\n\nWhat the submission does depends on the form's type. An admin interaction form\nwrites the answers straight onto the user and records the change against them. An\nadmin submission form stores the answers as a submission of their own, leaving the\nuser untouched, and is restricted to callers who hold a role in the account.\n\nThe body is the form's own fields, sent by the `name` each one carries in the\nrender response - `user:custom_notes`, and so on. Only fields the visibility rules\ncurrently show are read; anything else in the body is ignored rather than\nrejected. Validation errors come back keyed by field, prefixed with the entity the\nfield belongs to.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Form successfully submitted" ] } }, "examples": [ { "message": "Form successfully submitted" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Admin access required for this form" ] } }, "examples": [ { "message": "Admin access required for this form" } ] } } } } }, "tags": [ "Form Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "user:{field}": { "type": "string", "description": "A field value, keyed by the `name` the render\n response gives it. The set of fields differs per form.", "examples": [ "Called and left a message" ] } } } } } } }, "parameters": [ { "in": "path", "name": "form_id", "description": "The ID of the form.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } }, { "in": "path", "name": "user_id", "description": "The ID of the user.", "required": true, "schema": { "type": "integer", "examples": [ 23453468 ] } } ] }, "/api/v2/form/{form_id}/copy": { "post": { "summary": "Copy a form", "operationId": "copyAForm", "description": "Duplicates a form, along with its fields and its visibility rules, and returns the\ncopy. Submissions are not copied.\n\nCopying within the same account returns the new form and appends `(Copy)` to its\nname. Copying into another account - send that account's id as `account_id` -\nreturns a short confirmation instead of the form, because the caller cannot\nnecessarily read what was just created there. Any custom attributes the fields\ndepend on are recreated in the target account if it does not already have them,\nand a field whose attribute exists there with a different type is skipped rather\nthan copied wrongly.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "oneOf": [ { "description": "copied into another account", "type": "object", "properties": { "message": { "type": "string", "examples": [ "Successfully copied form" ] } }, "examples": [ { "message": "Successfully copied form" } ] }, { "description": "", "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 37 ] }, "form_type_id": { "type": "integer", "examples": [ 15 ] }, "name": { "type": "string", "examples": [ "Volunteer Application" ] }, "form_title": { "type": "string", "examples": [ "Volunteer Application" ] }, "form_category_id": { "type": [ "string", "null" ], "examples": [ null ] }, "success_content": { "type": "string", "examples": [ "" ] }, "close_content": { "type": "string", "examples": [ "" ] }, "options": { "type": "array", "examples": [ [] ] }, "rules": { "type": "array", "examples": [ [] ] }, "cost": { "type": "string", "examples": [ "0.00" ] }, "tax_percentage": { "type": "string", "examples": [ "0.00" ] }, "close_at": { "type": [ "string", "null" ], "examples": [ null ] }, "public": { "type": "integer", "examples": [ 0 ] }, "is_archived": { "type": "integer", "examples": [ 0 ] }, "token": { "type": "string", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "created_at": { "type": "string", "examples": [ "2026-06-09T05:36:25.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-06-09T05:36:25.000000Z" ] }, "deleted_by": { "type": [ "string", "null" ], "examples": [ null ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:form:37" ] }, "is_open": { "type": "string", "examples": [ "Yes" ] }, "close_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_foreign_account": { "type": "boolean", "examples": [ false ] } } }, "relations": { "type": "object", "properties": { "form_type": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 15 ] }, "name": { "type": "string", "examples": [ "User Interaction - New answers for new submissions" ] }, "code": { "type": "string", "examples": [ "user_submission" ] }, "main_entity": { "type": "string", "examples": [ "user_form_submission" ] }, "entities": { "type": "object", "properties": { "user_form_submission": { "type": "object", "properties": { "create": { "type": "boolean", "examples": [ true ] } } } } }, "public_field": { "type": "object", "properties": { "form_title": { "type": "object", "properties": { "rules": { "type": "string", "examples": [ "required|json" ] }, "validation": { "type": "string", "examples": [ "required" ] } } }, "close_content": { "type": "object", "properties": { "rules": { "type": "string", "examples": [ "nullable|json" ] }, "validation": { "type": "string", "examples": [ "string" ] } } }, "success_content": { "type": "object", "properties": { "rules": { "type": "string", "examples": [ "required|json" ] }, "validation": { "type": "string", "examples": [ "required" ] } } } } }, "access": { "type": "string", "examples": [ "form" ] } } } } }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ false ] }, "copy": { "type": "boolean", "examples": [ false ] } } } }, "examples": [ { "object": { "id": 37, "form_type_id": 15, "name": "Volunteer Application", "form_title": "Volunteer Application", "form_category_id": null, "success_content": "", "close_content": "", "options": [], "rules": [], "cost": "0.00", "tax_percentage": "0.00", "close_at": null, "public": 0, "is_archived": 0, "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "deleted_at": null, "created_at": "2026-06-09T05:36:25.000000Z", "updated_at": "2026-06-09T05:36:25.000000Z", "deleted_by": null }, "nice": { "rrn": "rrn:local:20101:form:37", "is_open": "Yes", "close_at": null, "is_foreign_account": false }, "relations": { "form_type": { "id": 15, "name": "User Interaction - New answers for new submissions", "code": "user_submission", "main_entity": "user_form_submission", "entities": { "user_form_submission": { "create": true } }, "public_field": { "form_title": { "rules": "required|json", "validation": "required" }, "close_content": { "rules": "nullable|json", "validation": "string" }, "success_content": { "rules": "required|json", "validation": "required" } }, "access": "form" } }, "permissions": { "read": true, "update": true, "delete": false, "copy": false } } ] } ] } } } } }, "tags": [ "Form Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "integer", "description": "The account to copy the form into. Defaults to the\n account the form is already in.", "examples": [ 20101 ] } } } } } } }, "parameters": [ { "in": "path", "name": "form_id", "description": "The ID of the form.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/form/{form_id}/export-responses": { "get": { "summary": "Export a form's responses", "operationId": "exportAFormsResponses", "description": "Queues an export of every response to a form and returns a token identifying the\nqueued job. **The file is not in the response** - the export is built in the\nbackground and delivered through the account's usual export delivery, so nothing\nhere needs polling.\n\nOnly the four form types that collect responses can be exported: anonymous forms,\nuser interaction forms, submission forms and admin submission forms. Asking for\nany other type is rejected.", "parameters": [ { "in": "query", "name": "format", "description": "The file format. One of `xlsx` or `csv`. Defaults to\n `xlsx`.", "required": false, "schema": { "type": "string", "description": "The file format. One of `xlsx` or `csv`. Defaults to\n `xlsx`.", "examples": [ "csv" ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "queue": { "type": "string", "examples": [ "yRw7YnOU4MqaSwsVVJlNV4PI" ] } }, "examples": [ { "queue": "yRw7YnOU4MqaSwsVVJlNV4PI" } ] } } } } }, "tags": [ "Form Module" ] }, "parameters": [ { "in": "path", "name": "form_id", "description": "The ID of the form.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/form/{form_id}/submission": { "get": { "summary": "List a form's anonymous submissions", "operationId": "listAFormsAnonymousSubmissions", "description": "Returns the answers left on an anonymous form - the type that can be filled in\nwithout signing in. Each row carries the answers as a `data` object keyed by the\nfield names the form renders, and nothing identifying who left them, because\nnobody signed in to leave them.\n\n**Only anonymous forms have these.** Every other form type stores its answers\nagainst a user; read those through `GET /user/{id}/form/user-submission` instead.\nAsking a form of any other type for its submissions returns an empty list rather\nthan an error.", "parameters": [ { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 1 ] }, "form_id": { "type": "integer", "examples": [ 36 ] }, "data": { "type": "object", "properties": { "user:custom_text_attribute": { "type": "string", "examples": [ "Example answer" ] }, "user:custom_email_attribute": { "type": "string", "examples": [ "respondent@example.com" ] }, "user:custom_number_attribute": { "type": "integer", "examples": [ 42 ] }, "user:custom_eav_multiselect_1": { "type": [ "string", "null" ], "examples": [ null ] }, "user:custom_textarea_attribute": { "type": "string", "examples": [ "A longer example answer." ] }, "user:custom_multiselect_attribute": { "type": [ "string", "null" ], "examples": [ null ] } } }, "created_at": { "type": "string", "examples": [ "2026-08-17T04:57:54.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-08-17T04:57:54.000000Z" ] } } }, "nice": { "type": "array", "examples": [ [] ] }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ false ] }, "delete": { "type": "boolean", "examples": [ false ] } } } } }, "examples": [ [ { "object": { "id": 1, "form_id": 36, "data": { "user:custom_text_attribute": "Example answer", "user:custom_email_attribute": "respondent@example.com", "user:custom_number_attribute": 42, "user:custom_eav_multiselect_1": null, "user:custom_textarea_attribute": "A longer example answer.", "user:custom_multiselect_attribute": null }, "created_at": "2026-08-17T04:57:54.000000Z", "updated_at": "2026-08-17T04:57:54.000000Z" }, "nice": [], "relations": [], "permissions": { "read": true, "update": false, "delete": false } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/form/{form}/submission?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/form/{form}/submission?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/form/{form}/submission" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 1, "form_id": 36, "data": { "user:custom_text_attribute": "Example answer", "user:custom_email_attribute": "respondent@example.com", "user:custom_number_attribute": 42, "user:custom_eav_multiselect_1": null, "user:custom_textarea_attribute": "A longer example answer.", "user:custom_multiselect_attribute": null }, "created_at": "2026-08-17T04:57:54.000000Z", "updated_at": "2026-08-17T04:57:54.000000Z" }, "nice": [], "relations": [], "permissions": { "read": true, "update": false, "delete": false } }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/form/{form}/submission?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/form/{form}/submission?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/form/{form}/submission", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Form Module" ] }, "parameters": [ { "in": "path", "name": "form_id", "description": "The ID of the form.", "required": true, "schema": { "type": "integer", "examples": [ 1 ] } } ] }, "/api/v2/user/{user_id}/form/user-submission": { "get": { "summary": "List a user's form submissions", "operationId": "listAUsersFormSubmissions", "description": "Returns every form submission held against one person, across all of the account's\nforms. Each row carries the raw answers in `object`, the same answers rendered for\ndisplay in `nice`, and the definition of each field in `attributes`, so a listing\ncan be shown without reading the form the answers came from.\n\nThe caller must be able to read the user in the path; otherwise the endpoint\nanswers as though they do not exist. Filter by `form_id` to narrow the result to\none form.\n\nAnonymous form submissions are not included - nobody signed in to leave them, so\nthey belong to no user. Read those through `GET /form/{id}/submission`.", "parameters": [ { "in": "query", "name": "per_page", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "required": false, "schema": { "type": "integer", "description": "The number of results to return per page. The higher the number the longer the request may take.\nIt is highly recommended to use this to avoid timeouts as your data grows.\nUsed in conjunction with the `page` parameter to paginate results.", "examples": [ 5 ] } }, { "in": "query", "name": "page", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "required": false, "schema": { "type": "integer", "description": "The page of results to return. Used in conjunction with the `per_page` parameter to paginate\nresults. If not specified, defaults to 1.\nThe response's next_page_url will be null if there are no\nmore pages.", "examples": [ 1 ] } }, { "in": "query", "name": "filter", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "example": null, "required": false, "schema": { "type": "array", "description": "A filter to apply to the results. Declared as an array of objects, where each object\ncontains an attr (attribute code), operator and value key. Examples:\n\n?filter[0]['attr']=name&filter[0][operator]=like&filter[0][value]=luke \n\n?filter[0]['attr']=id&filter[0][operator]=>&filter[0][value]=265 \n\nSee the filters documentation for more details on how to use this.", "items": { "type": "object" }, "examples": [ null ] } }, { "in": "query", "name": "sort_by", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "example": null, "required": false, "schema": { "type": "string", "description": "The field to sort the results by. No ordering is applied unless you specify one, so\nrow order is not guaranteed. Always send it when paging through a list, otherwise\nrecords can repeat or be missed between pages.\nExample: id", "examples": [ null ] } }, { "in": "query", "name": "sort_order", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "example": null, "required": false, "schema": { "type": "string", "description": "The direction to sort the results by. Can be 'asc' or 'desc', default is 'asc'.", "enum": [ "asc", "desc" ], "examples": [ null ] } }, { "in": "query", "name": "_locale", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "required": false, "schema": { "type": "string", "description": "The locale to use for the response. This primarily affects the results of the `nice` field, which\ncontain human-readable labels and terms, as well as locale-specific date formats.,", "examples": [ "en-US" ] } }, { "in": "query", "name": "extras", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "required": false, "schema": { "type": "array", "description": "A list of extras to include in the response. These are objects or arrays that are not part of\nthe model's primary attributes, such as stats and counts.\nFor fast responses, avoid requesting them if you don't need them. ", "items": { "type": "string", "enum": [ "entity" ] }, "examples": [ [ "entity" ] ] } }, { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "object", "properties": { "id": { "type": "integer", "examples": [ 2 ] }, "form_id": { "type": "integer", "examples": [ 37 ] }, "user_id": { "type": "integer", "examples": [ 23453473 ] }, "entity": { "type": "string", "examples": [ "user_form_submission" ] }, "entity_id": { "type": "integer", "examples": [ 2 ] }, "data": { "type": "array", "examples": [ [] ] }, "requires_resubmission": { "type": "integer", "examples": [ 0 ] }, "deleted_at": { "type": [ "string", "null" ], "examples": [ null ] }, "is_erased": { "type": "integer", "examples": [ 0 ] }, "created_at": { "type": "string", "examples": [ "2026-08-17T04:57:55.000000Z" ] }, "updated_at": { "type": "string", "examples": [ "2026-08-17T04:57:55.000000Z" ] } } }, "nice": { "type": "object", "properties": { "rrn": { "type": "string", "examples": [ "rrn:local:20101:user_form_submission:2" ] } } }, "relations": { "type": "array", "examples": [ [] ] }, "permissions": { "type": "object", "properties": { "read": { "type": "boolean", "examples": [ true ] }, "update": { "type": "boolean", "examples": [ true ] }, "delete": { "type": "boolean", "examples": [ false ] } } }, "attributes": { "type": "array", "examples": [ [] ] } } }, "examples": [ [ { "object": { "id": 2, "form_id": 37, "user_id": 23453473, "entity": "user_form_submission", "entity_id": 2, "data": [], "requires_resubmission": 0, "deleted_at": null, "is_erased": 0, "created_at": "2026-08-17T04:57:55.000000Z", "updated_at": "2026-08-17T04:57:55.000000Z" }, "nice": { "rrn": "rrn:local:20101:user_form_submission:2" }, "relations": [], "permissions": { "read": true, "update": true, "delete": false }, "attributes": [] }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ] ] }, "first_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/user/{user}/form/user-submission?per_page=5&_locale=en-US&page=1" ] }, "from": { "type": "integer", "examples": [ 1 ] }, "next_page_url": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/user/{user}/form/user-submission?per_page=5&_locale=en-US&page=2" ] }, "path": { "type": "string", "examples": [ "https://example.rosterfy.com/api/v2/user/{user}/form/user-submission" ] }, "per_page": { "type": "integer", "examples": [ 5 ] }, "prev_page_url": { "type": [ "string", "null" ], "examples": [ null ] }, "to": { "type": "integer", "examples": [ 5 ] } } }, "examples": [ [ { "current_page": 1, "data": [ { "object": { "id": 2, "form_id": 37, "user_id": 23453473, "entity": "user_form_submission", "entity_id": 2, "data": [], "requires_resubmission": 0, "deleted_at": null, "is_erased": 0, "created_at": "2026-08-17T04:57:55.000000Z", "updated_at": "2026-08-17T04:57:55.000000Z" }, "nice": { "rrn": "rrn:local:20101:user_form_submission:2" }, "relations": [], "permissions": { "read": true, "update": true, "delete": false }, "attributes": [] }, { "object": { "id": 2 } }, { "object": { "id": 3 } }, { "object": { "id": 4 } }, { "object": { "id": 5 } } ], "first_page_url": "https://example.rosterfy.com/api/v2/user/{user}/form/user-submission?per_page=5&_locale=en-US&page=1", "from": 1, "next_page_url": "https://example.rosterfy.com/api/v2/user/{user}/form/user-submission?per_page=5&_locale=en-US&page=2", "path": "https://example.rosterfy.com/api/v2/user/{user}/form/user-submission", "per_page": 5, "prev_page_url": null, "to": 5 } ] ] } } } } }, "tags": [ "Form Module" ] }, "put": { "summary": "Update a user's form submissions in bulk", "operationId": "updateAUsersFormSubmissionsInBulk", "description": "Applies one change to many of a person's form submissions at once, and answers\nwith a plain-text confirmation rather than the rows it changed.\n\n**Send a `filter` unless you mean every submission that person has.** There is no\nlist of ids to update; the change is applied to whatever the filter selects, and\nan unfiltered request selects all of them. Filter by `form_id` to confine it to\none form. The filter takes the same shape as the one on the listing above, so a\nsafe way to work is to run the listing with a filter first, check what comes back,\nthen send the same filter here.\n\nThe change itself is applied directly and does not go back through the form, so\nneither the form's validation rules nor its visibility rules apply. Requires the\nability to update forms.", "parameters": [ { "in": "header", "name": "Rosterfy-Platform", "description": "", "schema": { "type": "string", "examples": [ "admin" ] } } ], "responses": { "200": { "description": "", "content": { "text/plain": { "schema": { "type": "string", "examples": [ "Mass operation succeeded" ] } } } } }, "tags": [ "Form Module" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "The submitted answers, as a JSON string. Replaces the stored\n answers outright on every selected submission rather than merging into them.", "examples": [ "{\"user:custom_text_attribute\":\"Example answer\"}" ] }, "requires_resubmission": { "type": [ "boolean", "null" ], "description": "Whether the selected submissions should be\n marked as needing to be filled in again.", "examples": [ true ] }, "filter": { "type": "array", "description": "Which of the person's submissions to change. Same shape\n as the listing's filter. Omit it and every submission they have is changed.", "items": { "type": "object" }, "examples": [ [ [] ] ] } } } } } } }, "parameters": [ { "in": "path", "name": "user_id", "description": "The ID of the user.", "required": true, "schema": { "type": "integer", "examples": [ 23453468 ] } } ] } } }