MENU navbar-image

Introduction

festiware API v2: project-scoped REST API for integrating festiware with your own systems: projects, people and groups (with forms, comments, attachments and workflow transitions), person and group types, ticket types, ticket codes, offers and shop categories, coupons, orders, invoices, contracts, areas and events, scheduler plans, teams, supplies, workflows and triggers. Authentication: OAuth 2.0 (Authorization Code) via Laravel Passport. Works with any HTTP client or automation tool.


Terminology: Group == Application

This API calls the resource a Group — the same entity the festiware backend shows as Gruppe. For backwards compatibility the wire format still uses the historic application spelling, and that spelling will not change.

Concept Wire identifier
Group GET /projects/{project}/applications, application_type_id
Group type GET /application-types, application_type
Sideload flags withApplications, withSubordinatedApplications
Permissions all_persons_and_applications_see / _manage / _administrate

Read every application* identifier below as "group".


Connecting your integration

Complete this once per integration. The API uses standard OAuth 2.0 Authorization Code with refresh tokens, so any HTTP client or library that supports this grant works. Ready-made recipes for n8n and Postman follow under Recipes.

Prerequisites


Step 1 — Create an API User

In the festiware backend: API Users → Create API User


Step 2 — Download the credentials

In the backend: open the API user → Actions → Download Credentials

The file contains client_id, client_secret, the API-user email + password and the granted API permissions. You can download it again at any time. Hand it only to whoever will complete Step 3.

Understanding the Redirect URI

This is the single most common point of confusion, so to be clear:


Step 3 — Get a token

The OAuth client from Step 2 is a standard OAuth 2.0 Authorization Code client:

Field Value
Grant Type Authorization Code
Authorization URL https://{instance}.festiwa.re/oauth/authorize
Token URL https://{instance}.festiwa.re/oauth/token
Client ID / Client Secret from Step 2
Scope (leave empty)
Client Authentication Send client credentials in body

The flow:

  1. Open the authorization URL in a browser with response_type=code, client_id, redirect_uri (exactly as registered in Step 1) and a random state: https://{instance}.festiwa.re/oauth/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&state={state}
  2. Log in with the API-user email + password from the credentials file (Step 2). The consent screen shows the client name → Authorize.
  3. The browser is sent to your redirect URI with ?code=…&state=…. Check that state matches, then exchange the code (it is valid for a few minutes and usable once):
curl -X POST https://{instance}.festiwa.re/oauth/token \
  -d grant_type=authorization_code \
  -d code={code} \
  -d redirect_uri={redirect_uri} \
  -d client_id={client_id} \
  -d client_secret={client_secret}

The response carries access_token, refresh_token and expires_in. Store the refresh token securely.


Step 4 — Token lifecycle

curl -X POST https://{instance}.festiwa.re/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token={refresh_token} \
  -d client_id={client_id} \
  -d client_secret={client_secret}

Step 5 — First API call

curl -H "Authorization: Bearer {access_token}" \
  https://{instance}.festiwa.re/api/v2/projects/{project_id}/people

Expected: HTTP 200 with a paginated People list.


Recipes

Tool-specific settings for the flow above. Steps 1 and 2 stay the same; the recipe replaces Steps 3 to 5.

n8n

  1. In n8n: Credentials → New → OAuth2 API. Register n8n's callback URL https://{n8n-instance}/rest/oauth2-credential/callback as the Redirect URI of the API user (Step 1).
Field Value
Grant Type Authorization Code
Authorization URL https://{instance}.festiwa.re/oauth/authorize
Access Token URL https://{instance}.festiwa.re/oauth/token
Client ID from Step 2
Client Secret from Step 2
Scope (leave empty)
  1. Click Connect. A browser window opens; log in as the API user from Step 1 and Authorize on the consent screen. The window closes and n8n shows Connected.
  2. n8n stores the refresh token and renews the access token automatically, no manual action.
  3. First call in an HTTP Request node:
Method: GET
URL:    https://{instance}.festiwa.re/api/v2/projects/{project_id}/people
Auth:   Predefined Credential Type → OAuth2 (the credential from above)

Postman

  1. Import or create a request/collection and open the Authorization tab → Type OAuth 2.0.
  2. Configure:
Field Value
Grant Type Authorization Code
Callback URL the Redirect URI registered on the API user (Step 1)
Auth URL https://{instance}.festiwa.re/oauth/authorize
Access Token URL https://{instance}.festiwa.re/oauth/token
Client ID / Client Secret from Step 2
Scope (leave empty)
Client Authentication Send client credentials in body
  1. Leave "Authorize using browser" switched OFF. When it is on, Postman replaces your callback URL with its own relay (https://oauth.pstmn.io/v1/callback), which won't match the registered redirect URI — the login then always fails. With the switch off, Postman opens its own login popup and intercepts the redirect regardless of where it points.
  2. Click Get New Access Token, log in with the API-user email + password from the credentials file (Step 2), and approve the consent screen. Postman stores the token and attaches it as a Bearer header.
  3. Postman does not refresh the token on its own: after 1 hour click Get New Access Token again.

Idempotent retries

Every POST endpoint accepts an optional Idempotency-Key header: a value of your choice, 1 to 255 characters of A-Z a-z 0-9 _ - . : (a UUID, a ULID or an n8n execution id). Send a new key for every new request and the same key when you retry that request, e.g. after a timeout.


Daily call allowance

A festiware package can limit the number of API v2 calls per day. All integrations of an instance share one allowance; it starts again at midnight (instance time, Europe/Berlin). Only authenticated /api/v2 calls count.

The endpoints the festiware check-in app uses at the gate count too, but are never refused, also past the limit: POST /projects/{project}/access-checks, GET /projects/{project}/access-holders, GET /projects/{project}/access-holders/version, the supply endpoints (/supplies, /supply-categories, /supplies/{supply}/items, /supply-items/{supplyItem}, POST /supply-tracking-events) and GET /projects/{project}/teams. Every other /api/v2 endpoint is refused once the allowance is used up.

While the limit applies, every response carries:

Header Meaning
X-RateLimit-Daily-Limit calls per day in the package
X-RateLimit-Daily-Remaining calls left today

Past the limit the API answers 429 with error.code = api_quota_exceeded, a Retry-After header (seconds until midnight) and X-RateLimit-Daily-Reset (Unix time of the next midnight). Refused calls do not count. Some endpoints also have a per-minute limit with the standard X-RateLimit-Limit / X-RateLimit-Remaining headers; it answers 429 too, but without the api_quota_exceeded code.


Troubleshooting

Symptom Cause Fix
Login form says "not an API user" The customer signed in with their own festiware account Use the API-user email + password from the credentials file (Step 2)
Your tool reports a redirect URI mismatch The Redirect URI on the client differs from the callback URL your tool sends Make them identical (backend: API user → Redirect URI)
Postman: login fails / redirect mismatch although the callback URL looks right "Authorize using browser" is ON — Postman silently forces its oauth.pstmn.io relay as callback Switch "Authorize using browser" off and get the token again
API calls return 403 The API user lacks the required API permission; the message names it Tick it in the backend → API User → Edit → API permissions
403 with error.code = cross_project_access_denied The API user is restricted to other projects (Project Access) Add the project to the API user's Project Access, or call a project it may use (GET /projects)
422 with error.code = idempotency_key_reused The Idempotency-Key was already used within 24 h for a request with a different payload Use a new key for every new request; reuse a key only to retry the identical request
409 with error.code = idempotency_in_progress A request with the same Idempotency-Key is still running (e.g. a retry sent before the first call timed out on the server) Wait a moment (Retry-After) and retry with the same key: you then get the stored response
409 with error.code = idempotency_permissions_changed The API user's permissions, Project Access or type restriction changed since the Idempotency-Key was first used, so the stored response is not replayed Send the request again with a new Idempotency-Key; it runs with the current permissions
422 with error.code = idempotency_key_invalid The Idempotency-Key header is empty, longer than 255 characters or contains other characters than A-Z a-z 0-9 _ - . : Send a UUID or another value in that format
429 with error.code = api_quota_exceeded The package's daily API call allowance is used up Wait until midnight (Retry-After), reduce the calls (e.g. poll less often), or ask festiware support to extend the allowance
422 with error.code = validation_failed on the file field of an upload The package's storage is full: once the nightly measurement of uploaded files reaches the limit, every request carrying a file is refused (the message names the figures) Delete files that are no longer needed (they count after the next nightly measurement) or ask festiware support to extend the storage
n8n shows "disconnected" after weeks/months Refresh token expired (1 year) or the credentials were reset Run Reset Credentials if needed, download the credentials and reconnect

Webhooks (events festiware sends to your endpoint, payloads, delivery and rate limit): see Webhooks at the end of this page.


API permissions

An API user gets its rights as API permissions. An admin ticks them in the festiware backend under Settings → All Settings → User Management → API Users → Edit. Tick only what the integration needs; no role is needed.

A higher level includes the lower ones (column Includes): an endpoint that requires “Read people and groups” (all_persons_and_applications_see) also accepts “Edit people and groups” (all_persons_and_applications_manage). A 403 answer names the missing API permission with its label and key, as in this table. Every endpoint states its permission under Required API permission.

API permissions without endpoints here unlock the older interface and the festiware apps.

People & groups

API permission Key Includes Endpoints (API v2)
Read people and groups all_persons_and_applications_see — GET /application-types (or formdefinition_see or workflow_see)
GET /person-types (or formdefinition_see or workflow_see)
GET /projects/{project}/people
GET /projects/{project}/people/{person}
GET /projects/{project}/applications
GET /projects/{project}/applications/{application}
GET /projects/{project}/applications/{application}/files/{field}
GET /projects/{project}/people/{person}/files/{field}
GET /projects/{project}/applications/{application}/comments
GET /projects/{project}/people/{person}/comments
GET /projects/{project}/teams/{team}/members
Edit people and groups all_persons_and_applications_manage Read people and groups PUT, PATCH /projects/{project}/people/{person}
PUT, PATCH /projects/{project}/applications/{application}
POST /projects/{project}/applications/{application}/files/{field}
DELETE /projects/{project}/applications/{application}/files/{field}
POST /projects/{project}/people/{person}/files/{field}
DELETE /projects/{project}/people/{person}/files/{field}
POST /projects/{project}/people/transitions/bulk
POST /projects/{project}/people/{person}/transitions
POST /projects/{project}/applications/transitions/bulk
POST /projects/{project}/applications/{application}/transitions
Create and delete people and groups all_persons_and_applications_administrate Edit people and groups, Read people and groups POST /projects/{project}/people
DELETE /projects/{project}/people/{person}
POST /projects/{project}/applications
DELETE /projects/{project}/applications/{application}
Read data qualifications app\modules\dataqualification\policies\dataqualificationtype_see — —
Read protected fields securedata_see — GET /projects/{project}/event-plans/{plan} (protected fields)
GET /projects/{project}/event-plans/{plan}/events (protected fields)
GET /projects/{project}/areas/{area}/events (protected fields)
GET /projects/{project}/events/{event} (protected fields)
GET /projects/{project}/ticket-codes (protected fields)
GET /projects/{project}/ticket-codes/{ticket_code} (protected fields)
GET /projects/{project}/people (protected fields)
POST /projects/{project}/people (protected fields)
GET /projects/{project}/people/{person} (protected fields)
PUT, PATCH /projects/{project}/people/{person} (protected fields)
GET /projects/{project}/applications (protected fields)
POST /projects/{project}/applications (protected fields)
GET /projects/{project}/applications/{application} (protected fields)
PUT, PATCH /projects/{project}/applications/{application} (protected fields)
GET /projects/{project}/applications/{application}/files/{field} (protected fields)
GET /projects/{project}/people/{person}/files/{field} (protected fields)
POST /projects/{project}/applications/{application}/files/{field} (protected fields)
DELETE /projects/{project}/applications/{application}/files/{field} (protected fields)
POST /projects/{project}/people/{person}/files/{field} (protected fields)
DELETE /projects/{project}/people/{person}/files/{field} (protected fields)
Read person and group type settings personandapplicationtype_see — GET /person-types/{personType}
GET /application-types/{applicationType}
GET /projects/{project}/person-types/{personType}/settings
GET /projects/{project}/application-types/{applicationType}/settings
Change person and group type settings personandapplicationtype_administrate Read person and group type settings PUT, PATCH /person-types/{personType}
PUT, PATCH /application-types/{applicationType}
PUT, PATCH /projects/{project}/person-types/{personType}/settings
PUT, PATCH /projects/{project}/application-types/{applicationType}/settings

Users & roles

API permission Key Includes Endpoints (API v2)
Read users and roles user_see — GET /users
GET /users/{user}
GET /roles
Edit users user_manage Read users and roles PUT, PATCH /users/{user}
Create and delete users and assign roles user_administrate Edit users, Read users and roles POST /users
DELETE /users/{user}

Forms & contracts

API permission Key Includes Endpoints (API v2)
Read forms formdefinition_see — GET /application-types (or all_persons_and_applications_see or workflow_see)
GET /person-types (or all_persons_and_applications_see or workflow_see)
GET /projects/{project}/form-definitions/{formDefinition}/validation
GET /projects/{project}/form-definitions
GET /projects/{project}/form-definitions/{formDefinition}
Edit forms formdefinition_manage Read forms PUT, PATCH /projects/{project}/form-definitions/{formDefinition}
Read contracts contract_see — GET /projects/{project}/contracts/{contract}
GET /projects/{project}/contracts/{contract}/pdf
List contracts contract_manage Read contracts GET /projects/{project}/contracts
Read contract types contracttype_see — GET /projects/{project}/contract-types

Check-in & entry

API permission Key Includes Endpoints (API v2)
Check-in check_in — —
Check access check_person_access — POST /projects/{project}/access-checks
GET /projects/{project}/access-holders
GET /projects/{project}/access-holders/version
Activate hard tickets ticket_activate — —
Health certificates check_health_certificate — —

Shop, tickets & invoices

API permission Key Includes Endpoints (API v2)
Shop orders order_post — —
Read orders and offers order_see — GET /projects/{project}/orders
GET /projects/{project}/orders/{order}
GET /projects/{project}/offer-categories
GET /projects/{project}/offer-categories/{category}
GET /projects/{project}/offerable-options
GET /projects/{project}/offerable-options/{option}
GET /projects/{project}/offer-categories/{category}/offers
GET /projects/{project}/offers
GET /projects/{project}/offers/{offer}
Manage offers order_administrate Read orders and offers POST /projects/{project}/offer-categories
PUT, PATCH /projects/{project}/offer-categories/{category}
DELETE /projects/{project}/offer-categories/{category}
POST /projects/{project}/offerable-options
PUT, PATCH /projects/{project}/offerable-options/{option}
DELETE /projects/{project}/offerable-options/{option}
POST /projects/{project}/offers
PUT, PATCH /projects/{project}/offers/{offer}
DELETE /projects/{project}/offers/{offer}
Read tickets ticketcode_see — GET /projects/{project}/ticket-types
GET /projects/{project}/ticket-types/{ticket_type}
GET /projects/{project}/ticket-codes
GET /projects/{project}/ticket-codes/{ticket_code}
GET /projects/{project}/orders (depending on the request)
GET /projects/{project}/orders/{order} (depending on the request)
Manage ticket types ticketcode_administrate Read tickets POST /projects/{project}/ticket-types
PUT, PATCH /projects/{project}/ticket-types/{ticket_type}
DELETE /projects/{project}/ticket-types/{ticket_type}
Read coupons app\modules\coupons\policies\coupon_see — GET /projects/{project}/coupons
GET /projects/{project}/coupons/{coupon}
Manage coupons app\modules\coupons\policies\coupon_administrate Read coupons POST /projects/{project}/coupons
PATCH /projects/{project}/coupons/{coupon}
DELETE /projects/{project}/coupons/{coupon}
Read invoices invoice_see — GET /projects/{project}/invoices
GET /projects/{project}/invoices/{invoice}
GET /projects/{project}/invoices/{invoice}/pdf

Planning

API permission Key Includes Endpoints (API v2)
Read scheduler scheduler_see — GET /projects/{project}/areas/{area}/events
GET /projects/{project}/event-types
Read areas area_see — GET /projects/{project}/areas
GET /projects/{project}/area-types
GET /projects/{project}/area-types/{type}
Read teams team_see — GET /projects/{project}/people (depending on the request)
GET /projects/{project}/teams
GET /projects/{project}/teams/{team}
GET /projects/{project}/teams/{team}/members
GET /projects/{project}/team-roles
Manage team members team_manage Read teams POST /projects/{project}/teams/{team}/members
DELETE /projects/{project}/teams/{team}/members/{person}
Edit areas area_manage Read areas PUT, PATCH /projects/{project}/area-types/{type}
Manage areas area_administrate Edit areas, Read areas POST /projects/{project}/area-types
DELETE /projects/{project}/area-types/{type}
Edit scheduler scheduler_manage Read scheduler —
Manage scheduler scheduler_administrate Edit scheduler, Read scheduler POST /projects/{project}/event-plans
DELETE /projects/{project}/event-plans/{plan}
POST /projects/{project}/event-types
PUT, PATCH /projects/{project}/event-types/{type}
DELETE /projects/{project}/event-types/{type}

Catering & vouchers

API permission Key Includes Endpoints (API v2)
Catering: hand out meals app\modules\catering\policies\mealorder_manage — —
Redeem vouchers app\modules\vouchers\policies\voucher_manage — —

Supplies

API permission Key Includes Endpoints (API v2)
Read supplies app\modules\supply\policies\supply_see — GET /projects/{project}/supplies
GET /projects/{project}/supply-categories
GET /projects/{project}/supplies/{supply}/items
GET /projects/{project}/supply-items/{supplyItem}
Manage supplies app\modules\supply\policies\supply_administrate Read supplies POST /projects/{project}/supplies/{supply}/items
Hand out supplies app\modules\supply\policies\supplytracking_manage — POST /projects/{project}/supply-tracking-events

Time tracking

API permission Key Includes Endpoints (API v2)
Time tracking time_tracking — —

Workflows & webhooks

API permission Key Includes Endpoints (API v2)
Read workflows workflow_see — GET /application-types (or all_persons_and_applications_see or formdefinition_see)
GET /person-types (or all_persons_and_applications_see or formdefinition_see)
GET /projects/{project}/workflows/{workflow}/export
GET /projects/{project}/workflows/{workflow}/triggers
GET /projects/{project}/workflows
GET /projects/{project}/workflows/{workflow}
GET /projects/{project}/workflow-triggers/{workflowTrigger}
GET /projects/{project}/webhooks/{webhook}/triggers
Edit workflows workflow_manage Read workflows POST /projects/{project}/workflows/import
PATCH /projects/{project}/workflow-triggers/{workflowTrigger}
Create and delete triggers workflow_administrate Edit workflows, Read workflows DELETE /projects/{project}/webhooks/{webhook} (depending on the request)
POST /projects/{project}/webhooks/{webhook}/triggers
DELETE /projects/{project}/webhooks/{webhook}/triggers/{workflowTrigger}
Send webhook responses webhook_manage — GET /projects/{project}/webhooks
GET /projects/{project}/webhooks/{webhook}
PATCH /projects/{project}/webhooks/{webhook}
GET /projects/{project}/webhooks/{webhook}/triggers
Manage webhooks webhook_administrate Send webhook responses POST /projects/{project}/webhooks
DELETE /projects/{project}/webhooks/{webhook}
POST /projects/{project}/webhooks/{webhook}/triggers
DELETE /projects/{project}/webhooks/{webhook}/triggers/{workflowTrigger}

Project

API permission Key Includes Endpoints (API v2)
Read and change project settings app\modules\projects\policies\project_manage — GET /projects/{project}/settings
PATCH /projects/{project}/settings

Endpoints without an API permission

Endpoint Rule
GET /projects Any API user. Lists only the projects the API user may use (its project access).
GET /me Any API user. Describes only the calling API access itself: its permissions, project access, type restriction and token.
GET /projects/{project}/event-plans Lists only the schedules the caller may see: a schedule without view roles needs “Read scheduler” (scheduler_see), one with view roles one of those roles; “Manage scheduler” (scheduler_administrate) sees every schedule.
GET /projects/{project}/event-plans/{plan} A schedule without view roles needs “Read scheduler” (scheduler_see), one with view roles one of those roles; “Manage scheduler” (scheduler_administrate) sees every schedule. Nested people and groups additionally need “Read people and groups” (all_persons_and_applications_see).
GET /projects/{project}/event-plans/{plan}/events A schedule without view roles needs “Read scheduler” (scheduler_see), one with view roles one of those roles; “Manage scheduler” (scheduler_administrate) sees every schedule. Nested people and groups additionally need “Read people and groups” (all_persons_and_applications_see).
PUT, PATCH /projects/{project}/event-plans/{plan} Whoever may edit the schedule: “Manage scheduler” (scheduler_administrate), the schedule owner, one of its edit roles, or “Edit scheduler” (scheduler_manage) when the schedule has neither owner nor edit roles. Changing view roles, edit roles or the owner needs “Manage scheduler” (scheduler_administrate).
POST /projects/{project}/event-plans/{plan}/events Whoever may edit the schedule: “Manage scheduler” (scheduler_administrate), the schedule owner, one of its edit roles, or “Edit scheduler” (scheduler_manage) when the schedule has neither owner nor edit roles. When events may be edited outside schedule permissions (setting): any schedule, for “Edit scheduler” (scheduler_manage) or whoever may edit at least one schedule of the project.
GET /projects/{project}/events/{event} Whoever sees a schedule that shows the event (see the schedule endpoints), “Read scheduler” (scheduler_see) when no schedule shows it; anybody when events may be edited outside schedule permissions (setting). Nested people and groups additionally need “Read people and groups” (all_persons_and_applications_see).
PUT, PATCH /projects/{project}/events/{event} Whoever may edit a schedule that shows the event, “Edit scheduler” (scheduler_manage) when no schedule shows it; anybody when events may be edited outside schedule permissions (setting).
DELETE /projects/{project}/events/{event} Whoever may edit a schedule that shows the event, “Edit scheduler” (scheduler_manage) when no schedule shows it; anybody when events may be edited outside schedule permissions (setting).
POST /projects/{project}/events/{event}/jobs Whoever may edit the shift's event (see updating an event).
PUT, PATCH /projects/{project}/jobs/{job} Whoever may edit the shift's event (see updating an event).
DELETE /projects/{project}/jobs/{job} Whoever may edit the shift's event (see updating an event).

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {ACCESS_TOKEN}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

Obtain a token via OAuth 2.0 Authorization Code grant. See the connection guide in the introduction (backend → OAuth client → token; recipes for n8n and Postman). The returned access_token must be sent as a Bearer token in the Authorization header.

People

List person types.

requires authentication

Returns every person type defined on the instance, paginated. Global reference data; not project-scoped.

An API access restricted to certain person and group types (set on the API user in festiware) sees only its person types here; an access restricted to group types only gets an empty list.

Requires one of all_persons_and_applications_see, formdefinition_see or workflow_see (or a higher level of one of them): the permissions of the people and group, form and workflow endpoints that use these shortnames. Without any of them 403.

Required API permission: one of “Read people and groups” (all_persons_and_applications_see) or “Read forms” (formdefinition_see) or “Read workflows” (workflow_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/person-types?per_page=25&page=1&created_since=2026-06-01T00%3A00%3A00%2B00%3A00&updated_since=2026-06-01T00%3A00%3A00%2B00%3A00" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/person-types"
);

const params = {
    "per_page": "25",
    "page": "1",
    "created_since": "2026-06-01T00:00:00+00:00",
    "updated_since": "2026-06-01T00:00:00+00:00",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/person-types';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'page' => '1',
            'created_since' => '2026-06-01T00:00:00+00:00',
            'updated_since' => '2026-06-01T00:00:00+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": 12,
            "shortname": "artist",
            "name": "Artist",
            "description": null
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Without any of the three permissions):


{
    "error": {
        "code": "permission_denied",
        "message": "This API access lacks the API permission \"Read people and groups\" (all_persons_and_applications_see) or \"Read forms\" (formdefinition_see) or \"Read workflows\" (workflow_see). An admin grants it in festiware under Settings → All Settings → User Management → API Users → \"My integration\" → Edit."
    }
}
 

Request      

GET api/v2/person-types

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

page   integer  optional    

Page number (1-indexed). Example: 1

created_since   string  optional    

ISO 8601 timestamp with offset; only records created at or after it. Example: 2026-06-01T00:00:00+00:00

updated_since   string  optional    

ISO 8601 timestamp with offset; only records updated at or after it. Example: 2026-06-01T00:00:00+00:00

Show a person type.

requires authentication

The list fields plus the global settings of the type: menu name, singular name and the read-only structural keys. These settings apply to every project of the instance; the per-project portal and check-in settings are on GET /api/v2/projects/{project}/person-types/{personType}/settings.

Requires personandapplicationtype_see (or personandapplicationtype_administrate), the permission of the type settings in the backend. An API access restricted to certain person and group types gets 403 type_not_allowed for any other type.

Rate limited per user (api-v2-config-read).

Required API permission: “Read person and group type settings” (personandapplicationtype_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/person-types/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/person-types/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/person-types/16';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": 12,
        "shortname": "VolunteerPerson",
        "name": "Volunteers",
        "description": null,
        "menu_name": "Crew",
        "name_singular": "Volunteer",
        "extends": null,
        "is_default_resource": false,
        "creates": null,
        "shows": null,
        "permission_key": "volunteer",
        "created_at": "2026-01-10T09:00:00+00:00",
        "updated_at": "2026-10-08T09:00:00+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Example response (429, TooManyRequests):


{
    "error": {
        "code": "too_many_requests",
        "message": "Too many requests."
    }
}
 

Request      

GET api/v2/person-types/{personType_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

personType_id   integer     

The ID of the personType. Example: 16

personType   integer     

Person type id. Example: 12

Update a person type.

requires authentication

Instance-wide: the type and its settings are shared by every project of the instance; a change here applies to all of them.

PUT and PATCH both route here. PUT is a full replace: it requires name and resets every other settable key it leaves out (to null, read back as the default); PATCH keeps what it omits. Settable: name, description, menu_name, name_singular. shortname is immutable (send it unchanged or not at all); id, extends, is_default_resource, creates, shows, permission_key and created_at are read-only and answer 422 when sent, as does any unknown key. Relations (form definition, workflow steps, PDF templates, permissions) are managed elsewhere.

Side effect: renaming the type renames its generated roles ("{name} Supervisor", "{name} Manager", "{name} Observer"). The response lists them in side_effects.roles_renamed; with dry_run=true it lists the expected renames and saves nothing, fires no triggers and writes no change log.

Every save is written to the change log (who, when, before/after), like an edit in the backend.

Requires personandapplicationtype_administrate. A type outside the API access's type restriction answers 403 type_not_allowed. An API access limited to certain projects answers 403 cross_project_access_denied: the change would reach projects outside its list. Access checks run before validation. Rate limited per user (api-v2-config-write).

Required API permission: “Change person and group type settings” (personandapplicationtype_administrate)

Example request:
curl --request PUT \
    "https://{instance}.festiwa.re/api/v2/person-types/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Volunteers\",
    \"description\": \"Crew working shifts on site\",
    \"menu_name\": \"Volunteers\",
    \"name_singular\": \"Volunteer\",
    \"shortname\": \"VolunteerPerson\",
    \"updated_at\": \"2026-10-08T09:00:00+00:00\",
    \"dry_run\": false
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/person-types/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "Volunteers",
    "description": "Crew working shifts on site",
    "menu_name": "Volunteers",
    "name_singular": "Volunteer",
    "shortname": "VolunteerPerson",
    "updated_at": "2026-10-08T09:00:00+00:00",
    "dry_run": false
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/person-types/16';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'name' => 'Volunteers',
            'description' => 'Crew working shifts on site',
            'menu_name' => 'Volunteers',
            'name_singular' => 'Volunteer',
            'shortname' => 'VolunteerPerson',
            'updated_at' => '2026-10-08T09:00:00+00:00',
            'dry_run' => false,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Saved):


{
    "data": {
        "id": 12,
        "shortname": "VolunteerPerson",
        "name": "Helpers",
        "description": null,
        "menu_name": "Crew",
        "name_singular": "Helper",
        "extends": null,
        "is_default_resource": false,
        "creates": null,
        "shows": null,
        "permission_key": "volunteer",
        "created_at": "2026-01-10T09:00:00+00:00",
        "updated_at": "2026-10-08T09:05:00+00:00"
    },
    "side_effects": {
        "roles_renamed": [
            {
                "from": "Volunteers Supervisor",
                "to": "Helpers Supervisor"
            },
            {
                "from": "Volunteers Manager",
                "to": "Helpers Manager"
            },
            {
                "from": "Volunteers Observer",
                "to": "Helpers Observer"
            }
        ]
    }
}
 

Example response (200, DryRun):


{
    "data": {
        "dry_run": true,
        "would_save": true,
        "changes": [
            "name"
        ]
    },
    "side_effects": {
        "roles_renamed": [
            {
                "from": "Volunteers Supervisor",
                "to": "Helpers Supervisor"
            }
        ]
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (403, Project-restricted access):


{
    "error": {
        "code": "cross_project_access_denied",
        "message": "A person or group type is shared by every project of the instance. This API access is limited to certain projects, so it cannot change the type itself; its project settings are on /api/v2/projects/{project}/…/settings."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Example response (409, OptimisticLockFailed):


{
    "error": {
        "code": "optimistic_lock_failed",
        "message": "The resource was modified after your last read. Re-fetch and retry.",
        "errors": {
            "current": {
                "updated_at": "2026-10-08T09:05:00+00:00"
            }
        }
    }
}
 

Example response (422, Invalid):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "shortname": [
                "The shortname of a type cannot be changed."
            ]
        }
    }
}
 

Example response (429, TooManyRequests):


{
    "error": {
        "code": "too_many_requests",
        "message": "Too many requests."
    }
}
 

Request      

PUT api/v2/person-types/{personType_id}

PATCH api/v2/person-types/{personType_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

personType_id   integer     

The ID of the personType. Example: 16

personType   integer     

Person type id. Example: 12

Body Parameters

name   string     

Required on PUT (PUT is a full replace: every other settable key left out is reset to its default). Plural name (max 36), unique among the person (or group) types. Renaming also renames the type's generated roles ("{name} Supervisor|Manager|Observer"); the response lists them in side_effects.roles_renamed. Must not be greater than 36 characters. Example: Volunteers

description   string  optional    

Internal description. Example: Crew working shifts on site

menu_name   string  optional    

Name in the backend menu (max 36). null falls back to the type name. Must not be greater than 36 characters. Example: Volunteers

name_singular   string  optional    

Singular name (max 36). Must not be greater than 36 characters. Example: Volunteer

shortname   string  optional    

Immutable. May be sent back unchanged; a different value answers 422. Example: VolunteerPerson

updated_at   string     

Optimistic lock: the updated_at you read. A newer stored version answers 409 optimistic_lock_failed. Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-10-08T09:00:00+00:00

dry_run   boolean  optional    

Validate only: returns what would change and the side effects (side_effects.roles_renamed), writes nothing and fires nothing. Example: false

id   string  optional    
extends   string  optional    
is_default_resource   string  optional    
creates   string  optional    
shows   string  optional    
permission_key   string  optional    
created_at   string  optional    

Paginated list of Persons in a project.

requires authentication

Required API permission: “Read people and groups” (all_persons_and_applications_see)

Depending on the request also: “Read teams” (team_see)

Depending on the permission: form fields marked as protected are returned in plain text only with “Read protected fields” (securedata_see) as a direct API permission of the API user (a role does not count); without it their keys are left out of data and calculated_data, also of nested people and groups, and a nested person's name or e-mail or a group's name is null.

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/people?email=anna%40example.com&updated_since=2026-04-30T00%3A00%3A00%2B00%3A00&person_type=volunteer&step=acc_buildup&workflow_id=209&withJourney=&group=812&withGroups=&withContracts=&team=tech&withTeams=&per_page=25&created_since=2026-06-01T00%3A00%3A00%2B00%3A00%0A%0AEvery+Person+also+carries+an+always-on+%60related%60+block+%28no+flag+needed%29%3A+ID-only%0Aarrays+of+linked+resources+%E2%80%94+teams%2C+team_roles%2C+groups_owned%2Fgroups_member+%28the%0APerson%27s+Groups%29%2C+events%2C+tickets%2C+orders%2C+person_access_types%2C+coupons%2C%0Anfc_tags%2C+contracts+%E2%80%94+for+follow-up+requests.+Use+the+existing+%60%3Fwith%2A%60+flags+to%0Aupgrade+a+single+relation+to+a+full+nested+resource." \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"per_page\": 16,
    \"email\": \"zbailey@example.net\",
    \"updated_since\": \"2026-11-19T01:25:40+01:00\",
    \"person_type\": \"architecto\",
    \"step\": \"architecto\",
    \"workflow_id\": 16,
    \"withJourney\": false,
    \"group\": 22,
    \"withGroups\": false,
    \"withContracts\": true,
    \"team\": \"g\",
    \"withTeams\": false
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/people"
);

const params = {
    "email": "anna@example.com",
    "updated_since": "2026-04-30T00:00:00+00:00",
    "person_type": "volunteer",
    "step": "acc_buildup",
    "workflow_id": "209",
    "withJourney": "0",
    "group": "812",
    "withGroups": "0",
    "withContracts": "0",
    "team": "tech",
    "withTeams": "0",
    "per_page": "25",
    "created_since": "2026-06-01T00:00:00+00:00

Every Person also carries an always-on `related` block (no flag needed): ID-only
arrays of linked resources — teams, team_roles, groups_owned/groups_member (the
Person's Groups), events, tickets, orders, person_access_types, coupons,
nfc_tags, contracts — for follow-up requests. Use the existing `?with*` flags to
upgrade a single relation to a full nested resource.",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "per_page": 16,
    "email": "zbailey@example.net",
    "updated_since": "2026-11-19T01:25:40+01:00",
    "person_type": "architecto",
    "step": "architecto",
    "workflow_id": 16,
    "withJourney": false,
    "group": 22,
    "withGroups": false,
    "withContracts": true,
    "team": "g",
    "withTeams": false
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/people';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'email' => 'anna@example.com',
            'updated_since' => '2026-04-30T00:00:00+00:00',
            'person_type' => 'volunteer',
            'step' => 'acc_buildup',
            'workflow_id' => '209',
            'withJourney' => '0',
            'group' => '812',
            'withGroups' => '0',
            'withContracts' => '0',
            'team' => 'tech',
            'withTeams' => '0',
            'per_page' => '25',
            'created_since' => '2026-06-01T00:00:00+00:00

Every Person also carries an always-on `related` block (no flag needed): ID-only
arrays of linked resources — teams, team_roles, groups_owned/groups_member (the
Person's Groups), events, tickets, orders, person_access_types, coupons,
nfc_tags, contracts — for follow-up requests. Use the existing `?with*` flags to
upgrade a single relation to a full nested resource.',
        ],
        'json' => [
            'per_page' => 16,
            'email' => 'zbailey@example.net',
            'updated_since' => '2026-11-19T01:25:40+01:00',
            'person_type' => 'architecto',
            'step' => 'architecto',
            'workflow_id' => 16,
            'withJourney' => false,
            'group' => 22,
            'withGroups' => false,
            'withContracts' => true,
            'team' => 'g',
            'withTeams' => false,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
            "project_id": 1,
            "data": {
                "firstname": "Anna",
                "email": "anna@example.com"
            },
            "calculated_data": {},
            "person_types": [
                "volunteer"
            ],
            "created_at": "2026-04-30T11:24:53+00:00",
            "updated_at": "2026-04-30T11:24:53+00:00",
            "related": {
                "teams": [
                    405,
                    426
                ],
                "team_roles": [
                    12
                ],
                "groups_owned": [],
                "groups_member": [
                    3310
                ],
                "events": [
                    881
                ],
                "tickets": [],
                "orders": [],
                "person_access_types": [
                    4
                ],
                "coupons": [],
                "nfc_tags": [],
                "contracts": [
                    3021
                ]
            }
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (200, With journey (?withJourney=1)):


{
    "data": [
        {
            "id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
            "project_id": 1,
            "data": {
                "firstname": "Anna"
            },
            "calculated_data": {},
            "person_types": [
                "volunteer"
            ],
            "created_at": "2026-04-30T11:24:53+00:00",
            "updated_at": "2026-04-30T11:24:53+00:00",
            "current_steps": [
                {
                    "workflow_id": 209,
                    "step": {
                        "id": 1904,
                        "shortname": "acc_buildup",
                        "name": "2a) Akkreditierung Aufbau"
                    },
                    "entered_at": "2026-05-01T09:00:00+00:00"
                }
            ],
            "journey": [
                {
                    "step": {
                        "id": 1904,
                        "shortname": "acc_buildup"
                    },
                    "registered_at": "2026-05-01T09:00:00+00:00",
                    "user_id": null
                }
            ]
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (200, With contracts (?withContracts=1)):


{
    "data": [
        {
            "id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
            "project_id": 1,
            "data": {
                "firstname": "Anna"
            },
            "calculated_data": {},
            "person_types": [
                "volunteer"
            ],
            "created_at": "2026-04-30T11:24:53+00:00",
            "updated_at": "2026-04-30T11:24:53+00:00",
            "contracts": [
                {
                    "id": 326,
                    "contract_number": "V-2026-0042",
                    "status": "signed",
                    "contract_type": {
                        "id": 4,
                        "shortname": "ARTIST"
                    }
                }
            ]
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (403, Filter on a hidden field):


{
    "error": {
        "code": "filter_not_allowed",
        "message": "Filter 'email' is not allowed: it searches data.email, which data qualification 'Personal Data' protects on a person form of this project, and your user does not hold it. Remove the email parameter and find the person another way (e.g. by id).",
        "errors": {
            "email": [
                "Filter 'email' is not allowed: it searches data.email, which data qualification 'Personal Data' protects on a person form of this project, and your user does not hold it. Remove the email parameter and find the person another way (e.g. by id)."
            ]
        }
    }
}
 

Example response (403, TypeNotAllowed):


{
    "error": {
        "code": "type_not_allowed",
        "message": "This API access is restricted to certain person and group types; the person type “Crew” (crew) is not one of them. An admin changes this in festiware under Settings → … → “People sync” → Edit."
    }
}
 

Example response (422, Invalid query parameter):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "per_page": [
                "The per page must not be greater than 100."
            ]
        }
    }
}
 

Request      

GET api/v2/projects/{project_id}/people

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Query Parameters

email   string  optional    

Optional exact-match filter against data.email (also email_private / email_corporate). Variants that data qualification hides from you are not searched; if email itself is hidden on a person form of the project, the filter is refused with 403 filter_not_allowed. Example: anna@example.com

updated_since   string  optional    

Optional ISO 8601 timestamp; returns Persons modified at or after this moment. Example: 2026-04-30T00:00:00+00:00

person_type   string  optional    

Optional PersonType shortname filter. Example: volunteer

step   string  optional    

Optional. Filter by the Person's CURRENT workflow-step shortname. LIMITATION: "current" is the Person's latest step OVERALL, not per workflow — for a Person in several workflows an older step in one workflow is not matched while a newer step in another is active. Pass workflow_id to scope, and note it still filters on the latest-overall status. Single-workflow Persons (the norm) are unaffected. Example: acc_buildup

workflow_id   integer  optional    

Optional. Narrow the step filter to one Workflow — needed when a Person is in several. Example: 209

withJourney   boolean  optional    

Optional. Sideload current_steps (latest step per workflow) and journey (full step history) on each Person. Default false. Example: false

group   integer  optional    

Optional. Only Persons who own OR are a member of this Group (id). Example: 812

withGroups   boolean  optional    

Optional. Sideload groups: one array of the Person's Groups, each {id, name, type: {id, shortname}, role} with role = owner or member. A Person who owns and is a member of the same Group appears twice, once per role. Default false. Example: false

withContracts   boolean  optional    

Optional. Sideload contracts: the Person's contracts in this project, each {id, contract_number, status, contract_type: {id, shortname}}. Requires contract_manage on this list (contract_see is enough on the single record); the key is omitted without it. Default false. Example: false

team   string  optional    

Optional. Requires team_see in addition (403 without). Only Persons who are a member of this Team of the project, by id or shortname. A team of another project or an unknown one matches nobody (empty list, no error). Team membership here is the staff membership (backend "Teammitglieder"), not a volunteer assignment of the contribution portal. Example: tech

withTeams   boolean  optional    

Optional. Requires team_see in addition (403 without). Sideload teams: the Person's Teams of this project, each {id, shortname, name, team_role_id, has_role_since, has_role_until} (role and dates of the membership, dates as Y-m-d). Default false. Example: false

per_page   integer  optional    

Page size, clamped to 100. Example: 25

created_since   string  optional    

ISO 8601 timestamp with offset; only records created at or after it. Example: `2026-06-01T00:00:00+00:00

Every Person also carries an always-on related block (no flag needed): ID-only arrays of linked resources — teams, team_roles, groups_owned/groups_member (the Person's Groups), events, tickets, orders, person_access_types, coupons, nfc_tags, contracts — for follow-up requests. Use the existing ?with* flags to upgrade a single relation to a full nested resource.`

Body Parameters

per_page   integer  optional    

Must be at least 1. Example: 16

email   string  optional    

Must not be greater than 255 characters. Example: zbailey@example.net

updated_since   string  optional    

Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-11-19T01:25:40+01:00

person_type   string  optional    

The shortname of an existing record in the types table. Example: architecto

step   string  optional    

Example: architecto

workflow_id   integer  optional    

The id of an existing record in the workflows table. Example: 16

withJourney   boolean  optional    

Example: false

group   integer  optional    

Must be at least 1. Example: 22

withGroups   boolean  optional    

Example: false

withContracts   boolean  optional    

Example: true

team   string  optional    

Must not be greater than 255 characters. Example: g

withTeams   boolean  optional    

Example: false

Create a new Person in a project.

requires authentication

Required API permission: “Create and delete people and groups” (all_persons_and_applications_administrate)

Depending on the permission: form fields marked as protected are returned in plain text only with “Read protected fields” (securedata_see) as a direct API permission of the API user (a role does not count); without it their keys are left out of data and calculated_data, also of nested people and groups, and a nested person's name or e-mail or a group's name is null.

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/people" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --data "{
    \"id\": \"architecto\",
    \"person_types\": [
        \"volunteer\"
    ],
    \"act_as_backend_creation\": false,
    \"data\": {
        \"firstname\": \"Anna\",
        \"email\": \"anna@example.com\"
    }
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/people"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

let body = {
    "id": "architecto",
    "person_types": [
        "volunteer"
    ],
    "act_as_backend_creation": false,
    "data": {
        "firstname": "Anna",
        "email": "anna@example.com"
    }
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/people';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'json' => [
            'id' => 'architecto',
            'person_types' => [
                'volunteer',
            ],
            'act_as_backend_creation' => false,
            'data' => [
                'firstname' => 'Anna',
                'email' => 'anna@example.com',
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201, Created):


{
    "data": {
        "id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
        "project_id": 1,
        "data": {
            "firstname": "Anna",
            "email": "anna@example.com"
        },
        "calculated_data": {},
        "person_types": [
            "volunteer"
        ],
        "created_at": "2026-04-30T11:24:53+00:00",
        "updated_at": "2026-04-30T11:24:53+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (403, TypeNotAllowed):


{
    "error": {
        "code": "type_not_allowed",
        "message": "This API access is restricted to certain person and group types; the person type “Crew” (crew) is not one of them. An admin changes this in festiware under Settings → … → “People sync” → Edit."
    }
}
 

Example response (409, DuplicateId):


{
    "error": {
        "code": "duplicate_id",
        "message": "A Person with this id already exists."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "data": [
                "The data field is required."
            ],
            "person_types": [
                "The person_types field is required."
            ]
        }
    }
}
 

Example response (422, QuotaExceeded):


{
    "error": {
        "code": "validation_failed",
        "message": "Your package's \"Active people and groups\" allowance is used up (500 of 500). Contact festiware support to extend it.",
        "errors": {
            "person_types": [
                "Your package's \"Active people and groups\" allowance is used up (500 of 500). Contact festiware support to extend it."
            ]
        }
    }
}
 

Request      

POST api/v2/projects/{project_id}/people

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Body Parameters

id   string  optional    

Optional caller-supplied UUID. Auto-generated if omitted; rejected with 409 if already used. Example: architecto

person_types   string[]     

Array of PersonType shortnames. At least one.

act_as_backend_creation   boolean  optional    

If true, the write is treated as backend-originated by downstream WorkflowTrigger evaluation. Default: false. Example: false

data   object     

Map of custom-data fields. Scalar values only.

Show a single Person by UUID.

requires authentication

Required API permission: “Read people and groups” (all_persons_and_applications_see)

Depending on the permission: form fields marked as protected are returned in plain text only with “Read protected fields” (securedata_see) as a direct API permission of the API user (a role does not count); without it their keys are left out of data and calculated_data, also of nested people and groups, and a nested person's name or e-mail or a group's name is null.

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/people/architecto?withContracts=" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/people/architecto"
);

const params = {
    "withContracts": "0",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/people/architecto';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'withContracts' => '0',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
        "project_id": 1,
        "data": {
            "firstname": "Anna",
            "email": "anna@example.com"
        },
        "calculated_data": {},
        "person_types": [
            "volunteer"
        ],
        "created_at": "2026-04-30T11:24:53+00:00",
        "updated_at": "2026-04-30T11:24:53+00:00"
    }
}
 

Example response (200, With contracts (?withContracts=1)):


{
    "data": {
        "id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
        "project_id": 1,
        "data": {
            "firstname": "Anna",
            "email": "anna@example.com"
        },
        "calculated_data": {},
        "person_types": [
            "volunteer"
        ],
        "created_at": "2026-04-30T11:24:53+00:00",
        "updated_at": "2026-04-30T11:24:53+00:00",
        "contracts": [
            {
                "id": 326,
                "contract_number": "V-2026-0042",
                "status": "signed",
                "contract_type": {
                    "id": 4,
                    "shortname": "ARTIST"
                }
            }
        ]
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Person not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/people/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   string     

The ID of the person. Example: architecto

project   integer     

Project id. Example: 16

person   string     

Person UUID. Example: architecto

Query Parameters

withContracts   boolean  optional    

Optional. Sideload contracts: the Person's contracts in this project, each {id, contract_number, status, contract_type: {id, shortname}}. Requires contract_see; the key is omitted without it. Default false. Example: false

Update a Person.

requires authentication

Both PUT and PATCH route here. The behavioural switch is replaceMissing:

Both verbs require an updated_at body field (ISO 8601) matching the Person's current updated_at; mismatch returns 409 with error.errors.current.updated_at.

Required API permission: “Edit people and groups” (all_persons_and_applications_manage)

Depending on the permission: form fields marked as protected are returned in plain text only with “Read protected fields” (securedata_see) as a direct API permission of the API user (a role does not count); without it their keys are left out of data and calculated_data. A protected field you cannot read keeps the value already stored: sending it fills an empty field but never changes or clears a stored value (also not by a PUT that leaves it out), and warnings names it.

Example request:
curl --request PUT \
    "https://{instance}.festiwa.re/api/v2/projects/564/people/architecto" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"person_types\": [
        \"architecto\"
    ],
    \"act_as_backend_creation\": false,
    \"data\": [],
    \"updated_at\": \"2026-04-30T11:24:53+00:00\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/people/architecto"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "person_types": [
        "architecto"
    ],
    "act_as_backend_creation": false,
    "data": [],
    "updated_at": "2026-04-30T11:24:53+00:00"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/people/architecto';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'person_types' => [
                'architecto',
            ],
            'act_as_backend_creation' => false,
            'data' => [],
            'updated_at' => '2026-04-30T11:24:53+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
        "project_id": 1,
        "data": {
            "firstname": "Anna",
            "email": "anna@example.com"
        },
        "calculated_data": {},
        "person_types": [
            "volunteer"
        ],
        "created_at": "2026-04-30T11:24:53+00:00",
        "updated_at": "2026-04-30T12:00:00+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (403, TypeNotAllowed):


{
    "error": {
        "code": "type_not_allowed",
        "message": "This API access is restricted to certain person and group types; the person type “Crew” (crew) is not one of them. An admin changes this in festiware under Settings → … → “People sync” → Edit."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Person not found."
    }
}
 

Example response (409, OptimisticLockFailed):


{
    "error": {
        "code": "optimistic_lock_failed",
        "message": "The Person was modified after your last read.",
        "errors": {
            "current": {
                "updated_at": "2026-04-30T11:24:53+00:00"
            }
        }
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "updated_at": [
                "The updated_at field is required."
            ]
        }
    }
}
 

Example response (422, LastAllowedTypeRemoved):


{
    "error": {
        "code": "validation_failed",
        "message": "This API access is restricted to certain person types (Artist (artist)). After this change the person would have none of them left and would no longer be accessible through this access. Keep at least one of these types in person_types.",
        "errors": {
            "person_types": [
                "This API access is restricted to certain person types (Artist (artist)). After this change the person would have none of them left and would no longer be accessible through this access. Keep at least one of these types in person_types."
            ]
        }
    }
}
 

Example response (422, QuotaExceeded):


{
    "error": {
        "code": "validation_failed",
        "message": "Your package's \"Active people and groups\" allowance is used up (500 of 500). Contact festiware support to extend it.",
        "errors": {
            "person_types": [
                "Your package's \"Active people and groups\" allowance is used up (500 of 500). Contact festiware support to extend it."
            ]
        }
    }
}
 

Request      

PUT api/v2/projects/{project_id}/people/{id}

PATCH api/v2/projects/{project_id}/people/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   string     

The ID of the person. Example: architecto

project   integer     

Project id. Example: 16

person   string     

Person UUID. Example: architecto

Body Parameters

person_types   string[]  optional    

Optional array of PersonType shortnames. If present, REPLACES existing assignments. If omitted, pivot is unchanged.

act_as_backend_creation   boolean  optional    

When true, downstream WorkflowTrigger evaluation treats this write as backend-originated (matches create/v1 semantics) — triggers flagged skip_after_backend_creation do NOT fire. Used so API write-backs (e.g. an automation relaying coupon codes onto a Person) don't re-trigger the outbound webhook. Defaults to false. The legacy camelCase alias actAsBackendCreation is accepted (snake-case wins on collision). Example: false

data   object     

Map of custom-data fields (scalar values only).

updated_at   string     

ISO 8601 timestamp of the last known version (optimistic-lock token). Example: 2026-04-30T11:24:53+00:00

Soft-delete a Person.

requires authentication

Requires explicit confirm: true in the body. Missing or false confirmation returns 422 and the Person remains intact. Soft-deleted Persons return 404 from all subsequent v2 endpoints.

Required API permission: “Create and delete people and groups” (all_persons_and_applications_administrate)

Example request:
curl --request DELETE \
    "https://{instance}.festiwa.re/api/v2/projects/564/people/architecto" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"confirm\": true
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/people/architecto"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "confirm": true
};

fetch(url, {
    method: "DELETE",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/people/architecto';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'confirm' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (204, SoftDeleted):

Empty response
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Person not found."
    }
}
 

Example response (409, PersonHasContracts):


{
    "error": {
        "code": "person_has_contracts",
        "message": "Person has signed contracts and cannot be deleted."
    }
}
 

Example response (409, PersonHasInvoices):


{
    "error": {
        "code": "person_has_invoices",
        "message": "Person has linked invoices and cannot be deleted."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "confirm": [
                "The confirm field must be accepted."
            ]
        }
    }
}
 

Request      

DELETE api/v2/projects/{project_id}/people/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   string     

The ID of the person. Example: architecto

project   integer     

Project id. Example: 16

person   string     

Person UUID. Example: architecto

Body Parameters

confirm   boolean     

Must be exactly true to confirm deletion. Example: true

Show the project settings of a person type.

requires authentication

The participant portal settings (portal) and the check-in settings (checkin) of the type in this project. Keys are the stored ones, as the backend form names them: per portal module <module> (on/off), <module>From, <module>To (publication window) plus its own options (e.g. guestListTicketType, eventsSettings.eventTypes). Only the modules available on the instance appear. Lists of ids come back as stored (strings).

Not returned: the redirects and the price list mail texts (they hold code, see the update endpoint).

A type without stored settings in the project returns empty sections and updated_at: null.

Requires personandapplicationtype_see (or personandapplicationtype_administrate). A type outside the API access's type restriction answers 403 type_not_allowed. Rate limited per user (api-v2-config-read).

Required API permission: “Read person and group type settings” (personandapplicationtype_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/person-types/16/settings" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/person-types/16/settings"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/person-types/16/settings';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "type": {
            "id": 12,
            "shortname": "VolunteerPerson"
        },
        "project_id": 5,
        "portal": {
            "updateForm": true,
            "updateFormFrom": "2026-03-01 00:00:00",
            "updateFormTo": null,
            "updateFormLabel": {
                "de": "Daten ändern",
                "en": "Edit your data"
            },
            "guestList": false,
            "eventsSettings": {
                "eventTypes": [
                    "3",
                    "4"
                ],
                "hideAssignedEvents": false
            }
        },
        "checkin": {
            "issuableTicketTypes": [
                "21"
            ]
        },
        "updated_at": "2026-10-08T09:00:00+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (403, Other project):


{
    "error": {
        "code": "cross_project_access_denied",
        "message": "You do not have access to this project."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Example response (429, TooManyRequests):


{
    "error": {
        "code": "too_many_requests",
        "message": "Too many requests."
    }
}
 

Request      

GET api/v2/projects/{project_id}/person-types/{personType_id}/settings

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

personType_id   integer     

The ID of the personType. Example: 16

project   integer     

Project id. Example: 5

personType   integer     

Person type id. Example: 12

Update the project settings of a person type.

requires authentication

Changes the portal and check-in settings of the type in this project only.

PUT replaces every settable key of portal (and checkin) — a settable key left out is removed — and requires both sections; PATCH sets only the keys it sends. Keys are the ones GET returns. A key that is unknown, belongs to a module not available on the instance, or is not settable answers 422 and nothing is saved.

Not settable (code fields): redirects (its condition is a Twig expression) and the price list mail texts are executed on the server and stay closed to the API until templates run sandboxed. They are kept unchanged on every write, as is anything else the API does not know.

Ids must belong to this project: ticket types (guestListTicketType, checkin.issuableTicketTypes: ticket types available in the backend), shift types, area types, areas, schedules. guestListTicketType also takes special_function_fields and is required while guestList is on and guestListNeedsPurchase is off. mwpIntroText takes HTML per language.

Optimistic lock on the settings' updated_at; settings never saved before have null. dry_run=true returns the settings as they would be saved and writes nothing. Every save is written to the change log.

Requires personandapplicationtype_administrate. Rate limited per user (api-v2-config-write).

Required API permission: “Change person and group type settings” (personandapplicationtype_administrate)

Example request:
curl --request PUT \
    "https://{instance}.festiwa.re/api/v2/projects/564/person-types/16/settings" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"portal\": {
        \"updateForm\": true,
        \"updateFormFrom\": \"2026-03-01 00:00:00\",
        \"updateFormTo\": null,
        \"updateFormLabel\": {
            \"de\": \"Daten ändern\",
            \"en\": \"Edit your data\"
        }
    },
    \"checkin\": {
        \"issuableTicketTypes\": [
            12,
            13
        ]
    },
    \"updated_at\": \"2026-10-08T09:00:00+00:00\",
    \"dry_run\": false
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/person-types/16/settings"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "portal": {
        "updateForm": true,
        "updateFormFrom": "2026-03-01 00:00:00",
        "updateFormTo": null,
        "updateFormLabel": {
            "de": "Daten ändern",
            "en": "Edit your data"
        }
    },
    "checkin": {
        "issuableTicketTypes": [
            12,
            13
        ]
    },
    "updated_at": "2026-10-08T09:00:00+00:00",
    "dry_run": false
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/person-types/16/settings';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'portal' => [
                'updateForm' => true,
                'updateFormFrom' => '2026-03-01 00:00:00',
                'updateFormTo' => null,
                'updateFormLabel' => [
                    'de' => 'Daten ändern',
                    'en' => 'Edit your data',
                ],
            ],
            'checkin' => [
                'issuableTicketTypes' => [
                    12,
                    13,
                ],
            ],
            'updated_at' => '2026-10-08T09:00:00+00:00',
            'dry_run' => false,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Saved):


{
    "data": {
        "type": {
            "id": 12,
            "shortname": "VolunteerPerson"
        },
        "project_id": 5,
        "portal": {
            "updateForm": true,
            "updateFormFrom": "2026-03-01 00:00:00",
            "updateFormTo": null
        },
        "checkin": {
            "issuableTicketTypes": [
                "21"
            ]
        },
        "updated_at": "2026-10-08T09:05:00+00:00"
    }
}
 

Example response (200, DryRun):


{
    "data": {
        "type": {
            "id": 12,
            "shortname": "VolunteerPerson"
        },
        "project_id": 5,
        "portal": {
            "updateForm": true
        },
        "checkin": {},
        "updated_at": "2026-10-08T09:00:00+00:00"
    },
    "dry_run": true
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (403, Other project):


{
    "error": {
        "code": "cross_project_access_denied",
        "message": "You do not have access to this project."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Example response (409, OptimisticLockFailed):


{
    "error": {
        "code": "optimistic_lock_failed",
        "message": "The resource was modified after your last read. Re-fetch and retry.",
        "errors": {
            "current": {
                "updated_at": "2026-10-08T09:05:00+00:00"
            }
        }
    }
}
 

Example response (422, Not settable):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "body": [
                "These settings cannot be changed through the API: portal.redirects."
            ]
        }
    }
}
 

Example response (429, TooManyRequests):


{
    "error": {
        "code": "too_many_requests",
        "message": "Too many requests."
    }
}
 

Request      

PUT api/v2/projects/{project_id}/person-types/{personType_id}/settings

PATCH api/v2/projects/{project_id}/person-types/{personType_id}/settings

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

personType_id   integer     

The ID of the personType. Example: 16

project   integer     

Project id. Example: 5

personType   integer     

Person type id. Example: 12

Body Parameters

portal   object  optional    

Required on PUT. Portal settings, keys as GET returns them (e.g. updateForm, updateFormFrom, updateFormLabel, eventsSettings.eventTypes). PUT replaces every key of the whitelist, PATCH only the sent ones. Not settable: redirects and the price list mail texts (code fields).

checkin   object  optional    

Person types only, required on PUT (may be empty). issuableTicketTypes: ids of ticket types of the project that staff may issue on the spot at the backend check-in.

updated_at   string  optional    

Optimistic lock: the updated_at of the settings you read. A newer stored version answers 409 optimistic_lock_failed. Settings that were never saved have updated_at: null; send null or leave it out. Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-10-08T09:00:00+00:00

dry_run   boolean  optional    

Validate only: returns the settings as they would be saved, writes nothing. Example: false

Advance many Persons in one request.

requires authentication

Required API permission: “Edit people and groups” (all_persons_and_applications_manage)

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/people/transitions/bulk" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --data "{
    \"ids\": [
        \"uuid-1\",
        \"uuid-2\"
    ],
    \"to_step_id\": 42,
    \"to_step_name\": \"APPROVED\",
    \"person_type\": \"volunteer\",
    \"workflow_id\": 5,
    \"note\": \"Approved.\",
    \"act_as_backend_creation\": false,
    \"dry_run\": false,
    \"force\": false
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/people/transitions/bulk"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

let body = {
    "ids": [
        "uuid-1",
        "uuid-2"
    ],
    "to_step_id": 42,
    "to_step_name": "APPROVED",
    "person_type": "volunteer",
    "workflow_id": 5,
    "note": "Approved.",
    "act_as_backend_creation": false,
    "dry_run": false,
    "force": false
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/people/transitions/bulk';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'json' => [
            'ids' => [
                'uuid-1',
                'uuid-2',
            ],
            'to_step_id' => 42,
            'to_step_name' => 'APPROVED',
            'person_type' => 'volunteer',
            'workflow_id' => 5,
            'note' => 'Approved.',
            'act_as_backend_creation' => false,
            'dry_run' => false,
            'force' => false,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, SyncBulk):


{
    "data": {
        "01a1e3a6-efbf-4413-9db1-f36e60489254": {
            "status": "success",
            "previous_step_id": 41,
            "current_step_id": 42,
            "triggers_fired": 3
        },
        "0298f01b-aa11-4d3c-bb22-cc33dd44ee55": {
            "status": "skipped",
            "reason": "already_in_step",
            "previous_step_id": 42
        }
    }
}
 

Example response (202, AsyncDispatched):


{
    "status": "dispatched",
    "count": 50
}
 

Example response (400, BulkValidationFailed):


{
    "error": {
        "code": "bulk_validation_failed",
        "message": "One or more transitions are not possible. Use force=true to process the eligible entries.",
        "failed_ids": [
            {
                "id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
                "reason": "already_in_step",
                "previous_step_id": 42
            },
            {
                "id": "0298f01b-aa11-4d3c-bb22-cc33dd44ee55",
                "reason": "person_not_found",
                "previous_step_id": null
            }
        ]
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "scope_missing",
        "message": "Token does not carry all_persons_and_applications_manage."
    }
}
 

Example response (403, TypeNotAllowed):


{
    "error": {
        "code": "type_not_allowed",
        "message": "This API access is restricted to certain person and group types; the person type “Crew” (crew) is not one of them. An admin changes this in festiware under Settings → … → “People sync” → Edit."
    }
}
 

Example response (422, InvalidPayload):


{
    "error": {
        "code": "invalid_payload",
        "message": "The given data was invalid.",
        "errors": {
            "ids": [
                "The ids field is required."
            ]
        }
    }
}
 

Request      

POST api/v2/projects/{project_id}/people/transitions/bulk

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Body Parameters

ids   string[]     

Array of Person UUIDs to transition.

to_step_id   integer  optional    

Target WorkflowStep id (one-of with to_step_name). Example: 42

to_step_name   string  optional    

Target WorkflowStep shortname (one-of with to_step_id). Example: APPROVED

person_type   string  optional    

PersonType shortname (one-of with workflow_id). Example: volunteer

workflow_id   integer  optional    

Workflow id (one-of with person_type; wins on collision). Example: 5

note   string  optional    

Optional audit note. Saved as a Comment on each transitioned Person. Example: Approved.

act_as_backend_creation   boolean  optional    

See single-endpoint docs. Default: false. Example: false

dry_run   boolean  optional    

If true, no DB writes and no triggers fire — the response reports per-id intended outcomes. Default: false. Example: false

force   boolean  optional    

If true, partial failures are graceful; if false, any failure aborts the batch with 400. Default: false. Example: false

Advance a single Person to a new workflow step.

requires authentication

Required API permission: “Edit people and groups” (all_persons_and_applications_manage)

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/people/architecto/transitions" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --data "{
    \"to_step_id\": 42,
    \"to_step_name\": \"APPROVED\",
    \"person_type\": \"volunteer\",
    \"workflow_id\": 5,
    \"note\": \"Approved via partner integration.\",
    \"act_as_backend_creation\": false,
    \"dry_run\": false
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/people/architecto/transitions"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

let body = {
    "to_step_id": 42,
    "to_step_name": "APPROVED",
    "person_type": "volunteer",
    "workflow_id": 5,
    "note": "Approved via partner integration.",
    "act_as_backend_creation": false,
    "dry_run": false
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/people/architecto/transitions';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'json' => [
            'to_step_id' => 42,
            'to_step_name' => 'APPROVED',
            'person_type' => 'volunteer',
            'workflow_id' => 5,
            'note' => 'Approved via partner integration.',
            'act_as_backend_creation' => false,
            'dry_run' => false,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Transitioned):


{
    "data": {
        "person_id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
        "previous_workflow_step": {
            "id": 41,
            "shortname": "PENDING",
            "name": "Pending"
        },
        "current_workflow_step": {
            "id": 42,
            "shortname": "APPROVED",
            "name": "Approved",
            "entered_at": "2026-05-13T10:00:00+00:00"
        },
        "triggers_fired": 3,
        "note_saved": true
    }
}
 

Example response (200, DryRun):


{
    "data": {
        "person_id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
        "previous_workflow_step": {
            "id": 41,
            "shortname": "PENDING",
            "name": "Pending"
        },
        "current_workflow_step": {
            "id": 42,
            "shortname": "APPROVED",
            "name": "Approved",
            "entered_at": "2026-05-13T10:00:00+00:00"
        },
        "triggers_fired": 0,
        "note_saved": false,
        "dry_run": true
    }
}
 

Example response (400, AlreadyInStep):


{
    "error": {
        "code": "already_in_step",
        "message": "The target is already in workflow step APPROVED."
    }
}
 

Example response (400, StepNotInWorkflow):


{
    "error": {
        "code": "step_not_in_workflow",
        "message": "The target step does not belong to the identified workflow."
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "scope_missing",
        "message": "Token does not carry all_persons_and_applications_manage."
    }
}
 

Example response (403, TypeNotAllowed):


{
    "error": {
        "code": "type_not_allowed",
        "message": "This API access is restricted to certain person and group types; the person type “Crew” (crew) is not one of them. An admin changes this in festiware under Settings → … → “People sync” → Edit."
    }
}
 

Example response (404, PersonNotFound):


{
    "error": {
        "code": "person_not_found",
        "message": "Person not found in this project."
    }
}
 

Example response (404, WorkflowNotFound):


{
    "error": {
        "code": "workflow_not_found",
        "message": "Workflow could not be resolved from the supplied disambiguation."
    }
}
 

Example response (422, InvalidPayload):


{
    "error": {
        "code": "invalid_payload",
        "message": "One of `to_step_id` or `to_step_name` is required.",
        "errors": {
            "to_step": [
                "One of `to_step_id` or `to_step_name` is required."
            ]
        }
    }
}
 

Request      

POST api/v2/projects/{project_id}/people/{person_id}/transitions

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

person_id   string     

The ID of the person. Example: architecto

project   integer     

Project id. Example: 16

person   string     

Person UUID. Example: architecto

Body Parameters

to_step_id   integer  optional    

Target WorkflowStep id (one-of with to_step_name; wins on collision). Example: 42

to_step_name   string  optional    

Target WorkflowStep shortname, case-insensitive (one-of with to_step_id). Example: APPROVED

person_type   string  optional    

PersonType shortname (one-of with workflow_id). Example: volunteer

workflow_id   integer  optional    

Workflow id (one-of with person_type; wins on collision). Example: 5

note   string  optional    

Optional audit note saved as a Comment on the Person. Example: Approved via partner integration.

act_as_backend_creation   boolean  optional    

If true, triggers with skip_after_backend_creation=true do not fire. Default: false. CamelCase alias actAsBackendCreation accepted. Example: false

dry_run   boolean  optional    

If true, validate and report the intended outcome without writing to the DB and without firing triggers. Default: false. Example: false

Groups

Groups — the resource the festiware backend shows as Gruppen. For backwards compatibility the wire format keeps the historic application spelling and will not change: route segment applications, payload keys application_type / application_type_id / subordinated_applications, sideload flags withApplications / withSubordinatedApplications, and the permissions all_persons_and_applications_*. Read each of them as "group".

List group types.

requires authentication

Returns every group type defined on the instance, paginated. Global reference data; not project-scoped.

An API access restricted to certain person and group types (set on the API user in festiware) sees only its group types here; an access restricted to person types only gets an empty list.

Requires one of all_persons_and_applications_see, formdefinition_see or workflow_see (or a higher level of one of them): the permissions of the people and group, form and workflow endpoints that use these shortnames. Without any of them 403.

Required API permission: one of “Read people and groups” (all_persons_and_applications_see) or “Read forms” (formdefinition_see) or “Read workflows” (workflow_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/application-types?per_page=25&page=1&created_since=2026-06-01T00%3A00%3A00%2B00%3A00&updated_since=2026-06-01T00%3A00%3A00%2B00%3A00" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/application-types"
);

const params = {
    "per_page": "25",
    "page": "1",
    "created_since": "2026-06-01T00:00:00+00:00",
    "updated_since": "2026-06-01T00:00:00+00:00",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/application-types';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'page' => '1',
            'created_since' => '2026-06-01T00:00:00+00:00',
            'updated_since' => '2026-06-01T00:00:00+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": 12,
            "shortname": "band",
            "name": "Band",
            "description": null
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Without any of the three permissions):


{
    "error": {
        "code": "permission_denied",
        "message": "This API access lacks the API permission \"Read people and groups\" (all_persons_and_applications_see) or \"Read forms\" (formdefinition_see) or \"Read workflows\" (workflow_see). An admin grants it in festiware under Settings → All Settings → User Management → API Users → \"My integration\" → Edit."
    }
}
 

Request      

GET api/v2/application-types

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

page   integer  optional    

Page number (1-indexed). Example: 1

created_since   string  optional    

ISO 8601 timestamp with offset; only records created at or after it. Example: 2026-06-01T00:00:00+00:00

updated_since   string  optional    

ISO 8601 timestamp with offset; only records updated at or after it. Example: 2026-06-01T00:00:00+00:00

Show a group type.

requires authentication

The list fields plus the global settings of the group type: menu name, singular name, the member options and the read-only structural keys. These settings apply to every project of the instance; the per-project portal and check-in settings are on GET /api/v2/projects/{project}/application-types/{applicationType}/settings.

Requires personandapplicationtype_see (or personandapplicationtype_administrate), the permission of the type settings in the backend. An API access restricted to certain person and group types gets 403 type_not_allowed for any other type.

Rate limited per user (api-v2-config-read).

Required API permission: “Read person and group type settings” (personandapplicationtype_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/application-types/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/application-types/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/application-types/16';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": 12,
        "shortname": "BandApplication",
        "name": "Volunteers",
        "description": null,
        "menu_name": "Crew",
        "name_singular": "Volunteer",
        "requires_owner": true,
        "role_required": false,
        "role_multiple": false,
        "show_sorting_field": false,
        "members_index_display_count": null,
        "extends": null,
        "is_default_resource": false,
        "creates": null,
        "shows": null,
        "permission_key": "volunteer",
        "created_at": "2026-01-10T09:00:00+00:00",
        "updated_at": "2026-10-08T09:00:00+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Example response (429, TooManyRequests):


{
    "error": {
        "code": "too_many_requests",
        "message": "Too many requests."
    }
}
 

Request      

GET api/v2/application-types/{applicationType_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

applicationType_id   integer     

The ID of the applicationType. Example: 16

applicationType   integer     

Group type id. Example: 12

Update a group type.

requires authentication

Instance-wide: the type and its settings are shared by every project of the instance; a change here applies to all of them.

PUT and PATCH both route here. PUT is a full replace: it requires name and resets every other settable key it leaves out (to null, read back as the default); PATCH keeps what it omits. Settable: name, description, menu_name, name_singular, requires_owner, role_required, role_multiple, show_sorting_field, members_index_display_count. shortname is immutable (send it unchanged or not at all); id, extends, is_default_resource, creates, shows, permission_key and created_at are read-only and answer 422 when sent, as does any unknown key. Relations (form definition, workflow steps, PDF templates, permissions) are managed elsewhere.

Side effect: renaming the type renames its generated roles ("{name} Supervisor", "{name} Manager", "{name} Observer"). The response lists them in side_effects.roles_renamed; with dry_run=true it lists the expected renames and saves nothing, fires no triggers and writes no change log.

Every save is written to the change log (who, when, before/after), like an edit in the backend.

Requires personandapplicationtype_administrate. A type outside the API access's type restriction answers 403 type_not_allowed. An API access limited to certain projects answers 403 cross_project_access_denied: the change would reach projects outside its list. Access checks run before validation. Rate limited per user (api-v2-config-write).

Required API permission: “Change person and group type settings” (personandapplicationtype_administrate)

Example request:
curl --request PUT \
    "https://{instance}.festiwa.re/api/v2/application-types/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Volunteers\",
    \"description\": \"Crew working shifts on site\",
    \"menu_name\": \"Volunteers\",
    \"name_singular\": \"Volunteer\",
    \"shortname\": \"VolunteerPerson\",
    \"updated_at\": \"2026-10-08T09:00:00+00:00\",
    \"dry_run\": false,
    \"requires_owner\": true,
    \"role_required\": false,
    \"role_multiple\": false,
    \"show_sorting_field\": false,
    \"members_index_display_count\": 5
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/application-types/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "Volunteers",
    "description": "Crew working shifts on site",
    "menu_name": "Volunteers",
    "name_singular": "Volunteer",
    "shortname": "VolunteerPerson",
    "updated_at": "2026-10-08T09:00:00+00:00",
    "dry_run": false,
    "requires_owner": true,
    "role_required": false,
    "role_multiple": false,
    "show_sorting_field": false,
    "members_index_display_count": 5
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/application-types/16';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'name' => 'Volunteers',
            'description' => 'Crew working shifts on site',
            'menu_name' => 'Volunteers',
            'name_singular' => 'Volunteer',
            'shortname' => 'VolunteerPerson',
            'updated_at' => '2026-10-08T09:00:00+00:00',
            'dry_run' => false,
            'requires_owner' => true,
            'role_required' => false,
            'role_multiple' => false,
            'show_sorting_field' => false,
            'members_index_display_count' => 5,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Saved):


{
    "data": {
        "id": 12,
        "shortname": "BandApplication",
        "name": "Helpers",
        "description": null,
        "menu_name": "Crew",
        "name_singular": "Helper",
        "requires_owner": true,
        "role_required": false,
        "role_multiple": false,
        "show_sorting_field": false,
        "members_index_display_count": null,
        "extends": null,
        "is_default_resource": false,
        "creates": null,
        "shows": null,
        "permission_key": "volunteer",
        "created_at": "2026-01-10T09:00:00+00:00",
        "updated_at": "2026-10-08T09:05:00+00:00"
    },
    "side_effects": {
        "roles_renamed": [
            {
                "from": "Volunteers Supervisor",
                "to": "Helpers Supervisor"
            },
            {
                "from": "Volunteers Manager",
                "to": "Helpers Manager"
            },
            {
                "from": "Volunteers Observer",
                "to": "Helpers Observer"
            }
        ]
    }
}
 

Example response (200, DryRun):


{
    "data": {
        "dry_run": true,
        "would_save": true,
        "changes": [
            "name"
        ]
    },
    "side_effects": {
        "roles_renamed": [
            {
                "from": "Volunteers Supervisor",
                "to": "Helpers Supervisor"
            }
        ]
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (403, Project-restricted access):


{
    "error": {
        "code": "cross_project_access_denied",
        "message": "A person or group type is shared by every project of the instance. This API access is limited to certain projects, so it cannot change the type itself; its project settings are on /api/v2/projects/{project}/…/settings."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Example response (409, OptimisticLockFailed):


{
    "error": {
        "code": "optimistic_lock_failed",
        "message": "The resource was modified after your last read. Re-fetch and retry.",
        "errors": {
            "current": {
                "updated_at": "2026-10-08T09:05:00+00:00"
            }
        }
    }
}
 

Example response (422, Invalid):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "shortname": [
                "The shortname of a type cannot be changed."
            ]
        }
    }
}
 

Example response (429, TooManyRequests):


{
    "error": {
        "code": "too_many_requests",
        "message": "Too many requests."
    }
}
 

Request      

PUT api/v2/application-types/{applicationType_id}

PATCH api/v2/application-types/{applicationType_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

applicationType_id   integer     

The ID of the applicationType. Example: 16

applicationType   integer     

Group type id. Example: 12

Body Parameters

name   string     

Required on PUT (PUT is a full replace: every other settable key left out is reset to its default). Plural name (max 36), unique among the person (or group) types. Renaming also renames the type's generated roles ("{name} Supervisor|Manager|Observer"); the response lists them in side_effects.roles_renamed. Must not be greater than 36 characters. Example: Volunteers

description   string  optional    

Internal description. Example: Crew working shifts on site

menu_name   string  optional    

Name in the backend menu (max 36). null falls back to the type name. Must not be greater than 36 characters. Example: Volunteers

name_singular   string  optional    

Singular name (max 36). Must not be greater than 36 characters. Example: Volunteer

shortname   string  optional    

Immutable. May be sent back unchanged; a different value answers 422. Example: VolunteerPerson

updated_at   string     

Optimistic lock: the updated_at you read. A newer stored version answers 409 optimistic_lock_failed. Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-10-08T09:00:00+00:00

dry_run   boolean  optional    

Validate only: returns what would change and the side effects (side_effects.roles_renamed), writes nothing and fires nothing. Example: false

requires_owner   boolean  optional    

Group types only: the group form needs a contact person (default true). Example: true

role_required   boolean  optional    

Group types only: a member needs a role. Example: false

role_multiple   boolean  optional    

Group types only: a member may have several roles. Example: false

show_sorting_field   boolean  optional    

Group types only: show the sorting field of the members. Example: false

members_index_display_count   integer  optional    

Group types only: how many members the group list shows (0–1000, null = default). Must be at least 0. Must not be greater than 1000. Example: 5

id   string  optional    
extends   string  optional    
is_default_resource   string  optional    
creates   string  optional    
shows   string  optional    
permission_key   string  optional    
created_at   string  optional    

Paginated list of Groups in a project.

requires authentication

Every Group also carries an always-on related block (no flag needed): ID-only arrays of linked resources — events, teams, ticket_types, subordinated_applications, contracts — for follow-up requests. owner and members are omitted from related as they are already top-level (person_id, members[]).

List rows carry no calculated_data unless withCalculatedData=1 is passed.

Required API permission: “Read people and groups” (all_persons_and_applications_see)

Depending on the permission: form fields marked as protected are returned in plain text only with “Read protected fields” (securedata_see) as a direct API permission of the API user (a role does not count); without it their keys are left out of data and calculated_data, also of nested people and groups, and a nested person's name or e-mail or a group's name is null.

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/applications?application_type=volunteer&person_id=01a1e3a6-efbf-4413-9db1-f36e60489254&step=applied&updated_since=2026-05-07T00%3A00%3A00%2B00%3A00&per_page=25&withOwner=&withMembersCollection=&withSubordinatedApplications=&withJourney=&withEvents=&withEventAttendees=&withTickets=&withTranslatedValues=de&withCalculatedData=1&calculatedFields=stage%2Cshow_day%2Cshow_time&withContracts=&created_since=2026-06-01T00%3A00%3A00%2B00%3A00" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"per_page\": 16,
    \"application_type\": \"architecto\",
    \"person_id\": \"a4855dc5-0acb-33c3-b921-f4291f719ca0\",
    \"step\": \"architecto\",
    \"updated_since\": \"2026-11-19T01:25:40+01:00\",
    \"withOwner\": true,
    \"withMembersCollection\": true,
    \"withSubordinatedApplications\": false,
    \"withJourney\": true,
    \"withEvents\": true,
    \"withEventAttendees\": true,
    \"withTickets\": false,
    \"withCalculatedData\": true,
    \"withContracts\": true,
    \"calculatedFields\": [
        \"architecto\"
    ],
    \"withTranslatedValues\": \"architecto\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/applications"
);

const params = {
    "application_type": "volunteer",
    "person_id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
    "step": "applied",
    "updated_since": "2026-05-07T00:00:00+00:00",
    "per_page": "25",
    "withOwner": "0",
    "withMembersCollection": "0",
    "withSubordinatedApplications": "0",
    "withJourney": "0",
    "withEvents": "0",
    "withEventAttendees": "0",
    "withTickets": "0",
    "withTranslatedValues": "de",
    "withCalculatedData": "1",
    "calculatedFields": "stage,show_day,show_time",
    "withContracts": "0",
    "created_since": "2026-06-01T00:00:00+00:00",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "per_page": 16,
    "application_type": "architecto",
    "person_id": "a4855dc5-0acb-33c3-b921-f4291f719ca0",
    "step": "architecto",
    "updated_since": "2026-11-19T01:25:40+01:00",
    "withOwner": true,
    "withMembersCollection": true,
    "withSubordinatedApplications": false,
    "withJourney": true,
    "withEvents": true,
    "withEventAttendees": true,
    "withTickets": false,
    "withCalculatedData": true,
    "withContracts": true,
    "calculatedFields": [
        "architecto"
    ],
    "withTranslatedValues": "architecto"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/applications';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'application_type' => 'volunteer',
            'person_id' => '01a1e3a6-efbf-4413-9db1-f36e60489254',
            'step' => 'applied',
            'updated_since' => '2026-05-07T00:00:00+00:00',
            'per_page' => '25',
            'withOwner' => '0',
            'withMembersCollection' => '0',
            'withSubordinatedApplications' => '0',
            'withJourney' => '0',
            'withEvents' => '0',
            'withEventAttendees' => '0',
            'withTickets' => '0',
            'withTranslatedValues' => 'de',
            'withCalculatedData' => '1',
            'calculatedFields' => 'stage,show_day,show_time',
            'withContracts' => '0',
            'created_since' => '2026-06-01T00:00:00+00:00',
        ],
        'json' => [
            'per_page' => 16,
            'application_type' => 'architecto',
            'person_id' => 'a4855dc5-0acb-33c3-b921-f4291f719ca0',
            'step' => 'architecto',
            'updated_since' => '2026-11-19T01:25:40+01:00',
            'withOwner' => true,
            'withMembersCollection' => true,
            'withSubordinatedApplications' => false,
            'withJourney' => true,
            'withEvents' => true,
            'withEventAttendees' => true,
            'withTickets' => false,
            'withCalculatedData' => true,
            'withContracts' => true,
            'calculatedFields' => [
                'architecto',
            ],
            'withTranslatedValues' => 'architecto',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
            "project_id": 1,
            "application_type_id": 3,
            "application_type": {
                "id": 3,
                "shortname": "volunteer"
            },
            "person_id": null,
            "members": [],
            "current_step": {
                "id": 42,
                "shortname": "APPROVED"
            },
            "data": {
                "shirt_size": "M"
            },
            "created_at": "2026-05-07T11:24:53+00:00",
            "updated_at": "2026-05-07T11:24:53+00:00",
            "anonymized_at": null,
            "deactivated_at": null,
            "deleted_at": null,
            "related": {
                "events": [
                    881
                ],
                "teams": [
                    405
                ],
                "ticket_types": [],
                "subordinated_applications": [],
                "contracts": []
            }
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (200, withCalculatedData=1&calculatedFields=stage,show_time):


{
    "data": [
        {
            "id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
            "project_id": 1,
            "application_type_id": 3,
            "application_type": {
                "id": 3,
                "shortname": "artist"
            },
            "person_id": null,
            "members": [],
            "current_step": {
                "id": 42,
                "shortname": "CONFIRMED"
            },
            "data": {
                "name": "Night Owls"
            },
            "created_at": "2026-05-07T11:24:53+00:00",
            "updated_at": "2026-05-07T11:24:53+00:00",
            "anonymized_at": null,
            "deactivated_at": null,
            "deleted_at": null,
            "calculated_data": {
                "stage": "Main Stage",
                "show_time": "22:30"
            },
            "related": {
                "events": [
                    881
                ],
                "teams": [],
                "ticket_types": [],
                "subordinated_applications": [],
                "contracts": []
            }
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (200, With contracts (?withContracts=1)):


{
    "data": [
        {
            "id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
            "project_id": 1,
            "application_type_id": 3,
            "application_type": {
                "id": 3,
                "shortname": "artist"
            },
            "person_id": null,
            "members": [],
            "current_step": {
                "id": 42,
                "shortname": "CONFIRMED"
            },
            "data": {
                "name": "Night Owls"
            },
            "created_at": "2026-05-07T11:24:53+00:00",
            "updated_at": "2026-05-07T11:24:53+00:00",
            "anonymized_at": null,
            "deactivated_at": null,
            "deleted_at": null,
            "related": {
                "events": [
                    881
                ],
                "teams": [],
                "ticket_types": [],
                "subordinated_applications": [],
                "contracts": [
                    326
                ]
            },
            "contracts": [
                {
                    "id": 326,
                    "contract_number": "V-2026-0042",
                    "status": "signed",
                    "contract_type": {
                        "id": 4,
                        "shortname": "ARTIST"
                    }
                }
            ]
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (403, TypeNotAllowed):


{
    "error": {
        "code": "type_not_allowed",
        "message": "This API access is restricted to certain person and group types; the group type “Vendor” (vendor) is not one of them. An admin changes this in festiware under Settings → … → “People sync” → Edit."
    }
}
 

Example response (422, Invalid query parameter):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "per_page": [
                "The per page must not be greater than 100."
            ]
        }
    }
}
 

Request      

GET api/v2/projects/{project_id}/applications

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Query Parameters

application_type   string  optional    

Optional ApplicationType shortname filter. Example: volunteer

person_id   string  optional    

Optional Person UUID filter. Example: 01a1e3a6-efbf-4413-9db1-f36e60489254

step   string  optional    

Optional current workflow step shortname filter (read-only — does not transition). Example: applied

updated_since   string  optional    

Optional ISO 8601 timestamp; returns Groups modified at or after this moment. Example: 2026-05-07T00:00:00+00:00

per_page   integer  optional    

Page size, clamped to 100. Example: 25

withOwner   boolean  optional    

Sideload: inline the owner as a nested PersonV2Resource at owner. Default false. Example: false

withMembersCollection   boolean  optional    

Sideload: replace the members[] UUID array with nested PersonV2Resources. Default false. Example: false

withSubordinatedApplications   boolean  optional    

Sideload: inline subordinated groups (depth 1) at subordinated_applications. Default false. Example: false

withJourney   boolean  optional    

Sideload: inline workflow step history at journey[]. Default false. Example: false

withEvents   boolean  optional    

Sideload: inline scheduler events at events[]; each event carries attendees[] as person UUIDs and applications[] as group IDs. Default false. Example: false

withEventAttendees   boolean  optional    

Sideload: only meaningful alongside withEvents=1. Replaces each event's attendees[] UUID array with PersonV2Resources. Default false. Example: false

withTickets   boolean  optional    

Sideload: inline ticket types at ticket_types[]. Default false. Example: false

withTranslatedValues   string  optional    

Translate data.* values via the group type's FormDefinition. Truthy non-locale values fall back to en. Example: de

withCalculatedData   boolean  optional    

Keep calculated_data on every list row (stored values, data-qualification rules applied as on the detail endpoint). Default false: list rows carry no calculated_data. Example: true

calculatedFields   string  optional    

Only meaningful alongside withCalculatedData=1. Comma list (calculatedFields=stage,show_time) or flat array (calculatedFields[]=stage&calculatedFields[]=show_time) of calculated field names to return; unknown names are ignored, a nested array or non-string entry is 422. Example: stage,show_day,show_time

withContracts   boolean  optional    

Sideload: the Group's contracts in this project at contracts[], each {id, contract_number, status, contract_type: {id, shortname}}. Requires contract_manage on this list (contract_see is enough on the single record); the key is omitted without it. Default false. Example: false

created_since   string  optional    

ISO 8601 timestamp with offset; only records created at or after it. Example: 2026-06-01T00:00:00+00:00

Body Parameters

per_page   integer  optional    

Must be at least 1. Example: 16

application_type   string  optional    

Example: architecto

person_id   string  optional    

Must be a valid UUID. Example: a4855dc5-0acb-33c3-b921-f4291f719ca0

step   string  optional    

Example: architecto

updated_since   string  optional    

Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-11-19T01:25:40+01:00

withOwner   boolean  optional    

Example: true

withMembersCollection   boolean  optional    

Example: true

withSubordinatedApplications   boolean  optional    

Example: false

withJourney   boolean  optional    

Example: true

withEvents   boolean  optional    

Example: true

withEventAttendees   boolean  optional    

Example: true

withTickets   boolean  optional    

Example: false

withCalculatedData   boolean  optional    

Example: true

withContracts   boolean  optional    

Example: true

calculatedFields   string[]  optional    
withTranslatedValues   string  optional    

Example: architecto

Create a new Group in a project.

requires authentication

Required API permission: “Create and delete people and groups” (all_persons_and_applications_administrate)

Depending on the permission: form fields marked as protected are returned in plain text only with “Read protected fields” (securedata_see) as a direct API permission of the API user (a role does not count); without it their keys are left out of data and calculated_data, also of nested people and groups, and a nested person's name or e-mail or a group's name is null.

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/applications" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --data "{
    \"application_type\": \"volunteer\",
    \"person_id\": \"01a1e3a6-efbf-4413-9db1-f36e60489254\",
    \"data\": {
        \"shirt_size\": \"M\",
        \"dietary_pref\": \"vegan\"
    }
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/applications"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

let body = {
    "application_type": "volunteer",
    "person_id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
    "data": {
        "shirt_size": "M",
        "dietary_pref": "vegan"
    }
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/applications';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'json' => [
            'application_type' => 'volunteer',
            'person_id' => '01a1e3a6-efbf-4413-9db1-f36e60489254',
            'data' => [
                'shirt_size' => 'M',
                'dietary_pref' => 'vegan',
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201, Created):


{
    "data": {
        "id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
        "project_id": 1,
        "application_type_id": 3,
        "application_type": {
            "id": 3,
            "shortname": "volunteer"
        },
        "person_id": null,
        "members": [],
        "current_step": {
            "id": 40,
            "shortname": "PENDING"
        },
        "data": {
            "shirt_size": "M",
            "dietary_pref": "vegan"
        },
        "calculated_data": {},
        "created_at": "2026-05-07T11:24:53+00:00",
        "updated_at": "2026-05-07T11:24:53+00:00",
        "anonymized_at": null,
        "deactivated_at": null,
        "deleted_at": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (403, TypeNotAllowed):


{
    "error": {
        "code": "type_not_allowed",
        "message": "This API access is restricted to certain person and group types; the group type “Vendor” (vendor) is not one of them. An admin changes this in festiware under Settings → … → “People sync” → Edit."
    }
}
 

Example response (409, DuplicateId):


{
    "error": {
        "code": "duplicate",
        "message": "A Group with this id already exists."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "application_type": [
                "The application_type field is required."
            ],
            "data": [
                "The data field must be an array."
            ]
        }
    }
}
 

Example response (422, QuotaExceeded):


{
    "error": {
        "code": "validation_failed",
        "message": "Your package's \"Active people and groups\" allowance is used up (500 of 500). Contact festiware support to extend it.",
        "errors": {
            "name": [
                "Your package's \"Active people and groups\" allowance is used up (500 of 500). Contact festiware support to extend it."
            ]
        }
    }
}
 

Request      

POST api/v2/projects/{project_id}/applications

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Body Parameters

id   string  optional    
application_type   string     

ApplicationType shortname. Immutable post-create. Example: volunteer

person_id   string  optional    

Optional Person UUID for the owner. Example: 01a1e3a6-efbf-4413-9db1-f36e60489254

data   object     

Map of custom-data fields. Scalar values only.

Show a single Group by UUID.

requires authentication

Same sideload flags (withOwner, withMembersCollection, withJourney, withEvents, withEventAttendees, withTickets, withSubordinatedApplications, withTranslatedValues) are supported here as on the list endpoint.

Required API permission: “Read people and groups” (all_persons_and_applications_see)

Depending on the permission: form fields marked as protected are returned in plain text only with “Read protected fields” (securedata_see) as a direct API permission of the API user (a role does not count); without it their keys are left out of data and calculated_data, also of nested people and groups, and a nested person's name or e-mail or a group's name is null.

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/applications/16?withOwner=&withMembersCollection=&withJourney=&withEvents=&withEventAttendees=&withTickets=&withSubordinatedApplications=&withTranslatedValues=de&withContracts=" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/applications/16"
);

const params = {
    "withOwner": "0",
    "withMembersCollection": "0",
    "withJourney": "0",
    "withEvents": "0",
    "withEventAttendees": "0",
    "withTickets": "0",
    "withSubordinatedApplications": "0",
    "withTranslatedValues": "de",
    "withContracts": "0",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/applications/16';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'withOwner' => '0',
            'withMembersCollection' => '0',
            'withJourney' => '0',
            'withEvents' => '0',
            'withEventAttendees' => '0',
            'withTickets' => '0',
            'withSubordinatedApplications' => '0',
            'withTranslatedValues' => 'de',
            'withContracts' => '0',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
        "project_id": 1,
        "application_type_id": 3,
        "application_type": {
            "id": 3,
            "shortname": "volunteer"
        },
        "person_id": null,
        "members": [],
        "current_step": {
            "id": 42,
            "shortname": "APPROVED"
        },
        "data": {
            "shirt_size": "M"
        },
        "calculated_data": {},
        "created_at": "2026-05-07T11:24:53+00:00",
        "updated_at": "2026-05-07T11:24:53+00:00",
        "anonymized_at": null,
        "deactivated_at": null,
        "deleted_at": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/applications/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   integer     

The ID of the application. Example: 16

project   integer     

Project id. Example: 16

application   string     

Group UUID. Example: architecto

Query Parameters

withOwner   boolean  optional    

Sideload owner as nested PersonV2Resource. Default false. Example: false

withMembersCollection   boolean  optional    

Sideload members as nested PersonV2Resources. Default false. Example: false

withJourney   boolean  optional    

Sideload workflow step history. Default false. Example: false

withEvents   boolean  optional    

Sideload scheduler events; each event carries attendees[] as person UUIDs and applications[] as group IDs. Default false. Example: false

withEventAttendees   boolean  optional    

Replace event attendees[] UUIDs with PersonV2Resources. Default false. Example: false

withTickets   boolean  optional    

Sideload ticket types. Default false. Example: false

withSubordinatedApplications   boolean  optional    

Sideload subordinated groups (depth 1). Default false. Example: false

withTranslatedValues   string  optional    

Translate data.* via FormDefinition. Example: de

withContracts   boolean  optional    

Sideload: the Group's contracts in this project at contracts[], each {id, contract_number, status, contract_type: {id, shortname}}. Requires contract_see; the key is omitted without it. Default false. Example: false

Update a Group (PUT = full replace, PATCH = sparse merge).

requires authentication

Both PUT and PATCH route here; replaceMissing is derived from the HTTP method. applicationType (immutable) and step_id / workflow_step_id (transitions belong to a separate endpoint) are rejected if present in the body. members[] writes return 422 — manage members in the festiware backend or via v1.

Required API permission: “Edit people and groups” (all_persons_and_applications_manage)

Depending on the permission: form fields marked as protected are returned in plain text only with “Read protected fields” (securedata_see) as a direct API permission of the API user (a role does not count); without it their keys are left out of data and calculated_data. A protected field you cannot read keeps the value already stored: sending it fills an empty field but never changes or clears a stored value (also not by a PUT that leaves it out), and warnings names it.

Example request:
curl --request PUT \
    "https://{instance}.festiwa.re/api/v2/projects/564/applications/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"data\": [],
    \"updated_at\": \"2026-05-07T11:24:53+00:00\",
    \"person_id\": \"architecto\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/applications/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "data": [],
    "updated_at": "2026-05-07T11:24:53+00:00",
    "person_id": "architecto"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/applications/16';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'data' => [],
            'updated_at' => '2026-05-07T11:24:53+00:00',
            'person_id' => 'architecto',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
        "project_id": 1,
        "application_type_id": 3,
        "application_type": {
            "id": 3,
            "shortname": "volunteer"
        },
        "person_id": null,
        "members": [],
        "current_step": {
            "id": 42,
            "shortname": "APPROVED"
        },
        "data": {
            "shirt_size": "L"
        },
        "calculated_data": {},
        "created_at": "2026-05-07T11:24:53+00:00",
        "updated_at": "2026-05-07T12:00:00+00:00",
        "anonymized_at": null,
        "deactivated_at": null,
        "deleted_at": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Example response (409, OptimisticLockFailed):


{
    "error": {
        "code": "optimistic_lock_failed",
        "message": "The Group was modified by someone else; reload and retry.",
        "errors": {
            "current": {
                "updated_at": "2026-05-07T11:24:53+00:00"
            }
        }
    }
}
 

Example response (422, GroupTypeImmutable):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "application_type": [
                "The application_type cannot be changed once set."
            ]
        }
    }
}
 

Example response (422, QuotaExceeded):


{
    "error": {
        "code": "validation_failed",
        "message": "Your package's \"Active people and groups\" allowance is used up (500 of 500). Contact festiware support to extend it.",
        "errors": {
            "person_id": [
                "Your package's \"Active people and groups\" allowance is used up (500 of 500). Contact festiware support to extend it."
            ]
        }
    }
}
 

Request      

PUT api/v2/projects/{project_id}/applications/{id}

PATCH api/v2/projects/{project_id}/applications/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   integer     

The ID of the application. Example: 16

project   integer     

Project id. Example: 16

application   string     

Group UUID. Example: architecto

Body Parameters

data   object     

Map of custom-data fields (scalar values only).

updated_at   string     

ISO 8601 timestamp of the last known version (optimistic-lock token). Example: 2026-05-07T11:24:53+00:00

person_id   string  optional    

Optional owner Person UUID. Pass null to clear. Example: architecto

application_type   string  optional    
application_type_id   string  optional    
step_id   string  optional    
workflow_step_id   string  optional    

Soft-delete a Group.

requires authentication

Requires explicit confirm: true. Missing/false confirmation returns 422 and the Group remains intact. Soft-deleted Groups return 404 from all subsequent v2 endpoints.

Required API permission: “Create and delete people and groups” (all_persons_and_applications_administrate)

Example request:
curl --request DELETE \
    "https://{instance}.festiwa.re/api/v2/projects/564/applications/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"confirm\": true
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/applications/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "confirm": true
};

fetch(url, {
    method: "DELETE",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/applications/16';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'confirm' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (204, SoftDeleted):

Empty response
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "confirm": [
                "The confirm field must be accepted."
            ]
        }
    }
}
 

Request      

DELETE api/v2/projects/{project_id}/applications/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   integer     

The ID of the application. Example: 16

project   integer     

Project id. Example: 16

application   string     

Group UUID. Example: architecto

Body Parameters

confirm   boolean     

Must be exactly true to confirm deletion. Example: true

Show the project settings of a group type.

requires authentication

The participant portal settings (portal) of the group type in this project (group types have no check-in settings). Keys are the stored ones, as the backend form names them: per portal module <module> (on/off), <module>From, <module>To (publication window) plus its own options (e.g. membersCanEdit, eventsSettings.eventTypes). Only the modules available on the instance appear. Lists of ids come back as stored (strings).

Not returned: the redirects and the price list mail texts (they hold code, see the update endpoint).

A type without stored settings in the project returns empty sections and updated_at: null.

Requires personandapplicationtype_see (or personandapplicationtype_administrate). A type outside the API access's type restriction answers 403 type_not_allowed. Rate limited per user (api-v2-config-read).

Required API permission: “Read person and group type settings” (personandapplicationtype_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/application-types/16/settings" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/application-types/16/settings"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/application-types/16/settings';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "type": {
            "id": 12,
            "shortname": "BandApplication"
        },
        "project_id": 5,
        "portal": {
            "updateForm": true,
            "updateFormFrom": "2026-03-01 00:00:00",
            "updateFormTo": null,
            "updateFormLabel": {
                "de": "Daten ändern",
                "en": "Edit your data"
            },
            "membersCanEdit": true,
            "eventsSettings": {
                "eventTypes": [
                    "3",
                    "4"
                ],
                "hideAssignedEvents": false
            }
        },
        "updated_at": "2026-10-08T09:00:00+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (403, Other project):


{
    "error": {
        "code": "cross_project_access_denied",
        "message": "You do not have access to this project."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Example response (429, TooManyRequests):


{
    "error": {
        "code": "too_many_requests",
        "message": "Too many requests."
    }
}
 

Request      

GET api/v2/projects/{project_id}/application-types/{applicationType_id}/settings

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

applicationType_id   integer     

The ID of the applicationType. Example: 16

project   integer     

Project id. Example: 5

applicationType   integer     

Group type id. Example: 12

Update the project settings of a group type.

requires authentication

Changes the portal settings of the group type in this project only.

PUT replaces every settable key of portal — a settable key left out is removed — and requires portal; PATCH sets only the keys it sends. Keys are the ones GET returns. A key that is unknown, belongs to a module not available on the instance, or is not settable answers 422 and nothing is saved.

Not settable (code fields): redirects (its condition is a Twig expression) and the price list mail texts are executed on the server and stay closed to the API until templates run sandboxed. They are kept unchanged on every write, as is anything else the API does not know.

Ids must belong to this project (shift types, area types).

Optimistic lock on the settings' updated_at; settings never saved before have null. dry_run=true returns the settings as they would be saved and writes nothing. Every save is written to the change log.

Requires personandapplicationtype_administrate. Rate limited per user (api-v2-config-write).

Required API permission: “Change person and group type settings” (personandapplicationtype_administrate)

Example request:
curl --request PUT \
    "https://{instance}.festiwa.re/api/v2/projects/564/application-types/16/settings" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"portal\": {
        \"updateForm\": true,
        \"updateFormFrom\": \"2026-03-01 00:00:00\",
        \"updateFormTo\": null,
        \"updateFormLabel\": {
            \"de\": \"Daten ändern\",
            \"en\": \"Edit your data\"
        }
    },
    \"checkin\": {
        \"issuableTicketTypes\": [
            12,
            13
        ]
    },
    \"updated_at\": \"2026-10-08T09:00:00+00:00\",
    \"dry_run\": false
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/application-types/16/settings"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "portal": {
        "updateForm": true,
        "updateFormFrom": "2026-03-01 00:00:00",
        "updateFormTo": null,
        "updateFormLabel": {
            "de": "Daten ändern",
            "en": "Edit your data"
        }
    },
    "checkin": {
        "issuableTicketTypes": [
            12,
            13
        ]
    },
    "updated_at": "2026-10-08T09:00:00+00:00",
    "dry_run": false
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/application-types/16/settings';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'portal' => [
                'updateForm' => true,
                'updateFormFrom' => '2026-03-01 00:00:00',
                'updateFormTo' => null,
                'updateFormLabel' => [
                    'de' => 'Daten ändern',
                    'en' => 'Edit your data',
                ],
            ],
            'checkin' => [
                'issuableTicketTypes' => [
                    12,
                    13,
                ],
            ],
            'updated_at' => '2026-10-08T09:00:00+00:00',
            'dry_run' => false,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Saved):


{
    "data": {
        "type": {
            "id": 12,
            "shortname": "BandApplication"
        },
        "project_id": 5,
        "portal": {
            "updateForm": true,
            "updateFormFrom": "2026-03-01 00:00:00",
            "updateFormTo": null
        },
        "updated_at": "2026-10-08T09:05:00+00:00"
    }
}
 

Example response (200, DryRun):


{
    "data": {
        "type": {
            "id": 12,
            "shortname": "BandApplication"
        },
        "project_id": 5,
        "portal": {
            "updateForm": true
        },
        "updated_at": "2026-10-08T09:00:00+00:00"
    },
    "dry_run": true
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (403, Other project):


{
    "error": {
        "code": "cross_project_access_denied",
        "message": "You do not have access to this project."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Example response (409, OptimisticLockFailed):


{
    "error": {
        "code": "optimistic_lock_failed",
        "message": "The resource was modified after your last read. Re-fetch and retry.",
        "errors": {
            "current": {
                "updated_at": "2026-10-08T09:05:00+00:00"
            }
        }
    }
}
 

Example response (422, Not settable):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "body": [
                "These settings cannot be changed through the API: portal.redirects."
            ]
        }
    }
}
 

Example response (429, TooManyRequests):


{
    "error": {
        "code": "too_many_requests",
        "message": "Too many requests."
    }
}
 

Request      

PUT api/v2/projects/{project_id}/application-types/{applicationType_id}/settings

PATCH api/v2/projects/{project_id}/application-types/{applicationType_id}/settings

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

applicationType_id   integer     

The ID of the applicationType. Example: 16

project   integer     

Project id. Example: 5

applicationType   integer     

Group type id. Example: 12

Body Parameters

portal   object  optional    

Required on PUT. Portal settings, keys as GET returns them (e.g. updateForm, updateFormFrom, updateFormLabel, eventsSettings.eventTypes). PUT replaces every key of the whitelist, PATCH only the sent ones. Not settable: redirects and the price list mail texts (code fields).

checkin   object  optional    

Person types only, required on PUT (may be empty). issuableTicketTypes: ids of ticket types of the project that staff may issue on the spot at the backend check-in.

updated_at   string  optional    

Optimistic lock: the updated_at of the settings you read. A newer stored version answers 409 optimistic_lock_failed. Settings that were never saved have updated_at: null; send null or leave it out. Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-10-08T09:00:00+00:00

dry_run   boolean  optional    

Validate only: returns the settings as they would be saved, writes nothing. Example: false

Advance many Groups in one request.

requires authentication

Bulk dry_run ABOVE the sync threshold returns 400 dry_run_async_unsupported — the preview cannot be produced asynchronously.

Required API permission: “Edit people and groups” (all_persons_and_applications_manage)

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/applications/transitions/bulk" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --data "{
    \"ids\": [
        4711,
        4712
    ],
    \"to_step_id\": 42,
    \"to_step_name\": \"APPROVED\",
    \"application_type\": \"vendor\",
    \"workflow_id\": 5,
    \"note\": \"Approved.\",
    \"act_as_backend_creation\": false,
    \"dry_run\": false,
    \"force\": false
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/applications/transitions/bulk"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

let body = {
    "ids": [
        4711,
        4712
    ],
    "to_step_id": 42,
    "to_step_name": "APPROVED",
    "application_type": "vendor",
    "workflow_id": 5,
    "note": "Approved.",
    "act_as_backend_creation": false,
    "dry_run": false,
    "force": false
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/applications/transitions/bulk';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'json' => [
            'ids' => [
                4711,
                4712,
            ],
            'to_step_id' => 42,
            'to_step_name' => 'APPROVED',
            'application_type' => 'vendor',
            'workflow_id' => 5,
            'note' => 'Approved.',
            'act_as_backend_creation' => false,
            'dry_run' => false,
            'force' => false,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, SyncBulk):


{
    "data": {
        "4711": {
            "status": "success",
            "previous_step_id": 41,
            "current_step_id": 42,
            "triggers_fired": 3
        },
        "4712": {
            "status": "skipped",
            "reason": "already_in_step",
            "previous_step_id": 42
        }
    }
}
 

Example response (202, AsyncDispatched):


{
    "status": "dispatched",
    "count": 50
}
 

Example response (400, BulkValidationFailed):


{
    "error": {
        "code": "bulk_validation_failed",
        "message": "One or more transitions are not possible. Use force=true to process the eligible entries.",
        "failed_ids": [
            {
                "id": 4712,
                "reason": "already_in_step",
                "previous_step_id": 42
            },
            {
                "id": 4713,
                "reason": "application_not_found",
                "previous_step_id": null
            }
        ]
    }
}
 

Example response (400, DryRunAsyncUnsupported):


{
    "error": {
        "code": "dry_run_async_unsupported",
        "message": "Bulk dry_run is not supported for batches above the sync threshold."
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (403, TypeNotAllowed):


{
    "error": {
        "code": "type_not_allowed",
        "message": "This API access is restricted to certain person and group types; the group type “Vendor” (vendor) is not one of them. An admin changes this in festiware under Settings → … → “People sync” → Edit."
    }
}
 

Example response (422, InvalidPayload):


{
    "error": {
        "code": "invalid_payload",
        "message": "The given data was invalid.",
        "errors": {
            "ids": [
                "The ids field is required."
            ]
        }
    }
}
 

Request      

POST api/v2/projects/{project_id}/applications/transitions/bulk

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Body Parameters

ids   integer[]     

Array of Group ids to transition.

to_step_id   integer  optional    

Target WorkflowStep id (one-of with to_step_name). Example: 42

to_step_name   string  optional    

Target WorkflowStep shortname (one-of with to_step_id). Example: APPROVED

application_type   string  optional    

ApplicationType shortname (one-of with workflow_id). Example: vendor

workflow_id   integer  optional    

Workflow id (one-of with application_type; wins on collision). Example: 5

note   string  optional    

Optional audit note. Saved as a Comment on each transitioned Group. Example: Approved.

act_as_backend_creation   boolean  optional    

See single-endpoint docs. Default: false. Example: false

dry_run   boolean  optional    

If true, no DB writes and no triggers fire — the response reports per-id intended outcomes. Default: false. Example: false

force   boolean  optional    

If true, partial failures are graceful; if false, any failure aborts the batch with 400. Default: false. Example: false

Advance a single Group to a new workflow step.

requires authentication

Required API permission: “Edit people and groups” (all_persons_and_applications_manage)

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/applications/16/transitions" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --data "{
    \"to_step_id\": 42,
    \"to_step_name\": \"APPROVED\",
    \"application_type\": \"vendor\",
    \"workflow_id\": 5,
    \"note\": \"Approved via partner integration.\",
    \"act_as_backend_creation\": false,
    \"dry_run\": false
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/applications/16/transitions"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

let body = {
    "to_step_id": 42,
    "to_step_name": "APPROVED",
    "application_type": "vendor",
    "workflow_id": 5,
    "note": "Approved via partner integration.",
    "act_as_backend_creation": false,
    "dry_run": false
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/applications/16/transitions';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'json' => [
            'to_step_id' => 42,
            'to_step_name' => 'APPROVED',
            'application_type' => 'vendor',
            'workflow_id' => 5,
            'note' => 'Approved via partner integration.',
            'act_as_backend_creation' => false,
            'dry_run' => false,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Transitioned):


{
    "data": {
        "application_id": 4711,
        "previous_workflow_step": {
            "id": 41,
            "shortname": "PENDING",
            "name": "Pending"
        },
        "current_workflow_step": {
            "id": 42,
            "shortname": "APPROVED",
            "name": "Approved",
            "entered_at": "2026-05-25T10:00:00+00:00"
        },
        "triggers_fired": 3,
        "note_saved": true
    }
}
 

Example response (200, DryRun):


{
    "data": {
        "application_id": 4711,
        "previous_workflow_step": {
            "id": 41,
            "shortname": "PENDING",
            "name": "Pending"
        },
        "current_workflow_step": {
            "id": 42,
            "shortname": "APPROVED",
            "name": "Approved",
            "entered_at": "2026-05-25T10:00:00+00:00"
        },
        "triggers_fired": 0,
        "note_saved": false,
        "dry_run": true
    }
}
 

Example response (400, AlreadyInStep):


{
    "error": {
        "code": "already_in_step",
        "message": "The target is already in workflow step APPROVED."
    }
}
 

Example response (400, StepNotInWorkflow):


{
    "error": {
        "code": "step_not_in_workflow",
        "message": "The target step does not belong to the identified workflow."
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (403, TypeNotAllowed):


{
    "error": {
        "code": "type_not_allowed",
        "message": "This API access is restricted to certain person and group types; the group type “Vendor” (vendor) is not one of them. An admin changes this in festiware under Settings → … → “People sync” → Edit."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (404, WorkflowNotFound):


{
    "error": {
        "code": "workflow_not_found",
        "message": "Workflow could not be resolved from the supplied disambiguation."
    }
}
 

Example response (422, InvalidPayload):


{
    "error": {
        "code": "invalid_payload",
        "message": "One of `to_step_id` or `to_step_name` is required.",
        "errors": {
            "to_step": [
                "One of `to_step_id` or `to_step_name` is required."
            ]
        }
    }
}
 

Request      

POST api/v2/projects/{project_id}/applications/{application_id}/transitions

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

application_id   integer     

The ID of the application. Example: 16

project   integer     

Project id. Example: 16

application   integer     

Group id. Example: 16

Body Parameters

to_step_id   integer  optional    

Target WorkflowStep id (one-of with to_step_name; wins on collision). Example: 42

to_step_name   string  optional    

Target WorkflowStep shortname, case-insensitive (one-of with to_step_id). Example: APPROVED

application_type   string  optional    

ApplicationType shortname (one-of with workflow_id). Example: vendor

workflow_id   integer  optional    

Workflow id (one-of with application_type; wins on collision). Example: 5

note   string  optional    

Optional audit note saved as a Comment on the Group. Example: Approved via partner integration.

act_as_backend_creation   boolean  optional    

If true, triggers with skip_after_backend_creation=true do not fire. Default: false. CamelCase alias actAsBackendCreation accepted. Example: false

dry_run   boolean  optional    

If true, validate and report the intended outcome without writing to the DB and without firing triggers. Default: false. Example: false

Form Attachments

Upload and clear the file/image fields of a Group or a Person.

Every other data.* field is written through the Group/Person update endpoints, but an upload field cannot be: its value is a stored path, and a JSON body carries no file. These endpoints take the file itself (multipart/form-data, one file per request) and write the resulting path into data.{field} for you.

The payload names neither a model type nor a type id — the URL says which record it is, and the record's own type(s) decide which form definition declares the field.

Download the file stored in a Group's form field.

requires authentication

Streams the file with its stored Content-Type and Content-Disposition: attachment. No signed or public URL is handed out: the file comes through this authenticated request.

404 when the field is unknown, is not a file/image field, is empty, or its file is gone, and when field-level access (data qualification) hides the field from you — the same fields the backend hides.

Required API permission: “Read people and groups” (all_persons_and_applications_see)

Depending on the permission: a form field marked as protected needs “Read protected fields” (securedata_see) as a direct API permission of the API user (a role does not count). Without it, downloading its file answers 404 and uploading or deleting one 422.

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/applications/16/files/passport_scan" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/applications/16/files/passport_scan"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/applications/16/files/passport_scan';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


[binary file content]
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NoFile):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/applications/{application_id}/files/{field}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

application_id   integer     

The ID of the application. Example: 16

field   string     

Name of the file/image field as declared in the group type's form definition. Example: passport_scan

project   integer     

Project id. Example: 1

application   string     

Group id. Example: 812

Download the file stored in a Person's form field.

requires authentication

Same behaviour as the Group download. The field counts as declared when any of the Person's types declares it.

Required API permission: “Read people and groups” (all_persons_and_applications_see)

Depending on the permission: a form field marked as protected needs “Read protected fields” (securedata_see) as a direct API permission of the API user (a role does not count). Without it, downloading its file answers 404 and uploading or deleting one 422.

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/people/architecto/files/photo" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/people/architecto/files/photo"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/people/architecto/files/photo';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


[binary file content]
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NoFile):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/people/{person_id}/files/{field}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

person_id   string     

The ID of the person. Example: architecto

field   string     

Name of the file/image field as declared in one of the person's types. Example: photo

project   integer     

Project id. Example: 1

person   string     

Person UUID. Example: 01a1e3a6-efbf-4413-9db1-f36e60489254

Upload a file into a Group's form field.

requires authentication

multipart/form-data, one file per request, part name file. Replaces whatever the field held before; the previously stored file is deleted once the new path is committed, unless another record still references it. Size and type are validated against the same limits the frontend forms use — image fields accept image formats only, file fields the instance's upload allowlist. HEIC/HEIF uploads are converted to JPEG before validation, as everywhere else.

Required API permission: “Edit people and groups” (all_persons_and_applications_manage)

Depending on the permission: a form field marked as protected needs “Read protected fields” (securedata_see) as a direct API permission of the API user (a role does not count). Without it, downloading its file answers 404 and uploading or deleting one 422.

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/applications/16/files/passport_scan" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --form "file=@/tmp/phpKoAy7Z" 
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/applications/16/files/passport_scan"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "multipart/form-data",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

const body = new FormData();
body.append('file', document.querySelector('input[name="file"]').files[0]);

fetch(url, {
    method: "POST",
    headers,
    body,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/applications/16/files/passport_scan';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'multipart/form-data',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'multipart' => [
            [
                'name' => 'file',
                'contents' => fopen('/tmp/phpKoAy7Z', 'r')
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
        "project_id": 1,
        "application_type_id": 3,
        "data": {
            "passport_scan": "form-attachments/01a1e3a6-efbf-4413-9db1-f36e60489254/8f14e45fceea167a5a36dedd4bea2543.jpg"
        },
        "created_at": "2026-05-07T11:24:53+00:00",
        "updated_at": "2026-05-07T12:00:00+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "message": "Unauthenticated."
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, UnknownFieldOrGroup):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (422, NotAnUploadField):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "field": [
                "The field 'shirt_size' does not take a file upload."
            ]
        }
    }
}
 

Example response (422, ProtectedByDataQualification):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "field": [
                "Field 'passport_scan': you may not upload or clear its file — your user holds data qualification 'Personal Data' read-only. Do not retry; this needs a user with write access to it."
            ]
        }
    }
}
 

Example response (422, FileRejected):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "file": [
                "The file is too large. A maximum of 20 MB is allowed."
            ]
        }
    }
}
 

Request      

POST api/v2/projects/{project_id}/applications/{application_id}/files/{field}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: multipart/form-data

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

application_id   integer     

The ID of the application. Example: 16

field   string     

Name of the file/image field as declared in the group type's form definition. Example: passport_scan

project   integer     

Project id. Example: 1

application   string     

Group UUID. Example: 01a1e3a6-efbf-4413-9db1-f36e60489254

Body Parameters

file   file     

The file to store. Example: /tmp/phpKoAy7Z

Clear a Group's file/image field.

requires authentication

Removes the field from data and deletes the stored file (kept if another record still references it). Clearing a field that is already empty is a no-op and still returns 200, so retries are safe.

Required API permission: “Edit people and groups” (all_persons_and_applications_manage)

Depending on the permission: a form field marked as protected needs “Read protected fields” (securedata_see) as a direct API permission of the API user (a role does not count). Without it, downloading its file answers 404 and uploading or deleting one 422.

Example request:
curl --request DELETE \
    "https://{instance}.festiwa.re/api/v2/projects/564/applications/16/files/passport_scan" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/applications/16/files/passport_scan"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/applications/16/files/passport_scan';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
        "project_id": 1,
        "application_type_id": 3,
        "data": {},
        "created_at": "2026-05-07T11:24:53+00:00",
        "updated_at": "2026-05-07T12:00:00+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "message": "Unauthenticated."
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, UnknownFieldOrGroup):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (422, NotAnUploadField):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "field": [
                "The field 'shirt_size' does not take a file upload."
            ]
        }
    }
}
 

Example response (422, ProtectedByDataQualification):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "field": [
                "Field 'passport_scan': you may not upload or clear its file — your user holds data qualification 'Personal Data' read-only. Do not retry; this needs a user with write access to it."
            ]
        }
    }
}
 

Request      

DELETE api/v2/projects/{project_id}/applications/{application_id}/files/{field}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

application_id   integer     

The ID of the application. Example: 16

field   string     

Name of the file/image field. Example: passport_scan

project   integer     

Project id. Example: 1

application   string     

Group UUID. Example: 01a1e3a6-efbf-4413-9db1-f36e60489254

Upload a file into a Person's form field.

requires authentication

Same contract as the Group endpoint. A Person carries several person types, each with its own form definition; the field is accepted when any of them declares it.

Required API permission: “Edit people and groups” (all_persons_and_applications_manage)

Depending on the permission: a form field marked as protected needs “Read protected fields” (securedata_see) as a direct API permission of the API user (a role does not count). Without it, downloading its file answers 404 and uploading or deleting one 422.

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/people/architecto/files/photo" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --form "file=@/tmp/phpVnHdF0" 
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/people/architecto/files/photo"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "multipart/form-data",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

const body = new FormData();
body.append('file', document.querySelector('input[name="file"]').files[0]);

fetch(url, {
    method: "POST",
    headers,
    body,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/people/architecto/files/photo';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'multipart/form-data',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'multipart' => [
            [
                'name' => 'file',
                'contents' => fopen('/tmp/phpVnHdF0', 'r')
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
        "project_id": 1,
        "data": {
            "photo": "form-attachments/01a1e3a6-efbf-4413-9db1-f36e60489254/8f14e45fceea167a5a36dedd4bea2543.jpg"
        },
        "person_types": [
            "volunteer"
        ],
        "related": {
            "teams": [],
            "groups_owned": [],
            "groups_member": [],
            "events": [],
            "tickets": [],
            "orders": []
        },
        "created_at": "2026-04-30T11:24:53+00:00",
        "updated_at": "2026-04-30T12:00:00+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "message": "Unauthenticated."
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, UnknownFieldOrPerson):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (422, NotAnUploadField):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "field": [
                "The field 'firstname' does not take a file upload."
            ]
        }
    }
}
 

Example response (422, ProtectedByDataQualification):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "field": [
                "Field 'passport_scan': you may not upload or clear its file — your user holds data qualification 'Personal Data' read-only. Do not retry; this needs a user with write access to it."
            ]
        }
    }
}
 

Example response (422, FileRejected):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "file": [
                "This file type is not allowed."
            ]
        }
    }
}
 

Request      

POST api/v2/projects/{project_id}/people/{person_id}/files/{field}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: multipart/form-data

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

person_id   string     

The ID of the person. Example: architecto

field   string     

Name of the file/image field as declared in one of the person type's form definitions. Example: photo

project   integer     

Project id. Example: 1

person   string     

Person UUID. Example: 01a1e3a6-efbf-4413-9db1-f36e60489254

Body Parameters

file   file     

The file to store. Example: /tmp/phpVnHdF0

Clear a Person's file/image field.

requires authentication

Required API permission: “Edit people and groups” (all_persons_and_applications_manage)

Depending on the permission: a form field marked as protected needs “Read protected fields” (securedata_see) as a direct API permission of the API user (a role does not count). Without it, downloading its file answers 404 and uploading or deleting one 422.

Example request:
curl --request DELETE \
    "https://{instance}.festiwa.re/api/v2/projects/564/people/architecto/files/photo" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/people/architecto/files/photo"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/people/architecto/files/photo';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
        "project_id": 1,
        "data": {},
        "person_types": [
            "volunteer"
        ],
        "related": {
            "teams": [],
            "groups_owned": [],
            "groups_member": [],
            "events": [],
            "tickets": [],
            "orders": []
        },
        "created_at": "2026-04-30T11:24:53+00:00",
        "updated_at": "2026-04-30T12:00:00+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "message": "Unauthenticated."
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, UnknownFieldOrPerson):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (422, NotAnUploadField):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "field": [
                "The field 'firstname' does not take a file upload."
            ]
        }
    }
}
 

Example response (422, ProtectedByDataQualification):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "field": [
                "Field 'passport_scan': you may not upload or clear its file — your user holds data qualification 'Personal Data' read-only. Do not retry; this needs a user with write access to it."
            ]
        }
    }
}
 

Request      

DELETE api/v2/projects/{project_id}/people/{person_id}/files/{field}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

person_id   string     

The ID of the person. Example: architecto

field   string     

Name of the file/image field. Example: photo

project   integer     

Project id. Example: 1

person   string     

Person UUID. Example: 01a1e3a6-efbf-4413-9db1-f36e60489254

Ticket Types

Paginated list of Ticket Types in a project.

requires authentication

Required API permission: “Read tickets” (ticketcode_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/ticket-types?per_page=25&created_since=2026-06-01T00%3A00%3A00%2B00%3A00&updated_since=2026-06-01T00%3A00%3A00%2B00%3A00" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/ticket-types"
);

const params = {
    "per_page": "25",
    "created_since": "2026-06-01T00:00:00+00:00",
    "updated_since": "2026-06-01T00:00:00+00:00",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/ticket-types';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'created_since' => '2026-06-01T00:00:00+00:00',
            'updated_since' => '2026-06-01T00:00:00+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": 161,
            "name": "Shuttle Berlin",
            "shortname": "BFST",
            "description": "Bus shuttle from Berlin Ostbahnhof",
            "issue": 100,
            "available_in_backend": true,
            "ticket_category_id": 7,
            "created_at": "2026-05-07T11:24:53+00:00",
            "updated_at": "2026-05-07T11:24:53+00:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Request      

GET api/v2/projects/{project_id}/ticket-types

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

created_since   string  optional    

ISO 8601 timestamp with offset; only records created at or after it. Example: 2026-06-01T00:00:00+00:00

updated_since   string  optional    

ISO 8601 timestamp with offset; only records updated at or after it. Example: 2026-06-01T00:00:00+00:00

Create a new Ticket Type in a project.

requires authentication

Required API permission: “Manage ticket types” (ticketcode_administrate)

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/ticket-types" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --form "name=Shuttle Berlin"\
    --form "shortname=BFST"\
    --form "description=Bus shuttle from Berlin Ostbahnhof to the festival site."\
    --form "issue=100"\
    --form "available_in_backend=1"\
    --form "ticket_category_id=7"\
    --form "additional_html=<p>Welcome!</p>"\
    --form "ticket_background=@/tmp/phpoApHmy" 
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/ticket-types"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "multipart/form-data",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

const body = new FormData();
body.append('name', 'Shuttle Berlin');
body.append('shortname', 'BFST');
body.append('description', 'Bus shuttle from Berlin Ostbahnhof to the festival site.');
body.append('issue', '100');
body.append('available_in_backend', '1');
body.append('ticket_category_id', '7');
body.append('additional_html', '<p>Welcome!</p>');
body.append('ticket_background', document.querySelector('input[name="ticket_background"]').files[0]);

fetch(url, {
    method: "POST",
    headers,
    body,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/ticket-types';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'multipart/form-data',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'multipart' => [
            [
                'name' => 'name',
                'contents' => 'Shuttle Berlin'
            ],
            [
                'name' => 'shortname',
                'contents' => 'BFST'
            ],
            [
                'name' => 'description',
                'contents' => 'Bus shuttle from Berlin Ostbahnhof to the festival site.'
            ],
            [
                'name' => 'issue',
                'contents' => '100'
            ],
            [
                'name' => 'available_in_backend',
                'contents' => '1'
            ],
            [
                'name' => 'ticket_category_id',
                'contents' => '7'
            ],
            [
                'name' => 'additional_html',
                'contents' => '<p>Welcome!</p>'
            ],
            [
                'name' => 'ticket_background',
                'contents' => fopen('/tmp/phpoApHmy', 'r')
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201, Created):


{
    "id": 161,
    "name": "Shuttle Berlin",
    "shortname": "BFST",
    "description": null,
    "issue": 100,
    "available_in_backend": true,
    "ticket_category_id": null,
    "created_at": "2026-05-07T11:24:53+00:00",
    "updated_at": "2026-05-07T11:24:53+00:00"
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "name": [
                "The name field is required."
            ],
            "shortname": [
                "The shortname must be 2-4 alphanumeric characters."
            ]
        }
    }
}
 

Request      

POST api/v2/projects/{project_id}/ticket-types

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: multipart/form-data

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Body Parameters

name   string     

Required on POST, optional on PATCH. Display name (max 255 chars). Must not be greater than 255 characters. Example: Shuttle Berlin

shortname   string     

Required on POST, optional on PATCH. TicketCode prefix — 2-4 alphanumeric characters. Must match the regex /^[a-zA-Z0-9]{2,4}$/. Example: BFST

description   string  optional    

Optional descriptive text. Nullable. Example: Bus shuttle from Berlin Ostbahnhof to the festival site.

issue   integer  optional    

Optional total capacity. 0 means unlimited (capacity managed via options instead). Must be at least 0. Example: 100

available_in_backend   boolean  optional    

Optional. Whether the ticket type is visible to backend operators. Example: true

ticket_category_id   integer  optional    

Optional category foreign key. Nullable. Example: 7

additional_html   string  optional    

Optional "Contextual information": HTML shown in the check-in app when a ticket of this type is scanned, not printed on the PDF ticket. Twig placeholders: ticketType, owner, order, orderPosition, ticketCode. Cleaned on save: script, event handlers, unsafe links and external resources are removed; inline styles, <style> blocks (scoped to this template) and classes (prefixed fw-u-) stay. Twig runs in a sandbox: {{ }}, if, for, set and simple filters; placeholders work in text and as a style value, not in other attributes. |raw is accepted and has no effect: every value stays escaped. A template the sandbox cannot render is refused with 422. Nullable. Example: <p>Welcome!</p>

ticket_background   file  optional    

Optional PDF ticket background image (multipart file — on PATCH send as POST with _method=PATCH). Stored on the public disk; response returns ticket_background_url. Must be a file. Must be an image. Example: /tmp/phpoApHmy

Show a single Ticket Type by id.

requires authentication

Required API permission: “Read tickets” (ticketcode_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/ticket-types/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/ticket-types/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/ticket-types/16';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "id": 161,
    "name": "Shuttle Berlin",
    "shortname": "BFST",
    "description": "Bus shuttle from Berlin Ostbahnhof",
    "issue": 100,
    "available_in_backend": true,
    "ticket_category_id": 7,
    "created_at": "2026-05-07T11:24:53+00:00",
    "updated_at": "2026-05-07T11:24:53+00:00"
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Ticket Type not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/ticket-types/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   integer     

The ID of the ticket type. Example: 16

project   integer     

Project id. Example: 16

ticketType   integer     

Ticket Type id. Example: 16

Update a Ticket Type (PATCH = sparse merge; PUT = full replace).

requires authentication

Required API permission: “Manage ticket types” (ticketcode_administrate)

Example request:
curl --request PUT \
    "https://{instance}.festiwa.re/api/v2/projects/564/ticket-types/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --form "name=Shuttle Berlin"\
    --form "shortname=BFST"\
    --form "description=Bus shuttle from Berlin Ostbahnhof to the festival site."\
    --form "issue=100"\
    --form "available_in_backend=1"\
    --form "ticket_category_id=7"\
    --form "additional_html=<p>Welcome!</p>"\
    --form "ticket_background=@/tmp/phpU9w5dP" 
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/ticket-types/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "multipart/form-data",
    "Accept": "application/json",
};

const body = new FormData();
body.append('name', 'Shuttle Berlin');
body.append('shortname', 'BFST');
body.append('description', 'Bus shuttle from Berlin Ostbahnhof to the festival site.');
body.append('issue', '100');
body.append('available_in_backend', '1');
body.append('ticket_category_id', '7');
body.append('additional_html', '<p>Welcome!</p>');
body.append('ticket_background', document.querySelector('input[name="ticket_background"]').files[0]);

fetch(url, {
    method: "PUT",
    headers,
    body,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/ticket-types/16';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'multipart/form-data',
            'Accept' => 'application/json',
        ],
        'multipart' => [
            [
                'name' => 'name',
                'contents' => 'Shuttle Berlin'
            ],
            [
                'name' => 'shortname',
                'contents' => 'BFST'
            ],
            [
                'name' => 'description',
                'contents' => 'Bus shuttle from Berlin Ostbahnhof to the festival site.'
            ],
            [
                'name' => 'issue',
                'contents' => '100'
            ],
            [
                'name' => 'available_in_backend',
                'contents' => '1'
            ],
            [
                'name' => 'ticket_category_id',
                'contents' => '7'
            ],
            [
                'name' => 'additional_html',
                'contents' => '<p>Welcome!</p>'
            ],
            [
                'name' => 'ticket_background',
                'contents' => fopen('/tmp/phpU9w5dP', 'r')
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "id": 161,
    "name": "Shuttle Berlin (updated)",
    "shortname": "BFST",
    "description": "Updated description.",
    "issue": 150,
    "available_in_backend": true,
    "ticket_category_id": 7,
    "created_at": "2026-05-07T11:24:53+00:00",
    "updated_at": "2026-05-07T12:00:00+00:00"
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Ticket Type not found."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "shortname": [
                "The shortname must be 2-4 alphanumeric characters."
            ]
        }
    }
}
 

Request      

PUT api/v2/projects/{project_id}/ticket-types/{id}

PATCH api/v2/projects/{project_id}/ticket-types/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: multipart/form-data

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   integer     

The ID of the ticket type. Example: 16

project   integer     

Project id. Example: 16

ticketType   integer     

Ticket Type id. Example: 16

Body Parameters

name   string     

Required on POST, optional on PATCH. Display name (max 255 chars). Must not be greater than 255 characters. Example: Shuttle Berlin

shortname   string     

Required on POST, optional on PATCH. TicketCode prefix — 2-4 alphanumeric characters. Must match the regex /^[a-zA-Z0-9]{2,4}$/. Example: BFST

description   string  optional    

Optional descriptive text. Nullable. Example: Bus shuttle from Berlin Ostbahnhof to the festival site.

issue   integer  optional    

Optional total capacity. 0 means unlimited (capacity managed via options instead). Must be at least 0. Example: 100

available_in_backend   boolean  optional    

Optional. Whether the ticket type is visible to backend operators. Example: true

ticket_category_id   integer  optional    

Optional category foreign key. Nullable. Example: 7

additional_html   string  optional    

Optional "Contextual information": HTML shown in the check-in app when a ticket of this type is scanned, not printed on the PDF ticket. Twig placeholders: ticketType, owner, order, orderPosition, ticketCode. Cleaned on save: script, event handlers, unsafe links and external resources are removed; inline styles, <style> blocks (scoped to this template) and classes (prefixed fw-u-) stay. Twig runs in a sandbox: {{ }}, if, for, set and simple filters; placeholders work in text and as a style value, not in other attributes. |raw is accepted and has no effect: every value stays escaped. A template the sandbox cannot render is refused with 422. Nullable. Example: <p>Welcome!</p>

ticket_background   file  optional    

Optional PDF ticket background image (multipart file — on PATCH send as POST with _method=PATCH). Stored on the public disk; response returns ticket_background_url. Must be a file. Must be an image. Example: /tmp/phpU9w5dP

Delete a Ticket Type. Refuses with 409 if the type still has issued ticket codes or offers attached.

requires authentication

Required API permission: “Manage ticket types” (ticketcode_administrate)

Example request:
curl --request DELETE \
    "https://{instance}.festiwa.re/api/v2/projects/564/ticket-types/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/ticket-types/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/ticket-types/16';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (204, Deleted):

Empty response
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Ticket Type not found."
    }
}
 

Example response (409, HasTicketCodes):


{
    "error": {
        "code": "ticket_type_has_codes",
        "message": "This ticket type has issued ticket codes and cannot be deleted."
    }
}
 

Example response (409, HasOffers):


{
    "error": {
        "code": "ticket_type_has_offers",
        "message": "This ticket type has offers attached and cannot be deleted."
    }
}
 

Request      

DELETE api/v2/projects/{project_id}/ticket-types/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   integer     

The ID of the ticket type. Example: 16

project   integer     

Project id. Example: 16

ticketType   integer     

Ticket Type id. Example: 16

Ticket Codes

Paginated list of Ticket Codes in a project.

requires authentication

Each item nests its ticket_type (id, shortname) and its owner (id, firstname, lastname, email); owner is null when the code is unowned.

status is the code's current status, the same value v1 returns as current_ticket_code_status.ticket_status: pending (not yet activated), valid, redeemed (scanned at the gate) or revoked (annulled). It is null for the rare code without any status row; such a code never opens a gate. status_changed_at is when the current status was set.

All filters combine (AND).

Required API permission: “Read tickets” (ticketcode_see)

Depending on the permission: form fields marked as protected are returned in plain text only with “Read protected fields” (securedata_see) as a direct API permission of the API user (a role does not count); without it their keys are left out of data and calculated_data, also of nested people and groups, and a nested person's name or e-mail or a group's name is null.

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/ticket-codes?per_page=25&updated_since=2026-06-01T00%3A00%3A00%2B00%3A00&ticket_type=VIP&status=redeemed&created_since=2026-06-01T00%3A00%3A00%2B00%3A00&person_id=01a1e3a6-efbf-4413-9db1-f36e60489254" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"per_page\": 16,
    \"updated_since\": \"2026-11-19T01:25:40+01:00\",
    \"ticket_type\": \"n\",
    \"status\": \"valid\",
    \"person_id\": \"6b72fe4a-5b40-307c-bc24-f79acf9a1bb9\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/ticket-codes"
);

const params = {
    "per_page": "25",
    "updated_since": "2026-06-01T00:00:00+00:00",
    "ticket_type": "VIP",
    "status": "redeemed",
    "created_since": "2026-06-01T00:00:00+00:00",
    "person_id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "per_page": 16,
    "updated_since": "2026-11-19T01:25:40+01:00",
    "ticket_type": "n",
    "status": "valid",
    "person_id": "6b72fe4a-5b40-307c-bc24-f79acf9a1bb9"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/ticket-codes';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'updated_since' => '2026-06-01T00:00:00+00:00',
            'ticket_type' => 'VIP',
            'status' => 'redeemed',
            'created_since' => '2026-06-01T00:00:00+00:00',
            'person_id' => '01a1e3a6-efbf-4413-9db1-f36e60489254',
        ],
        'json' => [
            'per_page' => 16,
            'updated_since' => '2026-11-19T01:25:40+01:00',
            'ticket_type' => 'n',
            'status' => 'valid',
            'person_id' => '6b72fe4a-5b40-307c-bc24-f79acf9a1bb9',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": "9b1c4d2e-0000-4000-8000-000000000001",
            "code": "ABC123",
            "ticket_type": {
                "id": 42,
                "shortname": "VIP"
            },
            "owner": {
                "id": "7a2f4d2e-0000-4000-8000-000000000002",
                "firstname": "Anna",
                "lastname": "Meyer",
                "email": "anna@example.com"
            },
            "status": "redeemed",
            "status_changed_at": "2026-06-02T18:30:00+00:00",
            "created_at": "2026-06-01T10:00:00+00:00",
            "updated_at": "2026-06-01T10:00:00+00:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "status": [
                "The selected status is invalid."
            ]
        }
    }
}
 

Request      

GET api/v2/projects/{project_id}/ticket-codes

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

updated_since   string  optional    

ISO 8601 timestamp with offset. Returns codes whose row changed OR whose status changed (e.g. redeemed) at or after this moment — a status change does not touch the code's own updated_at. Example: 2026-06-01T00:00:00+00:00

ticket_type   string  optional    

Ticket type id or shortname. Example: VIP

status   string  optional    

Current status: pending, valid, redeemed or revoked. Example: redeemed

created_since   string  optional    

ISO 8601 timestamp with offset; only records created at or after it. Example: 2026-06-01T00:00:00+00:00

person_id   string  optional    

Only codes owned by this Person (UUID). A person of another project returns an empty list. Example: 01a1e3a6-efbf-4413-9db1-f36e60489254

Body Parameters

per_page   integer  optional    

Must be at least 1. Example: 16

updated_since   string  optional    

Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-11-19T01:25:40+01:00

ticket_type   string  optional    

Must not be greater than 255 characters. Example: n

status   string  optional    

Example: valid

Must be one of:
  • pending
  • valid
  • redeemed
  • revoked
person_id   string  optional    

Must be a valid UUID. Example: 6b72fe4a-5b40-307c-bc24-f79acf9a1bb9

Show one Ticket Code, including its current status.

requires authentication

Same shape as an item of the list.

Required API permission: “Read tickets” (ticketcode_see)

Depending on the permission: form fields marked as protected are returned in plain text only with “Read protected fields” (securedata_see) as a direct API permission of the API user (a role does not count); without it their keys are left out of data and calculated_data, also of nested people and groups, and a nested person's name or e-mail or a group's name is null.

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/ticket-codes/architecto" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/ticket-codes/architecto"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/ticket-codes/architecto';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": "9b1c4d2e-0000-4000-8000-000000000001",
        "code": "ABC123",
        "ticket_type": {
            "id": 42,
            "shortname": "VIP"
        },
        "owner": null,
        "status": "valid",
        "status_changed_at": "2026-06-01T10:00:00+00:00",
        "created_at": "2026-06-01T10:00:00+00:00",
        "updated_at": "2026-06-01T10:00:00+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/ticket-codes/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   string     

The ID of the ticket code. Example: architecto

project   integer     

Project id. Example: 16

ticket_code   string     

Ticket code UUID (not the printed code). Example: 9b1c4d2e-0000-4000-8000-000000000001

Orders

Paginated list of Orders in a project.

requires authentication

Each order carries currency, total_price, total_discount and total_donation — major units, rounded to 2 decimals, the same values as the backend's order detail. current_status is the status shortname (OPEN, PAID, DELIVERED, CANCELLED, CONFLICTING, RETURNREQUESTED, RETURNED, SWAPPED). All filters combine (AND).

withTicketCodes additionally needs ticketcode_see.

Required API permission: “Read orders and offers” (order_see)

Depending on the request also: “Read tickets” (ticketcode_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/orders?per_page=25&status=PAID%2CDELIVERED&created_from=2026-06-01T00%3A00%3A00%2B02%3A00&created_until=2026-07-01T00%3A00%3A00%2B02%3A00&updated_since=2026-06-01T00%3A00%3A00%2B00%3A00&withPositions=&withTicketCodes=&created_since=2026-06-01T00%3A00%3A00%2B00%3A00&person_id=7a2f4d2e-0000-4000-8000-000000000002" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"per_page\": 16,
    \"status\": \"architecto\",
    \"statuses\": [
        \"SWAPPED\"
    ],
    \"created_from\": \"2026-11-19T01:25:40+01:00\",
    \"created_until\": \"2026-11-19T01:25:40+01:00\",
    \"updated_since\": \"2026-11-19T01:25:40+01:00\",
    \"person_id\": \"a4855dc5-0acb-33c3-b921-f4291f719ca0\",
    \"withPositions\": false,
    \"withTicketCodes\": true
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/orders"
);

const params = {
    "per_page": "25",
    "status": "PAID,DELIVERED",
    "created_from": "2026-06-01T00:00:00+02:00",
    "created_until": "2026-07-01T00:00:00+02:00",
    "updated_since": "2026-06-01T00:00:00+00:00",
    "withPositions": "0",
    "withTicketCodes": "0",
    "created_since": "2026-06-01T00:00:00+00:00",
    "person_id": "7a2f4d2e-0000-4000-8000-000000000002",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "per_page": 16,
    "status": "architecto",
    "statuses": [
        "SWAPPED"
    ],
    "created_from": "2026-11-19T01:25:40+01:00",
    "created_until": "2026-11-19T01:25:40+01:00",
    "updated_since": "2026-11-19T01:25:40+01:00",
    "person_id": "a4855dc5-0acb-33c3-b921-f4291f719ca0",
    "withPositions": false,
    "withTicketCodes": true
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/orders';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'status' => 'PAID,DELIVERED',
            'created_from' => '2026-06-01T00:00:00+02:00',
            'created_until' => '2026-07-01T00:00:00+02:00',
            'updated_since' => '2026-06-01T00:00:00+00:00',
            'withPositions' => '0',
            'withTicketCodes' => '0',
            'created_since' => '2026-06-01T00:00:00+00:00',
            'person_id' => '7a2f4d2e-0000-4000-8000-000000000002',
        ],
        'json' => [
            'per_page' => 16,
            'status' => 'architecto',
            'statuses' => [
                'SWAPPED',
            ],
            'created_from' => '2026-11-19T01:25:40+01:00',
            'created_until' => '2026-11-19T01:25:40+01:00',
            'updated_since' => '2026-11-19T01:25:40+01:00',
            'person_id' => 'a4855dc5-0acb-33c3-b921-f4291f719ca0',
            'withPositions' => false,
            'withTicketCodes' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": "3f8a4d2e-0000-4000-8000-000000000001",
            "order_number": "2026-000123",
            "current_status": "PAID",
            "firstname": "Anna",
            "lastname": "Meyer",
            "email": "anna@example.com",
            "created_at": "2026-06-01T10:00:00+00:00",
            "updated_at": "2026-06-01T10:00:00+00:00",
            "currency": "EUR",
            "total_price": 89,
            "total_discount": 10,
            "total_donation": 5
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (200, With positions (?withPositions=1)):


{
    "data": [
        {
            "id": "3f8a4d2e-0000-4000-8000-000000000001",
            "order_number": "2026-000123",
            "current_status": "PAID",
            "firstname": "Anna",
            "lastname": "Meyer",
            "email": "anna@example.com",
            "created_at": "2026-06-01T10:00:00+00:00",
            "updated_at": "2026-06-01T10:00:00+00:00",
            "currency": "EUR",
            "total_price": 89,
            "total_discount": 10,
            "total_donation": 5,
            "positions": [
                {
                    "id": 501,
                    "offer": {
                        "id": 300,
                        "shortname": "weekend"
                    },
                    "coupon": null,
                    "amount": 2,
                    "price": 47,
                    "total_price": 94,
                    "tax": 19,
                    "currency": "EUR",
                    "is_donation": false
                }
            ]
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "statuses.0": [
                "The selected statuses.0 is invalid."
            ]
        }
    }
}
 

Request      

GET api/v2/projects/{project_id}/orders

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

status   string  optional    

Current status, one or several comma-separated, case-insensitive. Example: PAID,DELIVERED

created_from   string  optional    

ISO 8601 timestamp with offset; orders created at or after it. Example: 2026-06-01T00:00:00+02:00

created_until   string  optional    

ISO 8601 timestamp with offset; orders created before it (exclusive). Example: 2026-07-01T00:00:00+02:00

updated_since   string  optional    

ISO 8601 timestamp with offset; orders updated at or after it. Example: 2026-06-01T00:00:00+00:00

withPositions   boolean  optional    

Sideload positions on each order. Default false. Example: false

withTicketCodes   boolean  optional    

Sideload ticket_codes (id, code, ticket_type) on each order. Requires ticketcode_see. Default false. Example: false

created_since   string  optional    

ISO 8601 timestamp with offset; only orders created at or after it, the same as created_from (the common name across v2 lists). Example: 2026-06-01T00:00:00+00:00

person_id   string  optional    

Only orders of this Person (UUID). A person of another project returns an empty list. Example: 7a2f4d2e-0000-4000-8000-000000000002

Body Parameters

per_page   integer  optional    

Must be at least 1. Example: 16

status   string  optional    

Example: architecto

statuses   string[]  optional    
Must be one of:
  • OPEN
  • PAID
  • DELIVERED
  • CANCELLED
  • CONFLICTING
  • RETURNREQUESTED
  • RETURNED
  • SWAPPED
created_from   string  optional    

Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-11-19T01:25:40+01:00

created_until   string  optional    

Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-11-19T01:25:40+01:00

updated_since   string  optional    

Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-11-19T01:25:40+01:00

person_id   string  optional    

Must be a valid UUID. Example: a4855dc5-0acb-33c3-b921-f4291f719ca0

withPositions   boolean  optional    

Example: false

withTicketCodes   boolean  optional    

Example: true

Show one Order with positions, payments and its invoice reference.

requires authentication

Adds billing data, payment_type, amount_received / amount_open, positions, payments (the order's transactions that are not ignored — the same set amount_received is summed from) and invoice (id, invoice_number, or null).

withTicketCodes additionally needs ticketcode_see.

Required API permission: “Read orders and offers” (order_see)

Depending on the request also: “Read tickets” (ticketcode_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/orders/architecto?withTicketCodes=" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/orders/architecto"
);

const params = {
    "withTicketCodes": "0",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/orders/architecto';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'withTicketCodes' => '0',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": "3f8a4d2e-0000-4000-8000-000000000001",
        "order_number": "2026-000123",
        "current_status": "PAID",
        "firstname": "Anna",
        "lastname": "Meyer",
        "email": "anna@example.com",
        "created_at": "2026-06-01T10:00:00+00:00",
        "updated_at": "2026-06-01T10:00:00+00:00",
        "currency": "EUR",
        "total_price": 89,
        "total_discount": 10,
        "total_donation": 5,
        "positions": [
            {
                "id": 501,
                "offer": {
                    "id": 300,
                    "shortname": "weekend"
                },
                "coupon": null,
                "amount": 2,
                "price": 47,
                "total_price": 94,
                "tax": 19,
                "currency": "EUR",
                "is_donation": false
            },
            {
                "id": 502,
                "offer": null,
                "coupon": {
                    "id": 12,
                    "code": "BUS-7F3K9A"
                },
                "amount": 1,
                "price": -10,
                "total_price": -10,
                "tax": 0,
                "currency": "EUR",
                "is_donation": false
            },
            {
                "id": 503,
                "offer": null,
                "coupon": null,
                "amount": 1,
                "price": 5,
                "total_price": 5,
                "tax": 0,
                "currency": "EUR",
                "is_donation": true
            }
        ],
        "person_id": "7a2f4d2e-0000-4000-8000-000000000002",
        "company": null,
        "address": "Hauptstr. 1",
        "address2": null,
        "zip": "04109",
        "city": "Leipzig",
        "country": "DE",
        "vat_id": null,
        "payment_type": "mollie",
        "amount_received": 89,
        "amount_open": 0,
        "payments": [
            {
                "id": 7001,
                "transaction_number": "tr_abc123",
                "transaction_type": "payment",
                "payment_method": "creditcard",
                "status": "paid",
                "balance": 89,
                "currency": "EUR",
                "registered_at": "2026-06-01T10:01:00+00:00",
                "created_at": "2026-06-01T10:01:00+00:00"
            }
        ],
        "invoice": {
            "id": 880,
            "invoice_number": "RE-2026-0042"
        }
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/orders/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   string     

The ID of the order. Example: architecto

project   integer     

Project id. Example: 16

order   string     

Order UUID. Example: 3f8a4d2e-0000-4000-8000-000000000001

Query Parameters

withTicketCodes   boolean  optional    

Sideload ticket_codes. Requires ticketcode_see. Default false. Example: false

Offers

Money fields are JSON numbers: price is the gross amount in the project's currency (the currency is a per-project setting, not part of the response), and tax is a rate as a decimal (0.19 = 19%), not a computed amount.

Paginated list of OfferCategories in a project.

requires authentication

Sort: order ASC (admin-curated shop display order), id ASC tiebreaker.

Required API permission: “Read orders and offers” (order_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/offer-categories?per_page=25&page=1&created_since=2026-06-01T00%3A00%3A00%2B00%3A00&updated_since=2026-06-01T00%3A00%3A00%2B00%3A00" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/offer-categories"
);

const params = {
    "per_page": "25",
    "page": "1",
    "created_since": "2026-06-01T00:00:00+00:00",
    "updated_since": "2026-06-01T00:00:00+00:00",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/offer-categories';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'page' => '1',
            'created_since' => '2026-06-01T00:00:00+00:00',
            'updated_since' => '2026-06-01T00:00:00+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": 42,
            "project_id": 5,
            "name": "Outbound",
            "shortname": "outbound",
            "description": "Bus shuttles leaving the festival",
            "order": 1,
            "created_at": "2026-06-23T09:00:00+00:00",
            "updated_at": "2026-06-23T09:00:00+00:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Request      

GET api/v2/projects/{project_id}/offer-categories

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

page   integer  optional    

Page number (1-indexed). Example: 1

created_since   string  optional    

ISO 8601 timestamp with offset; only records created at or after it. Example: 2026-06-01T00:00:00+00:00

updated_since   string  optional    

ISO 8601 timestamp with offset; only records updated at or after it. Example: 2026-06-01T00:00:00+00:00

Create an OfferCategory in a project.

requires authentication

Required API permission: “Manage offers” (order_administrate)

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/offer-categories" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --data "{
    \"name\": \"Outbound\",
    \"shortname\": \"outbound\",
    \"description\": \"Bus shuttles leaving the festival.\",
    \"name_translations\": {
        \"de\": \"Hinfahrt\",
        \"en\": \"Outbound\"
    },
    \"description_translations\": {
        \"de\": \"Busse ab dem Festival.\",
        \"en\": \"Bus shuttles leaving the festival.\"
    }
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/offer-categories"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

let body = {
    "name": "Outbound",
    "shortname": "outbound",
    "description": "Bus shuttles leaving the festival.",
    "name_translations": {
        "de": "Hinfahrt",
        "en": "Outbound"
    },
    "description_translations": {
        "de": "Busse ab dem Festival.",
        "en": "Bus shuttles leaving the festival."
    }
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/offer-categories';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'json' => [
            'name' => 'Outbound',
            'shortname' => 'outbound',
            'description' => 'Bus shuttles leaving the festival.',
            'name_translations' => [
                'de' => 'Hinfahrt',
                'en' => 'Outbound',
            ],
            'description_translations' => [
                'de' => 'Busse ab dem Festival.',
                'en' => 'Bus shuttles leaving the festival.',
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201, Created):


{
    "id": 42,
    "project_id": 5,
    "name": "Outbound",
    "shortname": "outbound",
    "description": null,
    "order": 0,
    "created_at": "2026-06-23T09:00:00+00:00",
    "updated_at": "2026-06-23T09:00:00+00:00"
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "name": [
                "The name field is required."
            ],
            "shortname": [
                "The shortname field is required."
            ]
        }
    }
}
 

Request      

POST api/v2/projects/{project_id}/offer-categories

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Body Parameters

name   string  optional    

Required unless name_translations is sent. Display name (max 255 chars); sent alone, it also becomes the German entry of name_translations. This field is required when name_translations is not present. Must not be greater than 255 characters. Example: Outbound

shortname   string     

Required. Short identifier, unique per project (max 255 chars). Must not be greater than 255 characters. Example: outbound

description   string  optional    

Optional explanation. Nullable. Sent alone, it also becomes the German entry of description_translations. Example: Bus shuttles leaving the festival.

name_translations   object  optional    

Multilanguage name map ({de, en}, de required): what the backend editor and the shop group header show. Its de value is copied into name; wins over name when both are sent.

description_translations   object  optional    

Multilanguage description map ({de, en}, de required): what the backend editor and the shop show. Its de value is copied into description; wins over description when both are sent.

project_id   string  optional    
typeable_model   string  optional    
id   string  optional    

Show a single OfferCategory.

requires authentication

?withOffers=1 adds the legacy combined payload — each offer with its offerable (TicketType) inlined, mirroring v1's with('offers.offerable'). Unpaginated. The new /offer-categories/{category}/offers sub-resource is the best-practice path for new integrators.

Required API permission: “Read orders and offers” (order_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/offer-categories/16?withOffers=" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/offer-categories/16"
);

const params = {
    "withOffers": "0",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/offer-categories/16';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'withOffers' => '0',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "id": 42,
    "project_id": 5,
    "name": "Outbound",
    "shortname": "outbound",
    "description": "Bus shuttles leaving the festival",
    "order": 1,
    "created_at": "2026-06-23T09:00:00+00:00",
    "updated_at": "2026-06-23T09:00:00+00:00"
}
 

Example response (200, OK (withOffers=1)):


{
    "id": 42,
    "project_id": 5,
    "name": "Outbound",
    "shortname": "outbound",
    "description": "Bus shuttles leaving the festival",
    "order": 1,
    "created_at": "2026-06-23T09:00:00+00:00",
    "updated_at": "2026-06-23T09:00:00+00:00",
    "offers": [
        {
            "id": 300,
            "shortname": "shuttle-bln",
            "description": "Bus shuttle from Berlin",
            "price": 2500,
            "tax": 19,
            "issue": 100,
            "ticket_count": 1,
            "available_from": "2026-06-01T00:00:00+00:00",
            "available_to": "2026-06-20T00:00:00+00:00",
            "published_from": null,
            "published_to": null,
            "sort_order": 1,
            "offerable": {
                "id": 161,
                "name": "Shuttle Berlin",
                "shortname": "BFST",
                "description": "Bus shuttle from Berlin Ostbahnhof",
                "issue": 100,
                "available_in_backend": true,
                "ticket_category_id": 7,
                "created_at": "2026-05-07T11:24:53+00:00",
                "updated_at": "2026-05-07T11:24:53+00:00"
            }
        }
    ]
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/offer-categories/{category_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

category_id   integer     

The ID of the category. Example: 16

project   integer     

Project id. Example: 16

category   integer     

OfferCategory id. Example: 16

Query Parameters

withOffers   boolean  optional    

Include offers[] with each offer's offerable inlined (legacy v1-shape). Default: false. Example: false

Update an OfferCategory. Both PUT and PATCH route here.

requires authentication

Optimistic lock via updated_at. Mismatch → 409 optimistic_lock_failed. PUT requires every editable field; PATCH treats omissions as preserve-existing.

Required API permission: “Manage offers” (order_administrate)

Example request:
curl --request PUT \
    "https://{instance}.festiwa.re/api/v2/projects/564/offer-categories/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Outbound\",
    \"shortname\": \"outbound\",
    \"description\": \"Bus shuttles leaving the festival.\",
    \"order\": 2,
    \"name_translations\": {
        \"de\": \"Hinfahrt\",
        \"en\": \"Outbound\"
    },
    \"description_translations\": {
        \"de\": \"Busse ab dem Festival.\",
        \"en\": \"Bus shuttles leaving the festival.\"
    },
    \"updated_at\": \"2026-06-23T09:00:00+00:00\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/offer-categories/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "Outbound",
    "shortname": "outbound",
    "description": "Bus shuttles leaving the festival.",
    "order": 2,
    "name_translations": {
        "de": "Hinfahrt",
        "en": "Outbound"
    },
    "description_translations": {
        "de": "Busse ab dem Festival.",
        "en": "Bus shuttles leaving the festival."
    },
    "updated_at": "2026-06-23T09:00:00+00:00"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/offer-categories/16';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'name' => 'Outbound',
            'shortname' => 'outbound',
            'description' => 'Bus shuttles leaving the festival.',
            'order' => 2,
            'name_translations' => [
                'de' => 'Hinfahrt',
                'en' => 'Outbound',
            ],
            'description_translations' => [
                'de' => 'Busse ab dem Festival.',
                'en' => 'Bus shuttles leaving the festival.',
            ],
            'updated_at' => '2026-06-23T09:00:00+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "id": 42,
    "project_id": 5,
    "name": "Outbound (updated)",
    "shortname": "outbound",
    "description": "Bus shuttles leaving the festival",
    "order": 2,
    "created_at": "2026-06-23T09:00:00+00:00",
    "updated_at": "2026-06-23T12:00:00+00:00"
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (409, OptimisticLockFailed):


{
    "error": {
        "code": "optimistic_lock_failed",
        "message": "The resource was modified after your last read. Re-fetch and retry.",
        "errors": {
            "current": {
                "updated_at": "2026-06-23T12:00:00+00:00"
            }
        }
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "updated_at": [
                "The updated_at field is required."
            ]
        }
    }
}
 

Request      

PUT api/v2/projects/{project_id}/offer-categories/{category_id}

PATCH api/v2/projects/{project_id}/offer-categories/{category_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

category_id   integer     

The ID of the category. Example: 16

project   integer     

Project id. Example: 16

category   integer     

OfferCategory id. Example: 16

Body Parameters

name   string  optional    

Required on PUT unless name_translations is sent, optional on PATCH. Display name (max 255 chars); sent alone, it also replaces the German entry of name_translations, English stays. This field is required when name_translations is not present. Must not be greater than 255 characters. Example: Outbound

shortname   string     

Required on PUT, optional on PATCH. Short identifier (max 255 chars). Must not be greater than 255 characters. Example: outbound

description   string  optional    

Optional explanation. Sent alone, it also replaces the German entry of description_translations (English stays); null clears both. Example: Bus shuttles leaving the festival.

order   integer  optional    

Optional sort position within the project. Example: 2

name_translations   object  optional    

Multilanguage name map ({de, en}, de required), replaced as a whole: what the backend editor and the shop group header show. Its de value is copied into name. Cannot be null.

description_translations   object  optional    

Multilanguage description map ({de, en}, de required), replaced as a whole. Its de value is copied into description; null clears both.

updated_at   string     

Required ISO 8601 last-known timestamp (optimistic-lock token). Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-06-23T09:00:00+00:00

project_id   string  optional    
typeable_model   string  optional    
id   string  optional    

Soft-delete an OfferCategory.

requires authentication

Requires {"confirm": true} body. Returns 409 offer_category_has_offers (with count in the message) if the category still has offers attached.

Required API permission: “Manage offers” (order_administrate)

Example request:
curl --request DELETE \
    "https://{instance}.festiwa.re/api/v2/projects/564/offer-categories/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"confirm\": true
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/offer-categories/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "confirm": true
};

fetch(url, {
    method: "DELETE",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/offer-categories/16';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'confirm' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (204, Deleted):

Empty response
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (409, HasOffers):


{
    "error": {
        "code": "offer_category_has_offers",
        "message": "This offer category cannot be deleted because offers are still attached. (3)"
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "confirm": [
                "The confirm field must be accepted."
            ]
        }
    }
}
 

Request      

DELETE api/v2/projects/{project_id}/offer-categories/{category_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

category_id   integer     

The ID of the category. Example: 16

project   integer     

Project id. Example: 16

category   integer     

OfferCategory id. Example: 16

Body Parameters

confirm   boolean     

Required guard against accidental deletion. Must be exactly true — false or omission returns 422 and leaves the category intact. Must be accepted. Example: true

Paginated list of OfferableOptions in a project.

requires authentication

Optional filter by offerable_id + offerable_type. The polymorphic relation has no project_id column on the join — scoping is enforced by filtering against TicketTypes belonging to the URL's {project}.

Required API permission: “Read orders and offers” (order_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/offerable-options?offerable_id=16&offerable_type=architecto&per_page=25&created_since=2026-06-01T00%3A00%3A00%2B00%3A00&updated_since=2026-06-01T00%3A00%3A00%2B00%3A00" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/offerable-options"
);

const params = {
    "offerable_id": "16",
    "offerable_type": "architecto",
    "per_page": "25",
    "created_since": "2026-06-01T00:00:00+00:00",
    "updated_since": "2026-06-01T00:00:00+00:00",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/offerable-options';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'offerable_id' => '16',
            'offerable_type' => 'architecto',
            'per_page' => '25',
            'created_since' => '2026-06-01T00:00:00+00:00',
            'updated_since' => '2026-06-01T00:00:00+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": 88,
            "name": "Early bird seat",
            "description": "Discounted seat for early buyers",
            "issue": 50,
            "overbook_allowance": 0,
            "active": true,
            "offerable_id": 161,
            "offerable_type": "App\\TicketType",
            "valid_from": "2026-06-01T00:00:00+00:00",
            "valid_to": "2026-06-20T00:00:00+00:00",
            "sort_order": 1,
            "created_at": "2026-06-23T09:00:00+00:00",
            "updated_at": "2026-06-23T09:00:00+00:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Request      

GET api/v2/projects/{project_id}/offerable-options

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Query Parameters

offerable_id   integer  optional    

Filter by the parent offerable's id. Example: 16

offerable_type   string  optional    

Filter by offerable class. Currently allow-listed to App\TicketType. Example: architecto

per_page   integer  optional    

Page size, clamped to 100. Example: 25

created_since   string  optional    

ISO 8601 timestamp with offset; only records created at or after it. Example: 2026-06-01T00:00:00+00:00

updated_since   string  optional    

ISO 8601 timestamp with offset; only records updated at or after it. Example: 2026-06-01T00:00:00+00:00

Create an OfferableOption attached to a TicketType.

requires authentication

Resolves offerable_id × offerable_type, then verifies the offerable belongs to the URL's {project} via assertBelongsToProject() — cross-project returns 404 (same guard used for URL-bound cross-tenant checks).

Required API permission: “Manage offers” (order_administrate)

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/offerable-options" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --data "{
    \"offerable_id\": 161,
    \"offerable_type\": \"App\\\\TicketType\",
    \"name\": \"Early bird seat\",
    \"description\": \"Discounted seat for early buyers.\",
    \"issue\": 50,
    \"overbook_allowance\": 16,
    \"active\": true,
    \"valid_from\": \"2026-06-01\",
    \"valid_to\": \"2026-06-20\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/offerable-options"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

let body = {
    "offerable_id": 161,
    "offerable_type": "App\\TicketType",
    "name": "Early bird seat",
    "description": "Discounted seat for early buyers.",
    "issue": 50,
    "overbook_allowance": 16,
    "active": true,
    "valid_from": "2026-06-01",
    "valid_to": "2026-06-20"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/offerable-options';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'json' => [
            'offerable_id' => 161,
            'offerable_type' => 'App\\TicketType',
            'name' => 'Early bird seat',
            'description' => 'Discounted seat for early buyers.',
            'issue' => 50,
            'overbook_allowance' => 16,
            'active' => true,
            'valid_from' => '2026-06-01',
            'valid_to' => '2026-06-20',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201, Created):


{
    "id": 88,
    "name": "Early bird seat",
    "description": "Discounted seat for early buyers",
    "issue": 50,
    "overbook_allowance": 0,
    "active": true,
    "offerable_id": 161,
    "offerable_type": "App\\TicketType",
    "valid_from": "2026-06-01T00:00:00+00:00",
    "valid_to": "2026-06-20T00:00:00+00:00",
    "sort_order": 0,
    "created_at": "2026-06-23T09:00:00+00:00",
    "updated_at": "2026-06-23T09:00:00+00:00"
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "offerable_id": [
                "The offerable_id field is required."
            ],
            "name": [
                "The name field is required."
            ]
        }
    }
}
 

Request      

POST api/v2/projects/{project_id}/offerable-options

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Body Parameters

offerable_id   integer     

Required. Parent TicketType id. Available types via GET /api/v2/projects/{project}/ticket-types. Example: 161

offerable_type   string     

Required. Always App\TicketType — the only allow-listed value. Example: App\TicketType

Must be one of:
  • App\TicketType
name   string     

Required. Display label (max 255 chars). Must not be greater than 255 characters. Example: Early bird seat

description   string  optional    

Optional help text. Nullable. Example: Discounted seat for early buyers.

issue   integer     

Required. Capacity. 0 means unlimited. Must be at least 0. Example: 50

overbook_allowance   integer  optional    

Optional. Coupon-only extra seats on top of issue (0 = off). Example: 16

active   boolean     

Required. Whether the option is purchasable. Example: true

valid_from   string  optional    

Optional availability window start (date). Nullable. Must be a valid date. Example: 2026-06-01

valid_to   string  optional    

Optional availability window end (date, after valid_from). Nullable. Must be a valid date. Must be a date after valid_from. Example: 2026-06-20

id   string  optional    
sort_order   string  optional    

Show a single OfferableOption.

requires authentication

Required API permission: “Read orders and offers” (order_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/offerable-options/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/offerable-options/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/offerable-options/16';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "id": 88,
    "name": "Early bird seat",
    "description": "Discounted seat for early buyers",
    "issue": 50,
    "overbook_allowance": 0,
    "active": true,
    "offerable_id": 161,
    "offerable_type": "App\\TicketType",
    "valid_from": "2026-06-01T00:00:00+00:00",
    "valid_to": "2026-06-20T00:00:00+00:00",
    "sort_order": 1,
    "created_at": "2026-06-23T09:00:00+00:00",
    "updated_at": "2026-06-23T09:00:00+00:00"
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/offerable-options/{option_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

option_id   integer     

The ID of the option. Example: 16

project   integer     

Project id. Example: 16

option   integer     

OfferableOption id. Example: 16

Update an OfferableOption. Both PUT and PATCH route here.

requires authentication

offerable_id and offerable_type are prohibited on update — re-parenting is not supported. Optimistic lock via updated_at.

Required API permission: “Manage offers” (order_administrate)

Example request:
curl --request PUT \
    "https://{instance}.festiwa.re/api/v2/projects/564/offerable-options/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Early bird seat\",
    \"description\": \"Discounted seat for early buyers.\",
    \"issue\": 75,
    \"overbook_allowance\": 16,
    \"active\": true,
    \"valid_from\": \"2026-06-01\",
    \"valid_to\": \"2026-06-20\",
    \"updated_at\": \"2026-06-23T09:00:00+00:00\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/offerable-options/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "Early bird seat",
    "description": "Discounted seat for early buyers.",
    "issue": 75,
    "overbook_allowance": 16,
    "active": true,
    "valid_from": "2026-06-01",
    "valid_to": "2026-06-20",
    "updated_at": "2026-06-23T09:00:00+00:00"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/offerable-options/16';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'name' => 'Early bird seat',
            'description' => 'Discounted seat for early buyers.',
            'issue' => 75,
            'overbook_allowance' => 16,
            'active' => true,
            'valid_from' => '2026-06-01',
            'valid_to' => '2026-06-20',
            'updated_at' => '2026-06-23T09:00:00+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "id": 88,
    "name": "Early bird seat (updated)",
    "description": "Discounted seat for early buyers",
    "issue": 75,
    "overbook_allowance": 0,
    "active": true,
    "offerable_id": 161,
    "offerable_type": "App\\TicketType",
    "valid_from": "2026-06-01T00:00:00+00:00",
    "valid_to": "2026-06-20T00:00:00+00:00",
    "sort_order": 1,
    "created_at": "2026-06-23T09:00:00+00:00",
    "updated_at": "2026-06-23T12:00:00+00:00"
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (409, OptimisticLockFailed):


{
    "error": {
        "code": "optimistic_lock_failed",
        "message": "The resource was modified after your last read. Re-fetch and retry.",
        "errors": {
            "current": {
                "updated_at": "2026-06-23T12:00:00+00:00"
            }
        }
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "offerable_id": [
                "The offerable_id field is prohibited."
            ],
            "updated_at": [
                "The updated_at field is required."
            ]
        }
    }
}
 

Request      

PUT api/v2/projects/{project_id}/offerable-options/{option_id}

PATCH api/v2/projects/{project_id}/offerable-options/{option_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

option_id   integer     

The ID of the option. Example: 16

project   integer     

Project id. Example: 16

option   integer     

OfferableOption id. Example: 16

Body Parameters

name   string     

Required on PUT, optional on PATCH. Display label (max 255 chars). Must not be greater than 255 characters. Example: Early bird seat

description   string  optional    

Optional help text. Nullable. Example: Discounted seat for early buyers.

issue   integer     

Required on PUT, optional on PATCH. Capacity. 0 means unlimited. Must be at least 0. Example: 75

overbook_allowance   integer  optional    

Optional. Coupon-only extra seats on top of issue (0 = off). Example: 16

active   boolean     

Required on PUT, optional on PATCH. Whether the option is purchasable. Example: true

valid_from   string  optional    

Optional availability window start (date). Nullable. Must be a valid date. Example: 2026-06-01

valid_to   string  optional    

Optional availability window end (date, after valid_from). Nullable. Must be a valid date. Must be a date after valid_from. Example: 2026-06-20

updated_at   string     

Required ISO 8601 last-known timestamp (optimistic-lock token). Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-06-23T09:00:00+00:00

offerable_id   string  optional    
offerable_type   string  optional    
id   string  optional    
sort_order   string  optional    

Soft-delete an OfferableOption.

requires authentication

Requires {"confirm": true} body. Returns 409 offerable_option_has_order_positions (with count in the message) if the option still has order_positions attached.

Required API permission: “Manage offers” (order_administrate)

Example request:
curl --request DELETE \
    "https://{instance}.festiwa.re/api/v2/projects/564/offerable-options/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"confirm\": true
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/offerable-options/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "confirm": true
};

fetch(url, {
    method: "DELETE",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/offerable-options/16';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'confirm' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (204, Deleted):

Empty response
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (409, HasOrderPositions):


{
    "error": {
        "code": "offerable_option_has_order_positions",
        "message": "This option cannot be deleted because order positions still reference it. (5)"
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "confirm": [
                "The confirm field must be accepted."
            ]
        }
    }
}
 

Request      

DELETE api/v2/projects/{project_id}/offerable-options/{option_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

option_id   integer     

The ID of the option. Example: 16

project   integer     

Project id. Example: 16

option   integer     

OfferableOption id. Example: 16

Body Parameters

confirm   boolean     

Required guard against accidental deletion. Must be exactly true — false or omission returns 422 and leaves the option intact. Must be accepted. Example: true

Paginated list of Offers in a given OfferCategory.

requires authentication

Best-practice sub-resource path. Each offer carries its offerable (TicketType) inlined by default — no opt-in flag. Mirrors Tier 2's /event-plans/{plan}/events pattern. The legacy /offer-categories/{category}?withOffers=1 endpoint provides the same data unpaginated for v1 callers.

Required API permission: “Read orders and offers” (order_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/offer-categories/16/offers?per_page=25&page=1&created_since=2026-06-01T00%3A00%3A00%2B00%3A00&updated_since=2026-06-01T00%3A00%3A00%2B00%3A00" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/offer-categories/16/offers"
);

const params = {
    "per_page": "25",
    "page": "1",
    "created_since": "2026-06-01T00:00:00+00:00",
    "updated_since": "2026-06-01T00:00:00+00:00",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/offer-categories/16/offers';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'page' => '1',
            'created_since' => '2026-06-01T00:00:00+00:00',
            'updated_since' => '2026-06-01T00:00:00+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": 300,
            "shortname": "shuttle-bln",
            "description": "Bus shuttle from Berlin",
            "price": 2500,
            "tax": 19,
            "issue": 100,
            "ticket_count": 1,
            "available_from": "2026-06-01T00:00:00+00:00",
            "available_to": "2026-06-20T00:00:00+00:00",
            "published_from": null,
            "published_to": null,
            "sort_order": 1,
            "offerable": {
                "id": 161,
                "name": "Shuttle Berlin",
                "shortname": "BFST",
                "description": "Bus shuttle from Berlin Ostbahnhof",
                "issue": 100,
                "available_in_backend": true,
                "ticket_category_id": 7,
                "created_at": "2026-05-07T11:24:53+00:00",
                "updated_at": "2026-05-07T11:24:53+00:00"
            }
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/offer-categories/{category_id}/offers

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

category_id   integer     

The ID of the category. Example: 16

project   integer     

Project id. Example: 16

category   integer     

OfferCategory id. Example: 16

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

page   integer  optional    

Page number (1-indexed). Example: 1

created_since   string  optional    

ISO 8601 timestamp with offset; only records created at or after it. Example: 2026-06-01T00:00:00+00:00

updated_since   string  optional    

ISO 8601 timestamp with offset; only records updated at or after it. Example: 2026-06-01T00:00:00+00:00

Paginated list of Offers in a project.

requires authentication

Admin surface: hidden and unpublished offers are included. Each item carries its offerable (ticket type) and offer_category.

Required API permission: “Read orders and offers” (order_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/offers?per_page=25&page=1&created_since=2026-06-01T00%3A00%3A00%2B00%3A00&updated_since=2026-06-01T00%3A00%3A00%2B00%3A00" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/offers"
);

const params = {
    "per_page": "25",
    "page": "1",
    "created_since": "2026-06-01T00:00:00+00:00",
    "updated_since": "2026-06-01T00:00:00+00:00",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/offers';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'page' => '1',
            'created_since' => '2026-06-01T00:00:00+00:00',
            'updated_since' => '2026-06-01T00:00:00+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": 311,
            "shortname": "Camping Club Hamburg",
            "name_translations": null,
            "description": null,
            "price": 0,
            "tax": 0,
            "issue": 0,
            "ticket_count": 1,
            "hidden_link": "club-hamburg",
            "image_url": "https://instance.example/storage/api-uploads/offers/1753364000_logo.png",
            "email_product": true,
            "max_order_amount": 8,
            "required_ticket_types": [],
            "required_person_types": [],
            "no_dynamic_showing": false,
            "available_from": null,
            "available_to": null,
            "published_from": null,
            "published_to": null,
            "sort_order": 1,
            "updated_at": "2026-07-24T09:00:00+00:00",
            "offerable": {
                "id": 208,
                "name": "Camping Club Hamburg",
                "shortname": "CCHH",
                "description": null,
                "capacity": 0,
                "valid_from": null,
                "valid_to": null,
                "available_in_backend": true,
                "category_id": null,
                "ticket_background_url": null,
                "additional_html": null,
                "created_at": "2026-07-24T09:00:00+00:00",
                "updated_at": "2026-07-24T09:00:00+00:00"
            },
            "offer_category": {
                "id": 91,
                "project_id": 5,
                "name": "Camping",
                "shortname": "camping",
                "description": null,
                "order": 0,
                "created_at": "2026-07-24T09:00:00+00:00",
                "updated_at": "2026-07-24T09:00:00+00:00"
            }
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Request      

GET api/v2/projects/{project_id}/offers

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

page   integer  optional    

Page number (1-indexed). Example: 1

created_since   string  optional    

ISO 8601 timestamp with offset; only records created at or after it. Example: 2026-06-01T00:00:00+00:00

updated_since   string  optional    

ISO 8601 timestamp with offset; only records updated at or after it. Example: 2026-06-01T00:00:00+00:00

Create an Offer (composite).

requires authentication

Atomic: the ticket type is created from ticket_type[...] XOR referenced via ticket_type_id; the category is referenced via offer_category_id XOR found-or-created from offer_category[...] (keyed on shortname + project). Any failure leaves zero rows and zero stored files. Content type: multipart/form-data.

The 201 response carries hidden_link and image_url — integrations build the individualized shop link without a second request.

Required API permission: “Manage offers” (order_administrate)

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/offers" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --form "shortname=Camping Club Hamburg"\
    --form "name[de]=Camping Club Hamburg"\
    --form "name[en]=Camping Club Hamburg"\
    --form "description=Includes breakfast"\
    --form "description_translations[de]=Inkl. Frühstück"\
    --form "description_translations[en]=Includes breakfast"\
    --form "price=0"\
    --form "tax=0"\
    --form "issue=27"\
    --form "hidden_link=club-hamburg"\
    --form "hide_show_all_link=1"\
    --form "email_product=1"\
    --form "max_order_amount=8"\
    --form "published_from=2026-11-19T01:25:41"\
    --form "published_to=2052-12-12"\
    --form "available_from=2026-11-19T01:25:41"\
    --form "available_to=2052-12-12"\
    --form "required_ticket_types[]=16"\
    --form "required_person_types[]=16"\
    --form "no_dynamic_showing=1"\
    --form "ticket_type_id=208"\
    --form "ticket_type[name]=Camping Club Hamburg"\
    --form "ticket_type[shortname]=CCHH"\
    --form "ticket_type[description]=Eius et animi quos velit et."\
    --form "ticket_type[issue]=60"\
    --form "ticket_type[available_in_backend]="\
    --form "ticket_type[ticket_category_id]=16"\
    --form "ticket_type[valid_from]=2022-12-13"\
    --form "ticket_type[valid_to]=2052-12-12"\
    --form "ticket_type[additional_html]=<p>Welcome, Club Hamburg!</p>"\
    --form "offer_category_id=91"\
    --form "offer_category[name]=Camping"\
    --form "offer_category[shortname]=camping"\
    --form "offer_category[description]=Eius et animi quos velit et."\
    --form "tax_rules[][layout]=architecto"\
    --form "tax_rules[][key]=architecto"\
    --form "tax_rules[][attributes][label]=n"\
    --form "tax_rules[][attributes][percent]=1"\
    --form "tax_rules[][attributes][rate]=1"\
    --form "image=@/tmp/phpbM5fRU" \
    --form "ticket_type[ticket_background]=@/tmp/phptjwx7Y" 
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/offers"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "multipart/form-data",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

const body = new FormData();
body.append('shortname', 'Camping Club Hamburg');
body.append('name[de]', 'Camping Club Hamburg');
body.append('name[en]', 'Camping Club Hamburg');
body.append('description', 'Includes breakfast');
body.append('description_translations[de]', 'Inkl. Frühstück');
body.append('description_translations[en]', 'Includes breakfast');
body.append('price', '0');
body.append('tax', '0');
body.append('issue', '27');
body.append('hidden_link', 'club-hamburg');
body.append('hide_show_all_link', '1');
body.append('email_product', '1');
body.append('max_order_amount', '8');
body.append('published_from', '2026-11-19T01:25:41');
body.append('published_to', '2052-12-12');
body.append('available_from', '2026-11-19T01:25:41');
body.append('available_to', '2052-12-12');
body.append('required_ticket_types[]', '16');
body.append('required_person_types[]', '16');
body.append('no_dynamic_showing', '1');
body.append('ticket_type_id', '208');
body.append('ticket_type[name]', 'Camping Club Hamburg');
body.append('ticket_type[shortname]', 'CCHH');
body.append('ticket_type[description]', 'Eius et animi quos velit et.');
body.append('ticket_type[issue]', '60');
body.append('ticket_type[available_in_backend]', '');
body.append('ticket_type[ticket_category_id]', '16');
body.append('ticket_type[valid_from]', '2022-12-13');
body.append('ticket_type[valid_to]', '2052-12-12');
body.append('ticket_type[additional_html]', '<p>Welcome, Club Hamburg!</p>');
body.append('offer_category_id', '91');
body.append('offer_category[name]', 'Camping');
body.append('offer_category[shortname]', 'camping');
body.append('offer_category[description]', 'Eius et animi quos velit et.');
body.append('tax_rules[][layout]', 'architecto');
body.append('tax_rules[][key]', 'architecto');
body.append('tax_rules[][attributes][label]', 'n');
body.append('tax_rules[][attributes][percent]', '1');
body.append('tax_rules[][attributes][rate]', '1');
body.append('image', document.querySelector('input[name="image"]').files[0]);
body.append('ticket_type[ticket_background]', document.querySelector('input[name="ticket_type[ticket_background]"]').files[0]);

fetch(url, {
    method: "POST",
    headers,
    body,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/offers';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'multipart/form-data',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'multipart' => [
            [
                'name' => 'shortname',
                'contents' => 'Camping Club Hamburg'
            ],
            [
                'name' => 'name[de]',
                'contents' => 'Camping Club Hamburg'
            ],
            [
                'name' => 'name[en]',
                'contents' => 'Camping Club Hamburg'
            ],
            [
                'name' => 'description',
                'contents' => 'Includes breakfast'
            ],
            [
                'name' => 'description_translations[de]',
                'contents' => 'Inkl. Frühstück'
            ],
            [
                'name' => 'description_translations[en]',
                'contents' => 'Includes breakfast'
            ],
            [
                'name' => 'price',
                'contents' => '0'
            ],
            [
                'name' => 'tax',
                'contents' => '0'
            ],
            [
                'name' => 'issue',
                'contents' => '27'
            ],
            [
                'name' => 'hidden_link',
                'contents' => 'club-hamburg'
            ],
            [
                'name' => 'hide_show_all_link',
                'contents' => '1'
            ],
            [
                'name' => 'email_product',
                'contents' => '1'
            ],
            [
                'name' => 'max_order_amount',
                'contents' => '8'
            ],
            [
                'name' => 'published_from',
                'contents' => '2026-11-19T01:25:41'
            ],
            [
                'name' => 'published_to',
                'contents' => '2052-12-12'
            ],
            [
                'name' => 'available_from',
                'contents' => '2026-11-19T01:25:41'
            ],
            [
                'name' => 'available_to',
                'contents' => '2052-12-12'
            ],
            [
                'name' => 'required_ticket_types[]',
                'contents' => '16'
            ],
            [
                'name' => 'required_person_types[]',
                'contents' => '16'
            ],
            [
                'name' => 'no_dynamic_showing',
                'contents' => '1'
            ],
            [
                'name' => 'ticket_type_id',
                'contents' => '208'
            ],
            [
                'name' => 'ticket_type[name]',
                'contents' => 'Camping Club Hamburg'
            ],
            [
                'name' => 'ticket_type[shortname]',
                'contents' => 'CCHH'
            ],
            [
                'name' => 'ticket_type[description]',
                'contents' => 'Eius et animi quos velit et.'
            ],
            [
                'name' => 'ticket_type[issue]',
                'contents' => '60'
            ],
            [
                'name' => 'ticket_type[available_in_backend]',
                'contents' => ''
            ],
            [
                'name' => 'ticket_type[ticket_category_id]',
                'contents' => '16'
            ],
            [
                'name' => 'ticket_type[valid_from]',
                'contents' => '2022-12-13'
            ],
            [
                'name' => 'ticket_type[valid_to]',
                'contents' => '2052-12-12'
            ],
            [
                'name' => 'ticket_type[additional_html]',
                'contents' => '<p>Welcome, Club Hamburg!</p>'
            ],
            [
                'name' => 'offer_category_id',
                'contents' => '91'
            ],
            [
                'name' => 'offer_category[name]',
                'contents' => 'Camping'
            ],
            [
                'name' => 'offer_category[shortname]',
                'contents' => 'camping'
            ],
            [
                'name' => 'offer_category[description]',
                'contents' => 'Eius et animi quos velit et.'
            ],
            [
                'name' => 'tax_rules[][layout]',
                'contents' => 'architecto'
            ],
            [
                'name' => 'tax_rules[][key]',
                'contents' => 'architecto'
            ],
            [
                'name' => 'tax_rules[][attributes][label]',
                'contents' => 'n'
            ],
            [
                'name' => 'tax_rules[][attributes][percent]',
                'contents' => '1'
            ],
            [
                'name' => 'tax_rules[][attributes][rate]',
                'contents' => '1'
            ],
            [
                'name' => 'image',
                'contents' => fopen('/tmp/phpbM5fRU', 'r')
            ],
            [
                'name' => 'ticket_type[ticket_background]',
                'contents' => fopen('/tmp/phptjwx7Y', 'r')
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201, Created):


{
    "data": {
        "id": 311,
        "shortname": "Camping Club Hamburg",
        "price": 0,
        "tax": 0,
        "hidden_link": "club-hamburg",
        "required_ticket_types": [
            208
        ],
        "required_person_types": [],
        "no_dynamic_showing": true,
        "image_url": "https://instance.example/storage/api-uploads/offers/1753364000_logo.png",
        "offerable": {
            "id": 208,
            "shortname": "CCHH",
            "ticket_background_url": "https://instance.example/storage/api-uploads/ticket-backgrounds/1753364000_bg.jpg",
            "additional_html": "<p>Welcome!</p>"
        },
        "offer_category": {
            "id": 91,
            "name": "Camping",
            "shortname": "camping"
        }
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "ticket_type.shortname": [
                "The ticket type.shortname field format is invalid."
            ]
        }
    }
}
 

Request      

POST api/v2/projects/{project_id}/offers

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: multipart/form-data

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Body Parameters

shortname   string     

Plain display string (legacy default name). Must not be greater than 255 characters. Example: Camping Club Hamburg

name   object  optional    

Optional multilanguage map ({de, en}). Plain strings are not accepted on v2 — send at least de. Omitted, it defaults to {de: shortname}.

description   string  optional    

Plain product description (legacy column, used by mails and PDFs). Sent alone, it also becomes the German entry of description_translations. Ignored when description_translations is sent. Example: Includes breakfast

description_translations   object  optional    

Multilanguage description map ({de, en}): what the backend editor and the shop show. Its de value (or the first non-empty one) is copied into description. Multipart: description_translations[de]=…&description_translations[en]=….

price   number     

Gross price, max 2 decimal places. 0 is an ordinary value. Must be at least 0. Must not be greater than 999999.99. Example: 0

tax   number     

Tax rate as decimal (0.0–1.0). E.g. 0.19 = 19%. Must be at least 0. Must not be greater than 1. Example: 0

tax_rules   object[]  optional    
layout   string  optional    

Example: architecto

key   string  optional    

Example: architecto

attributes   object  optional    

This field is required when tax_rules is present.

label   string  optional    

This field is required when tax_rules.*.attributes is present. Must not be greater than 50 characters. Example: n

percent   number  optional    

This field is required when tax_rules.*.attributes is present. Must be at least 0. Must not be greater than 1. Example: 1

rate   number  optional    

This field is required when tax_rules.*.attributes is present. Must be at least 0. Must not be greater than 1. Example: 1

issue   integer  optional    

Must be at least 0. Example: 27

hidden_link   string  optional    

Caller-supplied keyword. When set, the offer is hidden from the public shop list and reachable only via ?shop_link=. Case-insensitive, shareable across offers. Must not be greater than 255 characters. Example: club-hamburg

hide_show_all_link   boolean  optional    

When true, a shop opened via ?oid= drops its "show all tickets" switch and stays on this offer. Example: true

image   file  optional    

Offer logo image file (multipart). Stored on the public disk; response returns the absolute URL. Must be a file. Must be an image. Example: /tmp/phpbM5fRU

email_product   boolean  optional    

Example: true

max_order_amount   integer  optional    

Maximum quantity per order. Omitted or null, it is stored as 8 (the backend default). Must be at least 1. Example: 8

published_from   string  optional    

Must be a valid date. Example: 2026-11-19T01:25:41

published_to   string  optional    

Must be a valid date. Must be a date after published_from. Example: 2052-12-12

available_from   string  optional    

Must be a valid date. Example: 2026-11-19T01:25:41

available_to   string  optional    

Must be a valid date. Must be a date after available_from. Example: 2052-12-12

required_ticket_types   integer[]  optional    

The id of an existing record in the ticket_types table.

required_person_types   integer[]  optional    

The id of an existing record in the types table.

no_dynamic_showing   boolean  optional    

Only meaningful together with required_ticket_types: when true the offer stays hidden until the person already owns one of the required tickets; a matching ticket in the cart no longer reveals it. Example: true

ticket_type_id   integer  optional    

Existing ticket type to attach to (same project). Mutually exclusive with ticket_type. This field is required when ticket_type is not present. Example: 208

ticket_type   object  optional    

This field is required when ticket_type_id is not present.

name   string  optional    

Ticket type display name (when creating one). This field is required when ticket_type is present. Must not be greater than 255 characters. Example: Camping Club Hamburg

shortname   string  optional    

TicketCode prefix — 2-4 alphanumeric characters. This field is required when ticket_type is present. Must match the regex /^[a-zA-Z0-9]{2,4}$/. Example: CCHH

description   string  optional    

Example: Eius et animi quos velit et.

issue   integer  optional    

Must be at least 0. Example: 60

available_in_backend   boolean  optional    

Example: false

ticket_category_id   integer  optional    

Example: 16

valid_from   string  optional    

Must be a valid date. Must be a date after or equal to 2000-01-01. Must be a date before 2100-01-01. Example: 2022-12-13

valid_to   string  optional    

Must be a valid date. Must be a date after ticket_type.valid_from. Example: 2052-12-12

additional_html   string  optional    

"Contextual information": HTML shown in the check-in app when a ticket of this type is scanned, not printed on the PDF ticket. Twig placeholders: ticketType, owner, order, orderPosition, ticketCode. Cleaned on save: script, event handlers, unsafe links and external resources are removed; inline styles, <style> blocks (scoped to this template) and classes (prefixed fw-u-) stay. Twig runs in a sandbox: {{ }}, if, for, set and simple filters; placeholders work in text and as a style value, not in other attributes. |raw is accepted and has no effect: every value stays escaped. A template the sandbox cannot render is refused with 422. Example: <p>Welcome, Club Hamburg!</p>

ticket_background   file  optional    

PDF ticket background image file (multipart). Must be a file. Must be an image. Example: /tmp/phptjwx7Y

offer_category_id   integer  optional    

Existing category id. Mutually exclusive with offer_category. This field is required when offer_category is not present. Example: 91

offer_category   object  optional    

This field is required when offer_category_id is not present.

name   string  optional    

Category display name (find-or-create). This field is required when offer_category is present. Must not be greater than 255 characters. Example: Camping

shortname   string  optional    

Category find-or-create key within the project. This field is required when offer_category is present. Must not be greater than 255 characters. Example: camping

description   string  optional    

Example: Eius et animi quos velit et.

Show a single Offer.

requires authentication

Required API permission: “Read orders and offers” (order_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/offers/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/offers/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/offers/16';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": 311,
        "shortname": "Camping Club Hamburg",
        "price": 0,
        "hidden_link": "club-hamburg",
        "required_ticket_types": [
            208
        ],
        "required_person_types": [],
        "no_dynamic_showing": true,
        "image_url": null,
        "offerable": {
            "id": 208,
            "shortname": "CCHH"
        },
        "offer_category": {
            "id": 91,
            "shortname": "camping"
        }
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/offers/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   integer     

The ID of the offer. Example: 16

project   integer     

Project id. Example: 16

offer   integer     

Offer id. Example: 16

Update an Offer (offer fields only). Both PUT and PATCH route here.

requires authentication

Optimistic lock via updated_at — mismatch → 409 optimistic_lock_failed. Omitted keys keep their current value on both verbs; PUT additionally requires every mandatory field (shortname, price, tax, issue, email_product), PATCH requires none of them. Ticket-type fields are rejected with 422 — change them via the ticket-types endpoint. Image changes: multipart POST + _method=PATCH. Shop visibility gates (required_ticket_types, required_person_types, no_dynamic_showing) are accepted here and on store.

Required API permission: “Manage offers” (order_administrate)

Example request:
curl --request PUT \
    "https://{instance}.festiwa.re/api/v2/projects/564/offers/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --form "shortname=Camping Club Hamburg"\
    --form "price=0"\
    --form "tax=0"\
    --form "issue=0"\
    --form "email_product=1"\
    --form "name[de]=Camping Club Hamburg"\
    --form "description=Includes breakfast and dinner"\
    --form "description_translations[de]=Inkl. Frühstück und Abendessen"\
    --form "description_translations[en]=Includes breakfast and dinner"\
    --form "hidden_link=club-hamburg-2027"\
    --form "hide_show_all_link=1"\
    --form "max_order_amount=8"\
    --form "published_from=2026-11-19T01:25:41"\
    --form "published_to=2052-12-12"\
    --form "available_from=2026-11-19T01:25:41"\
    --form "available_to=2052-12-12"\
    --form "offer_category_id=91"\
    --form "required_ticket_types[]=16"\
    --form "required_person_types[]=16"\
    --form "no_dynamic_showing=1"\
    --form "updated_at=2026-07-24T09:00:00+00:00"\
    --form "image=@/tmp/phpr18DC3" 
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/offers/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "multipart/form-data",
    "Accept": "application/json",
};

const body = new FormData();
body.append('shortname', 'Camping Club Hamburg');
body.append('price', '0');
body.append('tax', '0');
body.append('issue', '0');
body.append('email_product', '1');
body.append('name[de]', 'Camping Club Hamburg');
body.append('description', 'Includes breakfast and dinner');
body.append('description_translations[de]', 'Inkl. Frühstück und Abendessen');
body.append('description_translations[en]', 'Includes breakfast and dinner');
body.append('hidden_link', 'club-hamburg-2027');
body.append('hide_show_all_link', '1');
body.append('max_order_amount', '8');
body.append('published_from', '2026-11-19T01:25:41');
body.append('published_to', '2052-12-12');
body.append('available_from', '2026-11-19T01:25:41');
body.append('available_to', '2052-12-12');
body.append('offer_category_id', '91');
body.append('required_ticket_types[]', '16');
body.append('required_person_types[]', '16');
body.append('no_dynamic_showing', '1');
body.append('updated_at', '2026-07-24T09:00:00+00:00');
body.append('image', document.querySelector('input[name="image"]').files[0]);

fetch(url, {
    method: "PUT",
    headers,
    body,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/offers/16';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'multipart/form-data',
            'Accept' => 'application/json',
        ],
        'multipart' => [
            [
                'name' => 'shortname',
                'contents' => 'Camping Club Hamburg'
            ],
            [
                'name' => 'price',
                'contents' => '0'
            ],
            [
                'name' => 'tax',
                'contents' => '0'
            ],
            [
                'name' => 'issue',
                'contents' => '0'
            ],
            [
                'name' => 'email_product',
                'contents' => '1'
            ],
            [
                'name' => 'name[de]',
                'contents' => 'Camping Club Hamburg'
            ],
            [
                'name' => 'description',
                'contents' => 'Includes breakfast and dinner'
            ],
            [
                'name' => 'description_translations[de]',
                'contents' => 'Inkl. Frühstück und Abendessen'
            ],
            [
                'name' => 'description_translations[en]',
                'contents' => 'Includes breakfast and dinner'
            ],
            [
                'name' => 'hidden_link',
                'contents' => 'club-hamburg-2027'
            ],
            [
                'name' => 'hide_show_all_link',
                'contents' => '1'
            ],
            [
                'name' => 'max_order_amount',
                'contents' => '8'
            ],
            [
                'name' => 'published_from',
                'contents' => '2026-11-19T01:25:41'
            ],
            [
                'name' => 'published_to',
                'contents' => '2052-12-12'
            ],
            [
                'name' => 'available_from',
                'contents' => '2026-11-19T01:25:41'
            ],
            [
                'name' => 'available_to',
                'contents' => '2052-12-12'
            ],
            [
                'name' => 'offer_category_id',
                'contents' => '91'
            ],
            [
                'name' => 'required_ticket_types[]',
                'contents' => '16'
            ],
            [
                'name' => 'required_person_types[]',
                'contents' => '16'
            ],
            [
                'name' => 'no_dynamic_showing',
                'contents' => '1'
            ],
            [
                'name' => 'updated_at',
                'contents' => '2026-07-24T09:00:00+00:00'
            ],
            [
                'name' => 'image',
                'contents' => fopen('/tmp/phpr18DC3', 'r')
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": 311,
        "shortname": "Camping Club Hamburg",
        "hidden_link": "club-hamburg-2027",
        "updated_at": "2026-07-24T12:00:00+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (409, OptimisticLockFailed):


{
    "error": {
        "code": "optimistic_lock_failed",
        "message": "The resource was modified after your last read. Re-fetch and retry.",
        "errors": {
            "current": {
                "updated_at": "2026-07-24T12:00:00+00:00"
            }
        }
    }
}
 

Example response (422, TicketTypeFieldsRejected):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "ticket_type": [
                "Ticket type fields cannot be changed through the offer. Please use the ticket-types endpoint."
            ]
        }
    }
}
 

Request      

PUT api/v2/projects/{project_id}/offers/{id}

PATCH api/v2/projects/{project_id}/offers/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: multipart/form-data

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   integer     

The ID of the offer. Example: 16

project   integer     

Project id. Example: 16

offer   integer     

Offer id. Example: 16

Body Parameters

shortname   string     

Required on PUT, optional on PATCH. Must not be greater than 255 characters. Example: Camping Club Hamburg

price   number     

Required on PUT, optional on PATCH. Max 2 decimal places. Must be at least 0. Must not be greater than 999999.99. Example: 0

tax   number     

Required on PUT, optional on PATCH. Decimal 0.0–1.0. Must be at least 0. Must not be greater than 1. Example: 0

issue   integer     

Required on PUT, optional on PATCH. Available quantity. Must be at least 0. Example: 0

email_product   boolean     

Required on PUT, optional on PATCH. Example: true

name   object  optional    

Multilanguage map ({de, en}). Plain strings are not accepted on v2. Null clears it.

description   string  optional    

Plain product description (legacy column, used by mails and PDFs). Sent without description_translations, it also replaces the German entry of description_translations; English stays. Example: Includes breakfast and dinner

description_translations   object  optional    

Multilanguage description map ({de, en}), replaced as a whole: what the backend editor and the shop show. Its de value (or the first non-empty one) is copied into description. Multipart: description_translations[de]=….

tax_rules   object  optional    
hidden_link   string  optional    

Hidden-shop keyword; null clears it. Must not be greater than 255 characters. Example: club-hamburg-2027

hide_show_all_link   boolean  optional    

Shop drops its "show all tickets" switch when opened via ?oid=. Example: true

max_order_amount   integer  optional    

Maximum quantity per order. Do not send null: the shop does not list an offer whose limit is null. Must be at least 1. Example: 8

published_from   string  optional    

Must be a valid date. Example: 2026-11-19T01:25:41

published_to   string  optional    

Must be a valid date. Must be a date after published_from. Example: 2052-12-12

available_from   string  optional    

Must be a valid date. Example: 2026-11-19T01:25:41

available_to   string  optional    

Must be a valid date. Must be a date after available_from. Example: 2052-12-12

offer_category_id   integer  optional    

Category of this project. Null clears the assignment. The id of an existing record in the types table. Example: 91

image   file  optional    

New logo image (multipart — send as POST with _method=PATCH). Replacing deletes the old file. Must be a file. Must be an image. Example: /tmp/phpr18DC3

required_ticket_types   integer[]  optional    

The id of an existing record in the ticket_types table.

required_person_types   integer[]  optional    

The id of an existing record in the types table.

no_dynamic_showing   boolean  optional    

Only meaningful together with required_ticket_types: when true the offer stays hidden until the person already owns one of the required tickets; a matching ticket in the cart no longer reveals it. Example: true

updated_at   string     

Required ISO 8601 last-known timestamp (optimistic-lock token). Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-07-24T09:00:00+00:00

project_id   string  optional    
id   string  optional    
offerable_id   string  optional    
offerable_type   string  optional    

Soft-delete an Offer — the offer only, never the ticket type.

requires authentication

Requires {"confirm": true} body. Deletion goes through the model (identical to backend deletion), so sales history, coupon links and rebooking links survive by design. To also remove an orphaned ticket type, call DELETE /ticket-types/{id} separately — it refuses with 409 while the type is still in use.

Required API permission: “Manage offers” (order_administrate)

Example request:
curl --request DELETE \
    "https://{instance}.festiwa.re/api/v2/projects/564/offers/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"confirm\": true
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/offers/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "confirm": true
};

fetch(url, {
    method: "DELETE",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/offers/16';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'confirm' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (204, Deleted):

Empty response
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "confirm": [
                "The confirm field must be accepted."
            ]
        }
    }
}
 

Request      

DELETE api/v2/projects/{project_id}/offers/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   integer     

The ID of the offer. Example: 16

project   integer     

Project id. Example: 16

offer   integer     

Offer id. Example: 16

Body Parameters

confirm   boolean     

Required guard against accidental deletion. Must be exactly true — false or omission returns 422 and leaves the offer intact. Must be accepted. Example: true

Coupons

Paginated list of coupons in a project, including their redemption status.

requires authentication

Every item has the same shape as the show endpoint: order_amount (orders placed on the coupon), redeemed and is_valid. Use it for reconciliation and export; walk the pages with updated_since for incremental syncs.

Required API permission: “Read coupons” (app\modules\coupons\policies\coupon_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/coupons?per_page=25&active=1&redeemed=&updated_since=2026-06-01T00%3A00%3A00%2B00%3A00&created_since=2026-06-01T00%3A00%3A00%2B00%3A00" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"per_page\": 16,
    \"active\": true,
    \"redeemed\": true,
    \"updated_since\": \"2026-11-19T01:25:41+01:00\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/coupons"
);

const params = {
    "per_page": "25",
    "active": "1",
    "redeemed": "0",
    "updated_since": "2026-06-01T00:00:00+00:00",
    "created_since": "2026-06-01T00:00:00+00:00",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "per_page": 16,
    "active": true,
    "redeemed": true,
    "updated_since": "2026-11-19T01:25:41+01:00"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/coupons';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'active' => '1',
            'redeemed' => '0',
            'updated_since' => '2026-06-01T00:00:00+00:00',
            'created_since' => '2026-06-01T00:00:00+00:00',
        ],
        'json' => [
            'per_page' => 16,
            'active' => true,
            'redeemed' => true,
            'updated_since' => '2026-11-19T01:25:41+01:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": 12,
            "project_id": 5,
            "code": "BUS-7F3K9A",
            "type": "relative",
            "value": 100,
            "max_units": 1,
            "active": true,
            "is_singleuse": true,
            "uses_reserved_contingent": false,
            "valid_from": null,
            "valid_until": null,
            "person_id": null,
            "offer_ids": [
                300,
                301
            ],
            "created_at": "2026-06-23T09:00:00+00:00",
            "updated_at": "2026-06-23T09:00:00+00:00",
            "order_amount": 0,
            "redeemed": false,
            "is_valid": true
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "redeemed": [
                "The redeemed field must be true or false."
            ]
        }
    }
}
 

Request      

GET api/v2/projects/{project_id}/coupons

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

active   boolean  optional    

Only active (true) or only inactive (false) coupons. Example: true

redeemed   boolean  optional    

Only coupons with at least one order (true) or with none (false) — the same rule as redeemed in the response. Example: false

updated_since   string  optional    

ISO 8601 timestamp with offset; only coupons updated at or after it. Example: 2026-06-01T00:00:00+00:00

created_since   string  optional    

ISO 8601 timestamp with offset; only coupons created at or after it. Example: 2026-06-01T00:00:00+00:00

Body Parameters

per_page   integer  optional    

Must be at least 1. Example: 16

active   boolean  optional    

Example: true

redeemed   boolean  optional    

Example: true

updated_since   string  optional    

Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-11-19T01:25:41+01:00

Create a coupon in a project.

requires authentication

Generates a unique code server-side and returns the coupon with its linked offers. Restrict the coupon to specific products via offer_ids; omit them to apply to all.

Required API permission: “Manage coupons” (app\modules\coupons\policies\coupon_administrate)

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/coupons" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --data "{
    \"type\": \"relative\",
    \"value\": 100,
    \"max_units\": 1,
    \"is_singleuse\": true,
    \"active\": true,
    \"uses_reserved_contingent\": true,
    \"valid_from\": \"2026-06-01T00:00:00+00:00\",
    \"valid_until\": \"2026-06-30T00:00:00+00:00\",
    \"code_prefix\": \"BUS\",
    \"offer_ids\": [
        16
    ],
    \"person_id\": \"9b1c8a7e-4f3d-4c2a-9e1b-2f5a6c7d8e9f\",
    \"code\": \"BURTON-MUC\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/coupons"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

let body = {
    "type": "relative",
    "value": 100,
    "max_units": 1,
    "is_singleuse": true,
    "active": true,
    "uses_reserved_contingent": true,
    "valid_from": "2026-06-01T00:00:00+00:00",
    "valid_until": "2026-06-30T00:00:00+00:00",
    "code_prefix": "BUS",
    "offer_ids": [
        16
    ],
    "person_id": "9b1c8a7e-4f3d-4c2a-9e1b-2f5a6c7d8e9f",
    "code": "BURTON-MUC"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/coupons';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'json' => [
            'type' => 'relative',
            'value' => 100.0,
            'max_units' => 1,
            'is_singleuse' => true,
            'active' => true,
            'uses_reserved_contingent' => true,
            'valid_from' => '2026-06-01T00:00:00+00:00',
            'valid_until' => '2026-06-30T00:00:00+00:00',
            'code_prefix' => 'BUS',
            'offer_ids' => [
                16,
            ],
            'person_id' => '9b1c8a7e-4f3d-4c2a-9e1b-2f5a6c7d8e9f',
            'code' => 'BURTON-MUC',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201, Created):


{
    "id": 12,
    "project_id": 5,
    "code": "BUS-7F3K9A",
    "type": "relative",
    "value": 100,
    "active": true,
    "is_singleuse": true,
    "valid_from": null,
    "valid_until": null,
    "person_id": null,
    "offer_ids": [
        300,
        301
    ],
    "created_at": "2026-06-23T09:00:00+00:00",
    "updated_at": "2026-06-23T09:00:00+00:00"
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "type": [
                "The type field is required."
            ],
            "value": [
                "The value field is required."
            ]
        }
    }
}
 

Request      

POST api/v2/projects/{project_id}/coupons

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Body Parameters

type   string     

Required. Discount type — relative (percentage) or absolute (fixed amount). Example: relative

Must be one of:
  • absolute
  • relative
value   number     

Required. Discount value. relative: 0 <= value <= 100. absolute: value >= 0. 0 mints an unlock coupon: no discount, but it reveals coupon_required products. Example: 100

max_units   integer  optional    

Optional. Cap the discount to at most N covered order-position units (the most expensive ones). 0 = unlimited (covers every covered unit). Defaults to 1. relative/100 + max_units=1 grants exactly one free unit of any price. Must be at least 0. Example: 1

is_singleuse   boolean  optional    

Optional. Whether the coupon may be redeemed only once. Defaults to true. Example: true

active   boolean  optional    

Optional. Whether the coupon is active. Defaults to true. Example: true

uses_reserved_contingent   boolean  optional    

Optional. Serve this coupon from the departure's reserved contingent (OfferableOption.overbook_allowance) instead of the public one. Defaults to false. When the reserve is exhausted the booking is refused rather than falling back to public seats. Options without a reserve are unaffected. Example: true

valid_from   string  optional    

Optional ISO 8601 start of the validity window. Nullable. Must be a valid date. Example: 2026-06-01T00:00:00+00:00

valid_until   string  optional    

Optional ISO 8601 end of the validity window (>= valid_from). Nullable. Must be a valid date. Must be a date after or equal to valid_from. Example: 2026-06-30T00:00:00+00:00

code_prefix   string  optional    

Optional prefix prepended to the generated code (max 40, [A-Za-z0-9-]). Nullable. Must match the regex /^[A-Za-z0-9-]*$/. Must not be greater than 40 characters. Example: BUS

offer_ids   integer[]  optional    

The id of an existing record in the offers table.

person_id   string  optional    

Optional person (uuid) to link the coupon to. Nullable. Available people via GET /api/v2/projects/{project}/people. Must be a valid UUID. The id of an existing record in the people table. Example: 9b1c8a7e-4f3d-4c2a-9e1b-2f5a6c7d8e9f

code   string  optional    

Optional. Set the coupon code verbatim (letters, digits and hyphens, max 64). Must be unused, compared case-insensitively. Omit it to have one generated; cannot be combined with code_prefix. Must match the regex /^[A-Za-z0-9-]+$/. Must not be greater than 64 characters. Example: BURTON-MUC

id   string  optional    
project_id   string  optional    

Show a coupon, including its redemption status.

requires authentication

order_amount is the number of orders placed on the coupon, redeemed is a convenience boolean, and is_valid reflects the model's own validity check (active + within the validity window + not a spent single-use coupon).

Required API permission: “Read coupons” (app\modules\coupons\policies\coupon_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/coupons/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/coupons/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/coupons/16';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": 12,
        "project_id": 5,
        "code": "BUS-7F3K9A",
        "type": "relative",
        "value": 100,
        "active": true,
        "is_singleuse": true,
        "valid_from": null,
        "valid_until": null,
        "person_id": null,
        "offer_ids": [
            300,
            301
        ],
        "created_at": "2026-06-23T09:00:00+00:00",
        "updated_at": "2026-06-23T09:00:00+00:00",
        "order_amount": 0,
        "redeemed": false,
        "is_valid": true
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/coupons/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   integer     

The ID of the coupon. Example: 16

project   integer     

Project id. Example: 16

coupon   integer     

Coupon id. Example: 16

Update a coupon (deactivate / reactivate).

requires authentication

Toggles active only. Deactivation is the storno path and works even for an already-redeemed coupon — such a coupon cannot be deleted (its order positions pin it via a RESTRICT foreign key), but it can always be switched inactive.

Required API permission: “Manage coupons” (app\modules\coupons\policies\coupon_administrate)

Example request:
curl --request PATCH \
    "https://{instance}.festiwa.re/api/v2/projects/564/coupons/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"active\": false,
    \"max_units\": 1,
    \"uses_reserved_contingent\": true
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/coupons/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "active": false,
    "max_units": 1,
    "uses_reserved_contingent": true
};

fetch(url, {
    method: "PATCH",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/coupons/16';
$response = $client->patch(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'active' => false,
            'max_units' => 1,
            'uses_reserved_contingent' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": 12,
        "project_id": 5,
        "code": "BUS-7F3K9A",
        "type": "relative",
        "value": 100,
        "active": false,
        "is_singleuse": true,
        "valid_from": null,
        "valid_until": null,
        "person_id": null,
        "offer_ids": [
            300,
            301
        ],
        "created_at": "2026-06-23T09:00:00+00:00",
        "updated_at": "2026-06-23T09:10:00+00:00",
        "order_amount": 0,
        "redeemed": false,
        "is_valid": false
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "active": [
                "The active field is required."
            ]
        }
    }
}
 

Request      

PATCH api/v2/projects/{project_id}/coupons/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   integer     

The ID of the coupon. Example: 16

project   integer     

Project id. Example: 16

coupon   integer     

Coupon id. Example: 16

Body Parameters

active   boolean     

Required. Whether the coupon is active. Set false to deactivate (works even for an already-redeemed coupon — a redeemed coupon cannot be deleted, only deactivated). Example: false

max_units   integer  optional    

Optional. Cap the discount to at most N covered order-position units (the most expensive ones). 0 = unlimited. Must be at least 0. Example: 1

uses_reserved_contingent   boolean  optional    

Optional. Serve this coupon from the departure's reserved contingent instead of the public one. Example: true

code   string  optional    
id   string  optional    
project_id   string  optional    

Delete a coupon.

requires authentication

Only a coupon that was never redeemed can be deleted: as soon as an order position references it, the request is refused with 409 coupon_has_orders and the coupon stays. Deactivate such a coupon instead (PATCH with active: false), which is the storno path for redeemed coupons. The links to offers are removed together with the coupon. Requires confirm: true in the body.

Required API permission: “Manage coupons” (app\modules\coupons\policies\coupon_administrate)

Example request:
curl --request DELETE \
    "https://{instance}.festiwa.re/api/v2/projects/564/coupons/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"confirm\": true
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/coupons/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "confirm": true
};

fetch(url, {
    method: "DELETE",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/coupons/16';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'confirm' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (204, Deleted):

Empty response
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Example response (409, Redeemed):


{
    "error": {
        "code": "coupon_has_orders",
        "message": "This coupon cannot be deleted because it has already been redeemed in orders."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "confirm": [
                "The confirm field is required."
            ]
        }
    }
}
 

Request      

DELETE api/v2/projects/{project_id}/coupons/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   integer     

The ID of the coupon. Example: 16

project   integer     

Project id. Example: 16

coupon   integer     

Coupon id. Example: 16

Body Parameters

confirm   boolean     

Required guard against accidental deletion. Must be exactly true — false or omission returns 422 and leaves the coupon intact. Must be accepted. Example: true

Scheduler

List scheduler plans visible to the authenticated caller.

requires authentication

Paginated list filtered by SchedulerPlan::scopeVisibleToUser($user) — plans with view_roles are restricted to users whose roles match; plans with no view_roles fall back to the scheduler_see permission.

Required API permission: none. Lists only the schedules the caller may see: a schedule without view roles needs “Read scheduler” (scheduler_see), one with view roles one of those roles; “Manage scheduler” (scheduler_administrate) sees every schedule.

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/event-plans?per_page=25&page=1&created_since=2026-06-01T00%3A00%3A00%2B00%3A00&updated_since=2026-06-01T00%3A00%3A00%2B00%3A00" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/event-plans"
);

const params = {
    "per_page": "25",
    "page": "1",
    "created_since": "2026-06-01T00:00:00+00:00",
    "updated_since": "2026-06-01T00:00:00+00:00",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/event-plans';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'page' => '1',
            'created_since' => '2026-06-01T00:00:00+00:00',
            'updated_since' => '2026-06-01T00:00:00+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (500):

Show headers
cache-control: no-cache, private
content-type: application/json
access-control-allow-origin: *
access-control-expose-headers: Cache-Control, Content-Language, Content-Type, Expires, Last-Modified, Pragma
x-request-id: 52b77be3-53d6-475f-ad39-c03d734713fc
 

{
    "message": "An error occurred and was reported automatically.<br>(Event ID: 4ea308959b9f492797e59cbe4e77d0b7)<br>We usually resolve errors within a few hours.<br>Please try again later!"
}
 

Request      

GET api/v2/projects/{project_id}/event-plans

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

page   integer  optional    

Page number (1-indexed). Example: 1

created_since   string  optional    

ISO 8601 timestamp with offset; only records created at or after it. Example: 2026-06-01T00:00:00+00:00

updated_since   string  optional    

ISO 8601 timestamp with offset; only records updated at or after it. Example: 2026-06-01T00:00:00+00:00

Show a single scheduler plan.

requires authentication

Default returns plan scalars only — no events key on the response. Set ?withEvents=1 to receive the full v1-equivalent shape: events embedded as nested array, each event with area, jobs, attendees, applications populated. For paginated event reads, use the dedicated /event-plans/{plan}/events sub-resource instead.

attendees and applications are nested Person / Group resources only for callers with the all_persons_and_applications_see permission (or a higher level of it). Every other caller gets them as an array of person UUIDs and an array of group IDs; the events themselves are the same.

Required API permission: none. A schedule without view roles needs “Read scheduler” (scheduler_see), one with view roles one of those roles; “Manage scheduler” (scheduler_administrate) sees every schedule. Nested people and groups additionally need “Read people and groups” (all_persons_and_applications_see).

Depending on the permission: form fields marked as protected are returned in plain text only with “Read protected fields” (securedata_see) as a direct API permission of the API user (a role does not count); without it their keys are left out of data and calculated_data, also of nested people and groups, and a nested person's name or e-mail or a group's name is null.

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/event-plans/16?withEvents=" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/event-plans/16"
);

const params = {
    "withEvents": "0",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/event-plans/16';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'withEvents' => '0',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, withEvents=1 without all_persons_and_applications_see (shortened)):


{
    "data": {
        "id": 7,
        "name": "Bar plan",
        "shortname": "bar-plan",
        "start_at": "2026-07-10T00:00:00+02:00",
        "end_at": "2026-07-13T00:00:00+02:00",
        "project_id": 1,
        "events": [
            {
                "id": "9b2f7c1e-4d3a-4f6b-8c2d-1a2b3c4d5e6f",
                "name": "Bar shift",
                "start_at": "2026-07-10T18:00:00+02:00",
                "end_at": "2026-07-10T22:00:00+02:00",
                "area_id": 12,
                "project_id": 1,
                "area": {
                    "id": 12,
                    "name": "Main bar",
                    "shortname": "main-bar"
                },
                "jobs": [],
                "applications": [
                    881
                ],
                "attendees": [
                    "01a1e3a6-efbf-4413-9db1-f36e60489254"
                ]
            }
        ]
    }
}
 

Example response (200, withEvents=1 with all_persons_and_applications_see (shortened)):


{
    "data": {
        "id": 7,
        "name": "Bar plan",
        "shortname": "bar-plan",
        "start_at": "2026-07-10T00:00:00+02:00",
        "end_at": "2026-07-13T00:00:00+02:00",
        "project_id": 1,
        "events": [
            {
                "id": "9b2f7c1e-4d3a-4f6b-8c2d-1a2b3c4d5e6f",
                "name": "Bar shift",
                "start_at": "2026-07-10T18:00:00+02:00",
                "end_at": "2026-07-10T22:00:00+02:00",
                "area_id": 12,
                "project_id": 1,
                "area": {
                    "id": 12,
                    "name": "Main bar",
                    "shortname": "main-bar"
                },
                "jobs": [],
                "applications": [
                    {
                        "id": 881,
                        "project_id": 1,
                        "data": {
                            "name": "Crew North"
                        },
                        "person_id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
                        "members": [
                            "01a1e3a6-efbf-4413-9db1-f36e60489254"
                        ],
                        "application_type_id": 3
                    }
                ],
                "attendees": [
                    {
                        "id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
                        "project_id": 1,
                        "data": {
                            "firstname": "Alex"
                        },
                        "calculated_data": [],
                        "person_types": [
                            "crew"
                        ]
                    }
                ]
            }
        ]
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Plan not visible to the caller):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, Plan not in this project):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/event-plans/{plan_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

plan_id   integer     

The ID of the plan. Example: 16

project   integer     

Project id. Example: 16

plan   integer     

Scheduler plan id. Example: 16

Query Parameters

withEvents   boolean  optional    

Include the full nested events array (v1-shape). Attendees and groups are nested only with all_persons_and_applications_see, IDs otherwise. Default false.

Carries area_ids, the areas of the schedule (FWT-2841). Example: false

List events in a scheduler plan.

requires authentication

Paginated. Default emission per event: area and jobs as full nested resources; attendees as an array of person UUIDs and applications as an array of group IDs. Upgrade attendees / applications to full nested Person / Group resources via the opt-in ?withAttendees=1 / ?withApplications=1 flags (mirrors ApplicationsController's sideload pattern).

The two flags take effect only for callers with the all_persons_and_applications_see permission (or a higher level of it). For every other caller they are ignored and the events keep the ID default — no 403, the plan view check alone grants the event list. ?withCalculatedData=1 rides on ?withApplications=1 and therefore has the same gate: without the permission there are no nested groups and so no calculated_data (FWT-2916, variant (a)).

403 if the caller cannot view the plan (canUserView). 404 if the plan does not belong to the URL's project.

Required API permission: none. A schedule without view roles needs “Read scheduler” (scheduler_see), one with view roles one of those roles; “Manage scheduler” (scheduler_administrate) sees every schedule. Nested people and groups additionally need “Read people and groups” (all_persons_and_applications_see).

Depending on the permission: form fields marked as protected are returned in plain text only with “Read protected fields” (securedata_see) as a direct API permission of the API user (a role does not count); without it their keys are left out of data and calculated_data, also of nested people and groups, and a nested person's name or e-mail or a group's name is null.

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/event-plans/16/events?withAttendees=&withApplications=&withCalculatedData=1&calculatedFields=stage%2Cshow_day%2Cshow_time&per_page=25&page=1&created_since=2026-06-01T00%3A00%3A00%2B00%3A00&updated_since=2026-06-01T00%3A00%3A00%2B00%3A00" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/event-plans/16/events"
);

const params = {
    "withAttendees": "0",
    "withApplications": "0",
    "withCalculatedData": "1",
    "calculatedFields": "stage,show_day,show_time",
    "per_page": "25",
    "page": "1",
    "created_since": "2026-06-01T00:00:00+00:00",
    "updated_since": "2026-06-01T00:00:00+00:00",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/event-plans/16/events';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'withAttendees' => '0',
            'withApplications' => '0',
            'withCalculatedData' => '1',
            'calculatedFields' => 'stage,show_day,show_time',
            'per_page' => '25',
            'page' => '1',
            'created_since' => '2026-06-01T00:00:00+00:00',
            'updated_since' => '2026-06-01T00:00:00+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, withAttendees=1&withApplications=1 without all_persons_and_applications_see (shortened)):


{
    "data": [
        {
            "id": "9b2f7c1e-4d3a-4f6b-8c2d-1a2b3c4d5e6f",
            "name": "Bar shift",
            "start_at": "2026-07-10T18:00:00+02:00",
            "end_at": "2026-07-10T22:00:00+02:00",
            "area_id": 12,
            "project_id": 1,
            "area": {
                "id": 12,
                "name": "Main bar",
                "shortname": "main-bar"
            },
            "jobs": [],
            "applications": [
                881
            ],
            "attendees": [
                "01a1e3a6-efbf-4413-9db1-f36e60489254"
            ]
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (200, withAttendees=1&withApplications=1 with all_persons_and_applications_see (shortened)):


{
    "data": [
        {
            "id": "9b2f7c1e-4d3a-4f6b-8c2d-1a2b3c4d5e6f",
            "name": "Bar shift",
            "start_at": "2026-07-10T18:00:00+02:00",
            "end_at": "2026-07-10T22:00:00+02:00",
            "area_id": 12,
            "project_id": 1,
            "area": {
                "id": 12,
                "name": "Main bar",
                "shortname": "main-bar"
            },
            "jobs": [],
            "applications": [
                {
                    "id": 881,
                    "project_id": 1,
                    "data": {
                        "name": "Crew North"
                    },
                    "person_id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
                    "members": [
                        "01a1e3a6-efbf-4413-9db1-f36e60489254"
                    ],
                    "application_type_id": 3
                }
            ],
            "attendees": [
                {
                    "id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
                    "project_id": 1,
                    "data": {
                        "firstname": "Alex"
                    },
                    "calculated_data": [],
                    "person_types": [
                        "crew"
                    ]
                }
            ]
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (200, withApplications=1&withCalculatedData=1&calculatedFields=stage,show_day,show_time with all_persons_and_applications_see):


{
    "data": [
        {
            "id": 881,
            "scheduler_event_type_id": 4,
            "name": "Night Owls",
            "nameInIcal": "Night Owls",
            "description": null,
            "start_at": "2026-08-14T22:30:00+02:00",
            "end_at": "2026-08-14T23:45:00+02:00",
            "duration": 75,
            "area_id": 12,
            "project_id": 1,
            "data": null,
            "created_at": "2026-05-07T11:24:53+00:00",
            "updated_at": "2026-05-07T11:24:53+00:00",
            "type": {
                "id": 4,
                "shortname": "show"
            },
            "area": {
                "id": 12,
                "name": "Main Stage"
            },
            "jobs": [],
            "applications": [
                {
                    "id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
                    "project_id": 1,
                    "data": {
                        "name": "Night Owls"
                    },
                    "person_id": null,
                    "members": [],
                    "current_step": {
                        "id": 42,
                        "shortname": "CONFIRMED"
                    },
                    "application_type_id": 3,
                    "application_type": {
                        "id": 3,
                        "shortname": "artist"
                    },
                    "created_at": "2026-05-07T11:24:53+00:00",
                    "updated_at": "2026-05-07T11:24:53+00:00",
                    "anonymized_at": null,
                    "deactivated_at": null,
                    "deleted_at": null,
                    "calculated_data": {
                        "stage": "Main Stage",
                        "show_day": "Friday",
                        "show_time": "22:30"
                    }
                }
            ],
            "attendees": []
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Plan not visible to the caller):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, Plan not in this project):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/event-plans/{plan_id}/events

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

plan_id   integer     

The ID of the plan. Example: 16

project   integer     

Project id. Example: 16

plan   integer     

Scheduler plan id (must belong to the project). Example: 16

Query Parameters

withAttendees   boolean  optional    

Upgrade attendees from UUIDs to nested Person resources. Needs all_persons_and_applications_see, ignored without it. Default false. Example: false

withApplications   boolean  optional    

Upgrade the applications array from group IDs to nested Group resources. Needs all_persons_and_applications_see, ignored without it. Default false. Example: false

withCalculatedData   boolean  optional    

Only meaningful alongside withApplications=1, so it needs all_persons_and_applications_see as well and is ignored without it. Keep calculated_data on every nested Group (stored values, data-qualification rules applied as on the Group detail endpoint). Default false. Example: true

calculatedFields   string  optional    

Only meaningful alongside withCalculatedData=1. Comma list (or flat array) of calculated field names to return per nested Group; unknown names are ignored, nested arrays are rejected with 422. Example: stage,show_day,show_time

per_page   integer  optional    

Page size, clamped to 100. Example: 25

page   integer  optional    

Page number (1-indexed). Example: 1

created_since   string  optional    

ISO 8601 timestamp with offset; only records created at or after it. Example: 2026-06-01T00:00:00+00:00

updated_since   string  optional    

ISO 8601 timestamp with offset; only records updated at or after it. Example: 2026-06-01T00:00:00+00:00

List areas in a project.

requires authentication

Paginated list of areas scoped to the project.

Requires area_see (or a higher level of it), the permission that gates areas in the backend; without it 403. The internal fields (internal_info, rent_info, note_on_program_planning) carry no stricter gate there and are returned to every area_see holder.

location is the area's geo point. Groups that are placed on an area (market stands, exhibitors) carry the id of that area in a form field of type area (for example stand_area); join the group list on that id to place the groups on a map. Where the form defines calculation fields over self.areas.<field>.lat / .lng, the group list returns the point per group (withCalculatedData=1).

Required API permission: “Read areas” (area_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/areas?per_page=25&page=1&created_since=2026-06-01T00%3A00%3A00%2B00%3A00&updated_since=2026-06-01T00%3A00%3A00%2B00%3A00" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/areas"
);

const params = {
    "per_page": "25",
    "page": "1",
    "created_since": "2026-06-01T00:00:00+00:00",
    "updated_since": "2026-06-01T00:00:00+00:00",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/areas';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'page' => '1',
            'created_since' => '2026-06-01T00:00:00+00:00',
            'updated_since' => '2026-06-01T00:00:00+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, With area_see (shortened)):


{
    "data": [
        {
            "id": 12,
            "name": "Main bar",
            "shortname": "main-bar",
            "description": null,
            "capacity": 400,
            "area_type_id": 3,
            "area_id": null,
            "color": "#ff9900",
            "internal_info": null,
            "rent_info": null,
            "project_id": 1,
            "created_at": "2026-05-07T11:24:53+02:00",
            "updated_at": "2026-05-07T11:24:53+02:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Without area_see):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Request      

GET api/v2/projects/{project_id}/areas

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

page   integer  optional    

Page number (1-indexed). Example: 1

created_since   string  optional    

ISO 8601 timestamp with offset; only records created at or after it. Example: 2026-06-01T00:00:00+00:00

updated_since   string  optional    

ISO 8601 timestamp with offset; only records updated at or after it. Example: 2026-06-01T00:00:00+00:00

List events scheduled in an area.

requires authentication

Paginated. Each event carries area, jobs, attendees, applications inline (mirrors the v1 emission).

Requires scheduler_see (or a higher level of it), the permission that gates scheduler events in the backend; without it 403. Plan view_roles are not evaluated here: a caller who sees plans only through a plan role reads their events via event-plans/{plan}/events.

attendees and applications depend on the caller: with the all_persons_and_applications_see permission (or a higher level of it) on top they hold the full nested Person / Group resources; every other caller gets attendees as an array of person UUIDs and applications as an array of group IDs. The Group sideload flags (e.g. withMembersCollection) then have nothing to act on.

Required API permission: “Read scheduler” (scheduler_see)

Depending on the permission: form fields marked as protected are returned in plain text only with “Read protected fields” (securedata_see) as a direct API permission of the API user (a role does not count); without it their keys are left out of data and calculated_data, also of nested people and groups, and a nested person's name or e-mail or a group's name is null.

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/areas/16/events?per_page=25&page=1&created_since=2026-06-01T00%3A00%3A00%2B00%3A00&updated_since=2026-06-01T00%3A00%3A00%2B00%3A00" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/areas/16/events"
);

const params = {
    "per_page": "25",
    "page": "1",
    "created_since": "2026-06-01T00:00:00+00:00",
    "updated_since": "2026-06-01T00:00:00+00:00",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/areas/16/events';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'page' => '1',
            'created_since' => '2026-06-01T00:00:00+00:00',
            'updated_since' => '2026-06-01T00:00:00+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, scheduler_see without all_persons_and_applications_see (shortened)):


{
    "data": [
        {
            "id": "9b2f7c1e-4d3a-4f6b-8c2d-1a2b3c4d5e6f",
            "scheduler_event_type_id": 2,
            "name": "Bar shift",
            "nameInIcal": "Bar shift",
            "description": null,
            "start_at": "2026-07-10T18:00:00+02:00",
            "end_at": "2026-07-10T22:00:00+02:00",
            "duration": 240,
            "area_id": 12,
            "project_id": 1,
            "data": [],
            "created_at": "2026-05-07T11:24:53+02:00",
            "updated_at": "2026-05-07T11:24:53+02:00",
            "type": {
                "id": 2,
                "shortname": "shift"
            },
            "area": {
                "id": 12,
                "name": "Main bar",
                "shortname": "main-bar"
            },
            "jobs": [],
            "applications": [
                881
            ],
            "attendees": [
                "01a1e3a6-efbf-4413-9db1-f36e60489254"
            ]
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (200, scheduler_see with all_persons_and_applications_see (shortened)):


{
    "data": [
        {
            "id": "9b2f7c1e-4d3a-4f6b-8c2d-1a2b3c4d5e6f",
            "name": "Bar shift",
            "area_id": 12,
            "project_id": 1,
            "applications": [
                {
                    "id": 881,
                    "project_id": 1,
                    "data": {
                        "name": "Crew North"
                    },
                    "person_id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
                    "members": [
                        "01a1e3a6-efbf-4413-9db1-f36e60489254"
                    ],
                    "application_type_id": 3
                }
            ],
            "attendees": [
                {
                    "id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
                    "project_id": 1,
                    "data": {
                        "firstname": "Alex"
                    },
                    "calculated_data": [],
                    "person_types": [
                        "crew"
                    ]
                }
            ]
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Without scheduler_see):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, Area not in this project):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/areas/{area_id}/events

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

area_id   integer     

The ID of the area. Example: 16

project   integer     

Project id. Example: 16

area   integer     

Area id (must belong to the project). Example: 16

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

page   integer  optional    

Page number (1-indexed). Example: 1

created_since   string  optional    

ISO 8601 timestamp with offset; only records created at or after it. Example: 2026-06-01T00:00:00+00:00

updated_since   string  optional    

ISO 8601 timestamp with offset; only records updated at or after it. Example: 2026-06-01T00:00:00+00:00

List scheduler event types in a project.

requires authentication

Requires scheduler_see (or a higher level of it), the permission that gates event types in the backend; without it 403.

Required API permission: “Read scheduler” (scheduler_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/event-types?per_page=25&page=1&created_since=2026-06-01T00%3A00%3A00%2B00%3A00&updated_since=2026-06-01T00%3A00%3A00%2B00%3A00" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/event-types"
);

const params = {
    "per_page": "25",
    "page": "1",
    "created_since": "2026-06-01T00:00:00+00:00",
    "updated_since": "2026-06-01T00:00:00+00:00",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/event-types';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'page' => '1',
            'created_since' => '2026-06-01T00:00:00+00:00',
            'updated_since' => '2026-06-01T00:00:00+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, With scheduler_see):


{
    "data": [
        {
            "id": 2,
            "name": "Shift",
            "color": "#3366ff",
            "brightness": 102,
            "data": [],
            "project_id": 1,
            "created_at": "2026-05-07T11:24:53+02:00",
            "updated_at": "2026-05-07T11:24:53+02:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Without scheduler_see):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Request      

GET api/v2/projects/{project_id}/event-types

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

page   integer  optional    

Page number (1-indexed). Example: 1

created_since   string  optional    

ISO 8601 timestamp with offset; only records created at or after it. Example: 2026-06-01T00:00:00+00:00

updated_since   string  optional    

ISO 8601 timestamp with offset; only records updated at or after it. Example: 2026-06-01T00:00:00+00:00

Create a scheduler plan (schedule).

requires authentication

Requires scheduler_administrate, like creating a schedule in the backend. The project comes from the URL. area_ids links areas of this project; only events in those areas are part of the schedule. owned_by optionally sets the owner (a backend user with access to the project), as the backend's owner field; without it the schedule has no owner. Limited by the package quotas for schedules, schedule days and areas per schedule (422 on the field when exceeded).

Required API permission: “Manage scheduler” (scheduler_administrate)

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/event-plans" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --data "{
    \"name\": \"Bar shifts\",
    \"shortname\": \"bar\",
    \"description\": \"All bar shifts of the main weekend.\",
    \"start_at\": \"2026-07-10T00:00:00+02:00\",
    \"end_at\": \"2026-07-13T00:00:00+02:00\",
    \"view_roles\": [],
    \"edit_roles\": [],
    \"area_ids\": [
        16
    ],
    \"owned_by\": 42
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/event-plans"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

let body = {
    "name": "Bar shifts",
    "shortname": "bar",
    "description": "All bar shifts of the main weekend.",
    "start_at": "2026-07-10T00:00:00+02:00",
    "end_at": "2026-07-13T00:00:00+02:00",
    "view_roles": [],
    "edit_roles": [],
    "area_ids": [
        16
    ],
    "owned_by": 42
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/event-plans';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'json' => [
            'name' => 'Bar shifts',
            'shortname' => 'bar',
            'description' => 'All bar shifts of the main weekend.',
            'start_at' => '2026-07-10T00:00:00+02:00',
            'end_at' => '2026-07-13T00:00:00+02:00',
            'view_roles' => [],
            'edit_roles' => [],
            'area_ids' => [
                16,
            ],
            'owned_by' => 42,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201, Created):


{
    "data": {
        "id": 7,
        "name": "Bar shifts",
        "shortname": "bar",
        "description": null,
        "start_at": "2026-07-10T00:00:00+02:00",
        "end_at": "2026-07-13T00:00:00+02:00",
        "display_name": ":name",
        "display_people": "name",
        "data": null,
        "view_roles": null,
        "edit_roles": null,
        "project_id": 1,
        "owned_by": null,
        "sort_order": 3,
        "created_at": "2026-06-23T09:00:00+00:00",
        "updated_at": "2026-06-23T09:00:00+00:00",
        "events": null,
        "area_ids": [
            12,
            13
        ]
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Without scheduler_administrate):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "end_at": [
                "The end at field must be a date after start at."
            ]
        }
    }
}
 

Example response (422, Owner not a backend user of the project):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "owned_by": [
                "The selected owned by is invalid."
            ]
        }
    }
}
 

Request      

POST api/v2/projects/{project_id}/event-plans

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Body Parameters

name   string     

Required. Display name of the schedule (max 255 chars). Must not be greater than 255 characters. Example: Bar shifts

shortname   string  optional    

Optional short identifier (max 100 chars). Stored as an empty string when omitted. Must not be greater than 100 characters. Example: bar

description   string  optional    

Optional description. Nullable. Example: All bar shifts of the main weekend.

start_at   string     

Required. Start of the schedule period (ISO 8601). Must be a valid date. Example: 2026-07-10T00:00:00+02:00

end_at   string     

Required. End of the schedule period, after start_at (ISO 8601). Must be a valid date. Must be a date after start_at. Example: 2026-07-13T00:00:00+02:00

view_roles   object  optional    

Optional role identifiers that may see the schedule. Empty or null: everybody with scheduler_see.

edit_roles   object  optional    

Optional role identifiers that may edit the schedule. Empty or null: everybody with scheduler_manage.

area_ids   integer[]  optional    

The id of an existing record in the areas table.

owned_by   integer  optional    

Optional user id of the schedule owner, as the backend's "Owner" field. The owner may always see and edit the schedule; while an owner is set, edit roles and scheduler_manage no longer grant editing (scheduler_administrate still does). Must be a backend user (no API user) with access to this project. Omitted or null: no owner. Example: 42

id   string  optional    
project_id   string  optional    
data   string  optional    
sort_order   string  optional    
jobs   string  optional    
attendees   string  optional    
applications   string  optional    
files   string  optional    
teams   string  optional    
shiftPreset   string  optional    
scheduler   string  optional    

Update a scheduler plan. Both PUT and PATCH route here.

requires authentication

Allowed for whoever may edit the schedule in the backend: scheduler_administrate, the schedule owner, a match in edit_roles, or scheduler_manage when the schedule has no owner and no edit roles. Changing view_roles, edit_roles or owned_by needs scheduler_administrate; the owner alone may not widen access or hand the schedule over. owned_by omitted keeps the owner (also on PUT), null removes it.

Optimistic lock via updated_at; mismatch → 409 optimistic_lock_failed. PUT requires name, start_at and end_at; PATCH keeps omitted fields. area_ids, when sent, replaces the schedule's areas as a whole.

Required API permission: none. Whoever may edit the schedule: “Manage scheduler” (scheduler_administrate), the schedule owner, one of its edit roles, or “Edit scheduler” (scheduler_manage) when the schedule has neither owner nor edit roles. Changing view roles, edit roles or the owner needs “Manage scheduler” (scheduler_administrate).

Example request:
curl --request PUT \
    "https://{instance}.festiwa.re/api/v2/projects/564/event-plans/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Bar shifts\",
    \"shortname\": \"bar\",
    \"description\": \"All bar shifts of the main weekend.\",
    \"start_at\": \"2026-07-10T00:00:00+02:00\",
    \"end_at\": \"2026-07-13T00:00:00+02:00\",
    \"view_roles\": [],
    \"edit_roles\": [],
    \"area_ids\": [
        16
    ],
    \"owned_by\": 42,
    \"updated_at\": \"2026-06-23T09:00:00+00:00\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/event-plans/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "Bar shifts",
    "shortname": "bar",
    "description": "All bar shifts of the main weekend.",
    "start_at": "2026-07-10T00:00:00+02:00",
    "end_at": "2026-07-13T00:00:00+02:00",
    "view_roles": [],
    "edit_roles": [],
    "area_ids": [
        16
    ],
    "owned_by": 42,
    "updated_at": "2026-06-23T09:00:00+00:00"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/event-plans/16';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'name' => 'Bar shifts',
            'shortname' => 'bar',
            'description' => 'All bar shifts of the main weekend.',
            'start_at' => '2026-07-10T00:00:00+02:00',
            'end_at' => '2026-07-13T00:00:00+02:00',
            'view_roles' => [],
            'edit_roles' => [],
            'area_ids' => [
                16,
            ],
            'owned_by' => 42,
            'updated_at' => '2026-06-23T09:00:00+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": 7,
        "name": "Bar shifts (late)",
        "shortname": "bar",
        "description": null,
        "start_at": "2026-07-10T00:00:00+02:00",
        "end_at": "2026-07-13T00:00:00+02:00",
        "display_name": ":name",
        "display_people": "name",
        "data": null,
        "view_roles": null,
        "edit_roles": null,
        "project_id": 1,
        "owned_by": null,
        "sort_order": 3,
        "created_at": "2026-06-23T09:00:00+00:00",
        "updated_at": "2026-06-23T12:00:00+00:00",
        "events": null,
        "area_ids": [
            12
        ]
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Not allowed to edit the plan):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, Plan not in this project):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (409, OptimisticLockFailed):


{
    "error": {
        "code": "optimistic_lock_failed",
        "message": "The resource was modified after your last read. Re-fetch and retry.",
        "errors": {
            "current": {
                "updated_at": "2026-06-23T12:00:00+00:00"
            }
        }
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "updated_at": [
                "The updated at field is required."
            ]
        }
    }
}
 

Request      

PUT api/v2/projects/{project_id}/event-plans/{plan_id}

PATCH api/v2/projects/{project_id}/event-plans/{plan_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

plan_id   integer     

The ID of the plan. Example: 16

project   integer     

Project id. Example: 16

plan   integer     

Scheduler plan id. Example: 16

Body Parameters

name   string     

Required on PUT, optional on PATCH. Display name (max 255 chars). Must not be greater than 255 characters. Example: Bar shifts

shortname   string  optional    

Optional short identifier (max 100 chars). Must not be greater than 100 characters. Example: bar

description   string  optional    

Optional description; null clears it. Example: All bar shifts of the main weekend.

start_at   string     

Required on PUT, optional on PATCH. Start of the schedule period (ISO 8601). Must be a valid date. Example: 2026-07-10T00:00:00+02:00

end_at   string     

Required on PUT, optional on PATCH. End of the schedule period; must stay after the start (ISO 8601). Must be a valid date. Example: 2026-07-13T00:00:00+02:00

view_roles   object  optional    

Optional. Changing it needs scheduler_administrate (the schedule owner alone may not).

edit_roles   object  optional    

Optional. Changing it needs scheduler_administrate (the schedule owner alone may not).

area_ids   integer[]  optional    

The id of an existing record in the areas table.

owned_by   integer  optional    

Optional user id of the schedule owner; null removes the owner, omitted keeps it (also on PUT). Changing it needs scheduler_administrate, as in the backend. Must be a backend user (no API user) with access to this project. Example: 42

updated_at   string     

Required ISO 8601 last-known timestamp (optimistic-lock token). Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-06-23T09:00:00+00:00

id   string  optional    
project_id   string  optional    
data   string  optional    
sort_order   string  optional    
jobs   string  optional    
attendees   string  optional    
applications   string  optional    
files   string  optional    
teams   string  optional    
shiftPreset   string  optional    
scheduler   string  optional    

Delete a scheduler plan.

requires authentication

Requires scheduler_administrate (the backend delete permission) and {"confirm": true}. The plan is soft-deleted. Its events, shifts and areas are NOT deleted: they belong to the project, not to the plan, and other plans may show them.

Required API permission: “Manage scheduler” (scheduler_administrate)

Example request:
curl --request DELETE \
    "https://{instance}.festiwa.re/api/v2/projects/564/event-plans/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"confirm\": true
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/event-plans/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "confirm": true
};

fetch(url, {
    method: "DELETE",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/event-plans/16';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'confirm' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (204, Deleted):

Empty response
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Without scheduler_administrate):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, Plan not in this project):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "confirm": [
                "The confirm field must be accepted."
            ]
        }
    }
}
 

Request      

DELETE api/v2/projects/{project_id}/event-plans/{plan_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

plan_id   integer     

The ID of the plan. Example: 16

project   integer     

Project id. Example: 16

plan   integer     

Scheduler plan id. Example: 16

Body Parameters

confirm   boolean     

Required guard against accidental deletion. Must be exactly true; false or omission returns 422 and deletes nothing. Must be accepted. Example: true

jobs   string  optional    
attendees   string  optional    
applications   string  optional    
files   string  optional    
teams   string  optional    
shiftPreset   string  optional    
scheduler   string  optional    

Create an event in a scheduler plan.

requires authentication

Allowed as in the backend: the caller may edit the schedule (scheduler_administrate, owner, edit role, or scheduler_manage for a schedule without owner and edit roles). With the setting "edit events outside plan permissions" on, any schedule of the project, as long as the caller holds scheduler_manage or may edit at least one schedule of the project (the backend's create rule, which the setting does not widen). The event must show in the schedule, like creating an event in the backend planner: area_id one of the schedule's areas (422 on area_id), the period overlapping the schedule's period (422 on start_at / end_at), and the type accepted by the schedule's event-type filter (422 on scheduler_event_type_id).

Shifts are created with POST /events/{event}/jobs. Jobs, attendees, groups and files are not accepted here (422).

Required API permission: none. Whoever may edit the schedule: “Manage scheduler” (scheduler_administrate), the schedule owner, one of its edit roles, or “Edit scheduler” (scheduler_manage) when the schedule has neither owner nor edit roles. When events may be edited outside schedule permissions (setting): any schedule, for “Edit scheduler” (scheduler_manage) or whoever may edit at least one schedule of the project.

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/event-plans/16/events" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --data "{
    \"area_id\": 12,
    \"name\": \"Bar shift\",
    \"description\": \"Evening bar.\",
    \"start_at\": \"2026-07-10T18:00:00+02:00\",
    \"end_at\": \"2026-07-10T22:00:00+02:00\",
    \"scheduler_event_type_id\": 4
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/event-plans/16/events"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

let body = {
    "area_id": 12,
    "name": "Bar shift",
    "description": "Evening bar.",
    "start_at": "2026-07-10T18:00:00+02:00",
    "end_at": "2026-07-10T22:00:00+02:00",
    "scheduler_event_type_id": 4
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/event-plans/16/events';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'json' => [
            'area_id' => 12,
            'name' => 'Bar shift',
            'description' => 'Evening bar.',
            'start_at' => '2026-07-10T18:00:00+02:00',
            'end_at' => '2026-07-10T22:00:00+02:00',
            'scheduler_event_type_id' => 4,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201, Created):


{
    "data": {
        "id": "9b2f7c1e-4d3a-4f6b-8c2d-1a2b3c4d5e6f",
        "scheduler_event_type_id": null,
        "name": "Bar shift",
        "nameInIcal": "Bar shift",
        "description": null,
        "start_at": "2026-07-10T18:00:00+02:00",
        "end_at": "2026-07-10T22:00:00+02:00",
        "duration": 240,
        "area_id": 12,
        "project_id": 1,
        "data": [],
        "created_at": "2026-06-23T09:00:00+00:00",
        "updated_at": "2026-06-23T09:00:00+00:00",
        "type": null,
        "area": {
            "id": 12,
            "name": "Main bar",
            "shortname": "main-bar"
        },
        "jobs": [],
        "applications": [],
        "attendees": []
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Not allowed to edit the plan's events):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, Plan not in this project):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (422, Area not in the plan):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "area_id": [
                "The area is not part of this schedule. Add it to the schedule first, otherwise the event would not show there."
            ]
        }
    }
}
 

Example response (422, Outside the plan period):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "start_at": [
                "The event lies outside this schedule's period, so the schedule would not show it."
            ],
            "end_at": [
                "The event lies outside this schedule's period, so the schedule would not show it."
            ]
        }
    }
}
 

Request      

POST api/v2/projects/{project_id}/event-plans/{plan_id}/events

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

plan_id   integer     

The ID of the plan. Example: 16

project   integer     

Project id. Example: 16

plan   integer     

Scheduler plan id (must belong to the project). Example: 16

Body Parameters

area_id   integer     

Required. Area of this project; it must be one of the schedule's areas, otherwise the event would not show in the schedule (422 area_id). The id of an existing record in the areas table. Example: 12

name   string  optional    

Optional event name (max 255 chars). Stored as an empty string when omitted. Must not be greater than 255 characters. Example: Bar shift

description   string  optional    

Optional description. Nullable. Example: Evening bar.

start_at   string     

Required. Start (ISO 8601). Must be a valid date. Example: 2026-07-10T18:00:00+02:00

end_at   string     

Required. End, after start_at (ISO 8601). Must be a valid date. Must be a date after start_at. Example: 2026-07-10T22:00:00+02:00

scheduler_event_type_id   integer  optional    

Optional event type of this project. Nullable. The id of an existing record in the s_event_types table. Example: 4

id   string  optional    
project_id   string  optional    
data   string  optional    
jobs   string  optional    
attendees   string  optional    
applications   string  optional    
files   string  optional    
teams   string  optional    
shiftPreset   string  optional    
scheduler   string  optional    

Show a single scheduler event.

requires authentication

Visible to whoever sees one of the schedules that show it (or scheduler_see when no schedule shows it), as in the backend. With the setting "edit events outside plan permissions" on, every user of the project sees every event, as in the backend (an API user restricted to certain person types still only gets those). area and jobs are nested. attendees and applications are nested Person / Group resources only with all_persons_and_applications_see, otherwise arrays of person UUIDs and group IDs.

Required API permission: none. Whoever sees a schedule that shows the event (see the schedule endpoints), “Read scheduler” (scheduler_see) when no schedule shows it; anybody when events may be edited outside schedule permissions (setting). Nested people and groups additionally need “Read people and groups” (all_persons_and_applications_see).

Depending on the permission: form fields marked as protected are returned in plain text only with “Read protected fields” (securedata_see) as a direct API permission of the API user (a role does not count); without it their keys are left out of data and calculated_data, also of nested people and groups, and a nested person's name or e-mail or a group's name is null.

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/events/architecto" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/events/architecto"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/events/architecto';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Without all_persons_and_applications_see):


{
    "data": {
        "id": "9b2f7c1e-4d3a-4f6b-8c2d-1a2b3c4d5e6f",
        "scheduler_event_type_id": null,
        "name": "Bar shift",
        "nameInIcal": "Bar shift",
        "description": null,
        "start_at": "2026-07-10T18:00:00+02:00",
        "end_at": "2026-07-10T22:00:00+02:00",
        "duration": 240,
        "area_id": 12,
        "project_id": 1,
        "data": [],
        "created_at": "2026-06-23T09:00:00+00:00",
        "updated_at": "2026-06-23T09:00:00+00:00",
        "type": null,
        "area": {
            "id": 12,
            "name": "Main bar",
            "shortname": "main-bar"
        },
        "jobs": [],
        "applications": [
            881
        ],
        "attendees": [
            "01a1e3a6-efbf-4413-9db1-f36e60489254"
        ]
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Event not visible to the caller):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, Event not in this project):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/events/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   string     

The ID of the event. Example: architecto

project   integer     

Project id. Example: 16

event   string     

Scheduler event id (UUID). Example: architecto

Update a scheduler event. Both PUT and PATCH route here.

requires authentication

Allowed for whoever may edit one of the schedules that show the event (or scheduler_manage when no schedule shows it), as in the backend. With the setting "edit events outside plan permissions" on, every user of the project may edit every event, as in the backend. A change of area_id, scheduler_event_type_id, start_at or end_at is checked again against the schedules that show the event afterwards: without the setting, moving it into a schedule the caller may not edit, or out of every schedule without scheduler_manage, is a 403. Only the event's own fields are written; shifts have their own endpoints, attendees, groups and files are not accepted (422).

Optimistic lock via updated_at; mismatch → 409 optimistic_lock_failed.

Required API permission: none. Whoever may edit a schedule that shows the event, “Edit scheduler” (scheduler_manage) when no schedule shows it; anybody when events may be edited outside schedule permissions (setting).

Example request:
curl --request PUT \
    "https://{instance}.festiwa.re/api/v2/projects/564/events/architecto" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"area_id\": 12,
    \"name\": \"Bar shift\",
    \"description\": \"Evening bar.\",
    \"start_at\": \"2026-07-10T18:00:00+02:00\",
    \"end_at\": \"2026-07-10T22:00:00+02:00\",
    \"scheduler_event_type_id\": 4,
    \"updated_at\": \"2026-06-23T09:00:00+00:00\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/events/architecto"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "area_id": 12,
    "name": "Bar shift",
    "description": "Evening bar.",
    "start_at": "2026-07-10T18:00:00+02:00",
    "end_at": "2026-07-10T22:00:00+02:00",
    "scheduler_event_type_id": 4,
    "updated_at": "2026-06-23T09:00:00+00:00"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/events/architecto';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'area_id' => 12,
            'name' => 'Bar shift',
            'description' => 'Evening bar.',
            'start_at' => '2026-07-10T18:00:00+02:00',
            'end_at' => '2026-07-10T22:00:00+02:00',
            'scheduler_event_type_id' => 4,
            'updated_at' => '2026-06-23T09:00:00+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": "9b2f7c1e-4d3a-4f6b-8c2d-1a2b3c4d5e6f",
        "scheduler_event_type_id": null,
        "name": "Bar shift (late)",
        "nameInIcal": "Bar shift (late)",
        "description": null,
        "start_at": "2026-07-10T19:00:00+02:00",
        "end_at": "2026-07-10T23:00:00+02:00",
        "duration": 240,
        "area_id": 12,
        "project_id": 1,
        "data": [],
        "created_at": "2026-06-23T09:00:00+00:00",
        "updated_at": "2026-06-23T12:00:00+00:00",
        "type": null,
        "area": {
            "id": 12,
            "name": "Main bar",
            "shortname": "main-bar"
        },
        "jobs": [],
        "applications": [],
        "attendees": []
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Not allowed to edit the event):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, Event not in this project):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (409, OptimisticLockFailed):


{
    "error": {
        "code": "optimistic_lock_failed",
        "message": "The resource was modified after your last read. Re-fetch and retry.",
        "errors": {
            "current": {
                "updated_at": "2026-06-23T12:00:00+00:00"
            }
        }
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "jobs": [
                "The jobs field must be missing."
            ]
        }
    }
}
 

Request      

PUT api/v2/projects/{project_id}/events/{id}

PATCH api/v2/projects/{project_id}/events/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   string     

The ID of the event. Example: architecto

project   integer     

Project id. Example: 16

event   string     

Scheduler event id (UUID). Example: architecto

Body Parameters

area_id   integer     

Required on PUT, optional on PATCH. Area of this project. The id of an existing record in the areas table. Example: 12

name   string  optional    

Optional event name (max 255 chars); null stores an empty name. Must not be greater than 255 characters. Example: Bar shift

description   string  optional    

Optional description; null clears it. Example: Evening bar.

start_at   string     

Required on PUT, optional on PATCH. Start (ISO 8601). Must be a valid date. Example: 2026-07-10T18:00:00+02:00

end_at   string     

Required on PUT, optional on PATCH. End; must stay after the start (ISO 8601). Must be a valid date. Example: 2026-07-10T22:00:00+02:00

scheduler_event_type_id   integer  optional    

Optional event type of this project; null removes the type. The id of an existing record in the s_event_types table. Example: 4

updated_at   string     

Required ISO 8601 last-known timestamp (optimistic-lock token). Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-06-23T09:00:00+00:00

id   string  optional    
project_id   string  optional    
data   string  optional    
jobs   string  optional    
attendees   string  optional    
applications   string  optional    
files   string  optional    
teams   string  optional    
shiftPreset   string  optional    
scheduler   string  optional    

Delete a scheduler event.

requires authentication

Same edit rule as the update. Requires {"confirm": true} (replaces API v1's force=1). 409 event_has_assigned_jobs while a person is assigned to one of its shifts. Otherwise the event and its unassigned shifts are soft-deleted.

Required API permission: none. Whoever may edit a schedule that shows the event, “Edit scheduler” (scheduler_manage) when no schedule shows it; anybody when events may be edited outside schedule permissions (setting).

Example request:
curl --request DELETE \
    "https://{instance}.festiwa.re/api/v2/projects/564/events/architecto" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"confirm\": true
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/events/architecto"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "confirm": true
};

fetch(url, {
    method: "DELETE",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/events/architecto';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'confirm' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (204, Deleted):

Empty response
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Not allowed to edit the event):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, Event not in this project):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (409, Shifts still assigned):


{
    "error": {
        "code": "event_has_assigned_jobs",
        "message": "This event cannot be deleted because people are still assigned to its shifts. Unassign them first. (2)"
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "confirm": [
                "The confirm field must be accepted."
            ]
        }
    }
}
 

Request      

DELETE api/v2/projects/{project_id}/events/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   string     

The ID of the event. Example: architecto

project   integer     

Project id. Example: 16

event   string     

Scheduler event id (UUID). Example: architecto

Body Parameters

confirm   boolean     

Required guard against accidental deletion. Must be exactly true; false or omission returns 422 and deletes nothing. Must be accepted. Example: true

jobs   string  optional    
attendees   string  optional    
applications   string  optional    
files   string  optional    
teams   string  optional    
shiftPreset   string  optional    
scheduler   string  optional    

Create shifts in a scheduler event.

requires authentication

Creates count empty shifts (default 1, max 50), named after the event plus the allowed teams or the event type, as API v1 does. Same edit rule as updating the event. Persons are assigned afterwards with PATCH /jobs/{job}. allowed_teams is ignored while the Teams module is off. Returns the created shifts, unpaginated.

Required API permission: none. Whoever may edit the shift's event (see updating an event).

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/events/architecto/jobs" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --data "{
    \"count\": 3,
    \"allowed_teams\": [
        16
    ]
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/events/architecto/jobs"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

let body = {
    "count": 3,
    "allowed_teams": [
        16
    ]
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/events/architecto/jobs';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'json' => [
            'count' => 3,
            'allowed_teams' => [
                16,
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201, Created):


{
    "data": [
        {
            "id": 501,
            "name": "Bar shift – Bar team",
            "scheduler_event_id": "9b2f7c1e-4d3a-4f6b-8c2d-1a2b3c4d5e6f",
            "allowed_teams": [
                5
            ],
            "person_id": null,
            "checkedin_at": null,
            "accomplished_at": null,
            "checkedin_by": null,
            "accomplished_by": null,
            "checkedin_user_id": null,
            "accomplished_user_id": null,
            "data": null,
            "project_id": 1,
            "created_at": "2026-06-23T09:00:00+00:00",
            "updated_at": "2026-06-23T09:00:00+00:00"
        }
    ]
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Not allowed to edit the event):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, Event not in this project):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "count": [
                "The count field must not be greater than 50."
            ]
        }
    }
}
 

Request      

POST api/v2/projects/{project_id}/events/{event_id}/jobs

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

event_id   string     

The ID of the event. Example: architecto

project   integer     

Project id. Example: 16

event   string     

Scheduler event id (UUID). Example: architecto

Body Parameters

count   integer  optional    

Number of shifts to create (1 to 50). Default 1. Must be at least 1. Must not be greater than 50. Example: 3

allowed_teams   integer[]  optional    

The id of an existing record in the teams table.

id   string  optional    
project_id   string  optional    
person_id   string  optional    
jobs   string  optional    
attendees   string  optional    
applications   string  optional    
files   string  optional    
teams   string  optional    
shiftPreset   string  optional    
scheduler   string  optional    

Update a shift, including the person assignment. Both PUT and PATCH route here.

requires authentication

Same edit rule as the shift's event. Optimistic lock via updated_at; mismatch → 409 optimistic_lock_failed.

Assigning a person (person_id) runs the checks of the backend assignment: the shift's team restriction (while the Teams module is on), overlapping shifts of the person, the project's rest period and daily maximum, and the person's attendance days. A conflict is a 422 job_assignment_conflict whose errors.person_id names the reason (team, time_conflict or attendance). Once work time is tracked on the shift (checkedin_at), the person can neither be removed nor replaced (409 job_has_tracked_work).

allowed_teams is ignored (the stored restriction is kept) while the Teams module is off.

For an API user restricted to certain person types, a person of another type is refused as if it did not exist (422 on person_id), and a shift held by such a person can neither be unassigned nor reassigned (403).

Required API permission: none. Whoever may edit the shift's event (see updating an event).

Example request:
curl --request PUT \
    "https://{instance}.festiwa.re/api/v2/projects/564/jobs/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Bar shift – Bar team\",
    \"allowed_teams\": [
        16
    ],
    \"person_id\": \"01a1e3a6-efbf-4413-9db1-f36e60489254\",
    \"updated_at\": \"2026-06-23T09:00:00+00:00\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/jobs/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "Bar shift – Bar team",
    "allowed_teams": [
        16
    ],
    "person_id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
    "updated_at": "2026-06-23T09:00:00+00:00"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/jobs/16';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'name' => 'Bar shift – Bar team',
            'allowed_teams' => [
                16,
            ],
            'person_id' => '01a1e3a6-efbf-4413-9db1-f36e60489254',
            'updated_at' => '2026-06-23T09:00:00+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Person assigned):


{
    "data": {
        "id": 501,
        "name": "Bar shift – Bar team",
        "scheduler_event_id": "9b2f7c1e-4d3a-4f6b-8c2d-1a2b3c4d5e6f",
        "allowed_teams": [
            5
        ],
        "person_id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
        "checkedin_at": null,
        "accomplished_at": null,
        "checkedin_by": null,
        "accomplished_by": null,
        "checkedin_user_id": null,
        "accomplished_user_id": null,
        "data": null,
        "project_id": 1,
        "created_at": "2026-06-23T09:00:00+00:00",
        "updated_at": "2026-06-23T12:00:00+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Not allowed to edit the shift):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, Shift not in this project):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (409, Tracked work):


{
    "error": {
        "code": "job_has_tracked_work",
        "message": "This shift has tracked work time. The assigned person cannot be changed and the shift cannot be deleted."
    }
}
 

Example response (409, OptimisticLockFailed):


{
    "error": {
        "code": "optimistic_lock_failed",
        "message": "The resource was modified after your last read. Re-fetch and retry.",
        "errors": {
            "current": {
                "updated_at": "2026-06-23T12:00:00+00:00"
            }
        }
    }
}
 

Example response (422, Assignment conflict):


{
    "error": {
        "code": "job_assignment_conflict",
        "message": "The person cannot take this shift.",
        "errors": {
            "person_id": [
                "time_conflict"
            ]
        }
    }
}
 

Request      

PUT api/v2/projects/{project_id}/jobs/{id}

PATCH api/v2/projects/{project_id}/jobs/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   integer     

The ID of the job. Example: 16

project   integer     

Project id. Example: 16

job   integer     

Shift (job) id. Example: 16

Body Parameters

name   string     

Required on PUT, optional on PATCH. Shift name (max 255 chars). Must not be greater than 255 characters. Example: Bar shift – Bar team

allowed_teams   integer[]  optional    

The id of an existing record in the teams table.

person_id   string  optional    

Optional person (UUID) of this project to assign, null to unassign. Checked like the backend assignment: team restriction, overlapping shifts, rest period, daily maximum and attendance (422 job_assignment_conflict). Not changeable once the shift has tracked work (409 job_has_tracked_work). The id of an existing record in the people table. Example: 01a1e3a6-efbf-4413-9db1-f36e60489254

updated_at   string     

Required ISO 8601 last-known timestamp (optimistic-lock token). Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-06-23T09:00:00+00:00

id   string  optional    
project_id   string  optional    
scheduler_event_id   string  optional    
checkedin_at   string  optional    
accomplished_at   string  optional    
jobs   string  optional    
attendees   string  optional    
applications   string  optional    
files   string  optional    
teams   string  optional    
shiftPreset   string  optional    
scheduler   string  optional    

Delete a shift.

requires authentication

Same edit rule as the shift's event. Requires {"confirm": true}. 409 job_assigned while a person is assigned, 409 job_has_tracked_work once work time is tracked on it.

Required API permission: none. Whoever may edit the shift's event (see updating an event).

Example request:
curl --request DELETE \
    "https://{instance}.festiwa.re/api/v2/projects/564/jobs/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"confirm\": true
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/jobs/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "confirm": true
};

fetch(url, {
    method: "DELETE",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/jobs/16';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'confirm' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (204, Deleted):

Empty response
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Not allowed to edit the shift):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, Shift not in this project):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (409, Person assigned):


{
    "error": {
        "code": "job_assigned",
        "message": "This shift cannot be deleted because a person is assigned to it. Unassign the person first."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "confirm": [
                "The confirm field must be accepted."
            ]
        }
    }
}
 

Request      

DELETE api/v2/projects/{project_id}/jobs/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   integer     

The ID of the job. Example: 16

project   integer     

Project id. Example: 16

job   integer     

Shift (job) id. Example: 16

Body Parameters

confirm   boolean     

Required guard against accidental deletion. Must be exactly true; false or omission returns 422 and deletes nothing. Must be accepted. Example: true

jobs   string  optional    
attendees   string  optional    
applications   string  optional    
files   string  optional    
teams   string  optional    
shiftPreset   string  optional    
scheduler   string  optional    

Create a scheduler event type.

requires authentication

Requires scheduler_administrate, the backend permission for event types. brightness is derived from color.

Required API permission: “Manage scheduler” (scheduler_administrate)

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/event-types" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --data "{
    \"name\": \"Shift\",
    \"color\": \"#3366ff\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/event-types"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

let body = {
    "name": "Shift",
    "color": "#3366ff"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/event-types';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'json' => [
            'name' => 'Shift',
            'color' => '#3366ff',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201, Created):


{
    "data": {
        "id": 2,
        "name": "Shift",
        "color": "#3366ff",
        "brightness": 102,
        "data": [],
        "project_id": 1,
        "created_at": "2026-06-23T09:00:00+00:00",
        "updated_at": "2026-06-23T09:00:00+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Without scheduler_administrate):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "color": [
                "The color field is required."
            ]
        }
    }
}
 

Request      

POST api/v2/projects/{project_id}/event-types

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Body Parameters

name   string     

Required. Name of the event type (max 255 chars). Must not be greater than 255 characters. Example: Shift

color   string     

Required. Display colour, e.g. a hex code (max 20 chars). brightness is derived from it. Must not be greater than 20 characters. Example: #3366ff

id   string  optional    
project_id   string  optional    
brightness   string  optional    
data   string  optional    

Update a scheduler event type. Both PUT and PATCH route here.

requires authentication

Requires scheduler_administrate. Optimistic lock via updated_at; mismatch → 409 optimistic_lock_failed.

Required API permission: “Manage scheduler” (scheduler_administrate)

Example request:
curl --request PUT \
    "https://{instance}.festiwa.re/api/v2/projects/564/event-types/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Shift\",
    \"color\": \"#3366ff\",
    \"updated_at\": \"2026-06-23T09:00:00+00:00\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/event-types/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "Shift",
    "color": "#3366ff",
    "updated_at": "2026-06-23T09:00:00+00:00"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/event-types/16';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'name' => 'Shift',
            'color' => '#3366ff',
            'updated_at' => '2026-06-23T09:00:00+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": 2,
        "name": "Late shift",
        "color": "#3366ff",
        "brightness": 102,
        "data": [],
        "project_id": 1,
        "created_at": "2026-06-23T09:00:00+00:00",
        "updated_at": "2026-06-23T12:00:00+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Without scheduler_administrate):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, Event type not in this project):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (409, OptimisticLockFailed):


{
    "error": {
        "code": "optimistic_lock_failed",
        "message": "The resource was modified after your last read. Re-fetch and retry.",
        "errors": {
            "current": {
                "updated_at": "2026-06-23T12:00:00+00:00"
            }
        }
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "updated_at": [
                "The updated at field is required."
            ]
        }
    }
}
 

Request      

PUT api/v2/projects/{project_id}/event-types/{type_id}

PATCH api/v2/projects/{project_id}/event-types/{type_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

type_id   integer     

The ID of the type. Example: 16

project   integer     

Project id. Example: 16

type   integer     

Event type id. Example: 16

Body Parameters

name   string     

Required on PUT, optional on PATCH. Name (max 255 chars). Must not be greater than 255 characters. Example: Shift

color   string     

Required on PUT, optional on PATCH. Display colour (max 20 chars). Must not be greater than 20 characters. Example: #3366ff

updated_at   string     

Required ISO 8601 last-known timestamp (optimistic-lock token). Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-06-23T09:00:00+00:00

id   string  optional    
project_id   string  optional    
brightness   string  optional    
data   string  optional    

Delete a scheduler event type.

requires authentication

Requires scheduler_administrate and {"confirm": true}. 409 event_type_in_use while an event still uses the type. The type is soft-deleted.

Required API permission: “Manage scheduler” (scheduler_administrate)

Example request:
curl --request DELETE \
    "https://{instance}.festiwa.re/api/v2/projects/564/event-types/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"confirm\": true
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/event-types/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "confirm": true
};

fetch(url, {
    method: "DELETE",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/event-types/16';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'confirm' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (204, Deleted):

Empty response
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Without scheduler_administrate):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, Event type not in this project):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (409, In use):


{
    "error": {
        "code": "event_type_in_use",
        "message": "This event type cannot be deleted because events still use it. (4)"
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "confirm": [
                "The confirm field must be accepted."
            ]
        }
    }
}
 

Request      

DELETE api/v2/projects/{project_id}/event-types/{type_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

type_id   integer     

The ID of the type. Example: 16

project   integer     

Project id. Example: 16

type   integer     

Event type id. Example: 16

Body Parameters

confirm   boolean     

Required guard against accidental deletion. Must be exactly true; false or omission returns 422 and deletes nothing. Must be accepted. Example: true

jobs   string  optional    
attendees   string  optional    
applications   string  optional    
files   string  optional    
teams   string  optional    
shiftPreset   string  optional    
scheduler   string  optional    

List the area types of a project.

requires authentication

Requires area_see (or a higher level of it).

Required API permission: “Read areas” (area_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/area-types?per_page=25&page=1" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/area-types"
);

const params = {
    "per_page": "25",
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/area-types';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": 31,
            "name": "Stage",
            "shortname": null,
            "description": null,
            "data": [],
            "project_id": 1,
            "created_at": "2026-06-23T09:00:00+00:00",
            "updated_at": "2026-06-23T09:00:00+00:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Without area_see):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Request      

GET api/v2/projects/{project_id}/area-types

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

page   integer  optional    

Page number (1-indexed). Example: 1

Create an area type.

requires authentication

Requires area_administrate. Only the name is writable (as API v1).

Required API permission: “Manage areas” (area_administrate)

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/area-types" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --data "{
    \"name\": \"Stage\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/area-types"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

let body = {
    "name": "Stage"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/area-types';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'json' => [
            'name' => 'Stage',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201, Created):


{
    "data": {
        "id": 31,
        "name": "Stage",
        "shortname": null,
        "description": null,
        "data": [],
        "project_id": 1,
        "created_at": "2026-06-23T09:00:00+00:00",
        "updated_at": "2026-06-23T09:00:00+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Without area_administrate):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "name": [
                "The name field is required."
            ]
        }
    }
}
 

Request      

POST api/v2/projects/{project_id}/area-types

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Body Parameters

name   string     

Required. Name of the area type (max 255 chars). Must not be greater than 255 characters. Example: Stage

id   string  optional    
project_id   string  optional    
typeable_model   string  optional    
data   string  optional    

Show a single area type.

requires authentication

Requires area_see.

Required API permission: “Read areas” (area_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/area-types/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/area-types/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/area-types/16';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": 31,
        "name": "Stage",
        "shortname": null,
        "description": null,
        "data": [],
        "project_id": 1,
        "created_at": "2026-06-23T09:00:00+00:00",
        "updated_at": "2026-06-23T09:00:00+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Without area_see):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, Area type not in this project):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/area-types/{type_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

type_id   integer     

The ID of the type. Example: 16

project   integer     

Project id. Example: 16

type   integer     

Area type id. Example: 16

Update an area type. Both PUT and PATCH route here.

requires authentication

Requires area_manage. Optimistic lock via updated_at; mismatch → 409 optimistic_lock_failed.

Required API permission: “Edit areas” (area_manage)

Example request:
curl --request PUT \
    "https://{instance}.festiwa.re/api/v2/projects/564/area-types/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Stage\",
    \"updated_at\": \"2026-06-23T09:00:00+00:00\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/area-types/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "Stage",
    "updated_at": "2026-06-23T09:00:00+00:00"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/area-types/16';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'name' => 'Stage',
            'updated_at' => '2026-06-23T09:00:00+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": 31,
        "name": "Main stage",
        "shortname": null,
        "description": null,
        "data": [],
        "project_id": 1,
        "created_at": "2026-06-23T09:00:00+00:00",
        "updated_at": "2026-06-23T12:00:00+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Without area_manage):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, Area type not in this project):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (409, OptimisticLockFailed):


{
    "error": {
        "code": "optimistic_lock_failed",
        "message": "The resource was modified after your last read. Re-fetch and retry.",
        "errors": {
            "current": {
                "updated_at": "2026-06-23T12:00:00+00:00"
            }
        }
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "updated_at": [
                "The updated at field is required."
            ]
        }
    }
}
 

Request      

PUT api/v2/projects/{project_id}/area-types/{type_id}

PATCH api/v2/projects/{project_id}/area-types/{type_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

type_id   integer     

The ID of the type. Example: 16

project   integer     

Project id. Example: 16

type   integer     

Area type id. Example: 16

Body Parameters

name   string     

Required on PUT, optional on PATCH. Name (max 255 chars). Must not be greater than 255 characters. Example: Stage

updated_at   string     

Required ISO 8601 last-known timestamp (optimistic-lock token). Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-06-23T09:00:00+00:00

id   string  optional    
project_id   string  optional    
typeable_model   string  optional    
data   string  optional    

Delete an area type.

requires authentication

Requires area_administrate and {"confirm": true}. 409 area_type_in_use while an area still uses the type.

Required API permission: “Manage areas” (area_administrate)

Example request:
curl --request DELETE \
    "https://{instance}.festiwa.re/api/v2/projects/564/area-types/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"confirm\": true
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/area-types/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "confirm": true
};

fetch(url, {
    method: "DELETE",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/area-types/16';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'confirm' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (204, Deleted):

Empty response
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Without area_administrate):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, Area type not in this project):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (409, In use):


{
    "error": {
        "code": "area_type_in_use",
        "message": "This area type cannot be deleted because areas still use it. (3)"
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "confirm": [
                "The confirm field must be accepted."
            ]
        }
    }
}
 

Request      

DELETE api/v2/projects/{project_id}/area-types/{type_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

type_id   integer     

The ID of the type. Example: 16

project   integer     

Project id. Example: 16

type   integer     

Area type id. Example: 16

Body Parameters

confirm   boolean     

Required guard against accidental deletion. Must be exactly true; false or omission returns 422 and deletes nothing. Must be accepted. Example: true

jobs   string  optional    
attendees   string  optional    
applications   string  optional    
files   string  optional    
teams   string  optional    
shiftPreset   string  optional    
scheduler   string  optional    

Supply

Paginated list of supplies (resources) in a project.

requires authentication

A supply is the type of equipment ("Label printer"), a supply item is the single physical device. category_ids lets a client group the list without a second call.

Required API permission: “Read supplies” (app\modules\supply\policies\supply_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/supplies?per_page=25&page=1" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/supplies"
);

const params = {
    "per_page": "25",
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/supplies';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": 7,
            "project_id": 5,
            "name": "Label printer",
            "description": "Zebra label printers",
            "image_url": null,
            "requires_existing_stock": true,
            "allow_partial_duration": false,
            "orderable_from": null,
            "orderable_to": null,
            "category_ids": [
                2
            ],
            "created_at": "2026-07-27T09:00:00+00:00",
            "updated_at": "2026-07-27T09:00:00+00:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Request      

GET api/v2/projects/{project_id}/supplies

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

page   integer  optional    

Page number (1-indexed). Example: 1

Paginated list of supply categories that carry at least one supply of this project.

requires authentication

Required API permission: “Read supplies” (app\modules\supply\policies\supply_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/supply-categories?per_page=25&page=1" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/supply-categories"
);

const params = {
    "per_page": "25",
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/supply-categories';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": 2,
            "name": "Technology",
            "description": "Printers, scanners, radios",
            "image_url": null,
            "supply_ids": [
                7,
                8
            ],
            "created_at": "2026-07-27T09:00:00+00:00",
            "updated_at": "2026-07-27T09:00:00+00:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Request      

GET api/v2/projects/{project_id}/supply-categories

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

page   integer  optional    

Page number (1-indexed). Example: 1

Paginated list of the single devices belonging to one supply.

requires authentication

latest_tracking_event tells a client who currently holds the device. It is null while the instance has no supply tracking booked.

Required API permission: “Read supplies” (app\modules\supply\policies\supply_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/supplies/16/items?per_page=25&page=1" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/supplies/16/items"
);

const params = {
    "per_page": "25",
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/supplies/16/items';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": 17,
            "supply_id": 7,
            "name": "Zebra ZD421 #3",
            "description": null,
            "serial_number": "ZD421-0099123",
            "tag_number": "A1B2C3D4",
            "owner_type": "team",
            "owner_id": "4",
            "owner_name": "Crew Technik",
            "available_from": null,
            "available_to": null,
            "image_url": null,
            "label_url": "https://demo.festiwa.re/supply-label/5/7/17.pdf",
            "latest_tracking_event": null,
            "created_at": "2026-07-27T09:00:00+00:00",
            "updated_at": "2026-07-27T09:00:00+00:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/supplies/{supply_id}/items

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

supply_id   integer     

The ID of the supply. Example: 16

project   integer     

Project id. Example: 16

supply   integer     

Supply (resource) id. Example: 16

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

page   integer  optional    

Page number (1-indexed). Example: 1

Register a single device on a supply.

requires authentication

This is the write half of the "register device" kiosk flow: pick a resource, name the device, let the server assign a scannable tag, optionally set an owner, then print the label from label_url.

Tag assignment: send tag_number to use your own code, send nothing to have one generated (this bypasses the project setting "generate tag numbers"), or send generate_tag: false to create an item without a tag.

Owner: either owner_type + owner_id, or owner_person_tag_number for the scan path. The owner must belong to the same project.

Required API permission: “Manage supplies” (app\modules\supply\policies\supply_administrate)

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/supplies/16/items" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --data "{
    \"name\": \"Zebra ZD421 #3\",
    \"description\": \"Label printer, 300 dpi\",
    \"serial_number\": \"ZD421-0099123\",
    \"tag_number\": \"A1B2C3D4\",
    \"generate_tag\": true,
    \"owner_type\": \"team\",
    \"owner_id\": \"17\",
    \"owner_person_tag_number\": \"0010000101\",
    \"available_from\": \"2026-08-01T08:00:00+02:00\",
    \"available_to\": \"2026-08-10T20:00:00+02:00\",
    \"image_url\": \"https:\\/\\/storage.example.com\\/supply\\/zd421.jpg\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/supplies/16/items"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

let body = {
    "name": "Zebra ZD421 #3",
    "description": "Label printer, 300 dpi",
    "serial_number": "ZD421-0099123",
    "tag_number": "A1B2C3D4",
    "generate_tag": true,
    "owner_type": "team",
    "owner_id": "17",
    "owner_person_tag_number": "0010000101",
    "available_from": "2026-08-01T08:00:00+02:00",
    "available_to": "2026-08-10T20:00:00+02:00",
    "image_url": "https:\/\/storage.example.com\/supply\/zd421.jpg"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/supplies/16/items';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'json' => [
            'name' => 'Zebra ZD421 #3',
            'description' => 'Label printer, 300 dpi',
            'serial_number' => 'ZD421-0099123',
            'tag_number' => 'A1B2C3D4',
            'generate_tag' => true,
            'owner_type' => 'team',
            'owner_id' => '17',
            'owner_person_tag_number' => '0010000101',
            'available_from' => '2026-08-01T08:00:00+02:00',
            'available_to' => '2026-08-10T20:00:00+02:00',
            'image_url' => 'https://storage.example.com/supply/zd421.jpg',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201, Created):


{
    "data": {
        "id": 17,
        "supply_id": 7,
        "name": "Zebra ZD421 #3",
        "description": null,
        "serial_number": "ZD421-0099123",
        "tag_number": "A1B2C3D4",
        "owner_type": "team",
        "owner_id": "4",
        "owner_name": "Crew Technik",
        "available_from": null,
        "available_to": null,
        "image_url": null,
        "label_url": "https://demo.festiwa.re/supply-label/5/7/17.pdf",
        "latest_tracking_event": null,
        "created_at": "2026-07-27T09:00:00+00:00",
        "updated_at": "2026-07-27T09:00:00+00:00"
    }
}
 

Example response (400, InvalidScan):


{
    "error": {
        "code": "bad_request",
        "message": "Dieser Pass ist nicht mehr aktuell."
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "tag_number": [
                "The tag number has already been taken."
            ]
        }
    }
}
 

Request      

POST api/v2/projects/{project_id}/supplies/{supply_id}/items

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

supply_id   integer     

The ID of the supply. Example: 16

project   integer     

Project id. Example: 16

supply   integer     

Supply (resource) id. Example: 16

Body Parameters

name   string     

Required. Device name shown in the backend and on the label. Must not be greater than 255 characters. Example: Zebra ZD421 #3

description   string  optional    

Optional free-text description. Example: Label printer, 300 dpi

serial_number   string  optional    

Optional manufacturer serial. Unique per resource. Must not be greater than 255 characters. Example: ZD421-0099123

tag_number   string  optional    

Optional scannable QR/NFC code, unique instance-wide. Colons are stripped. Omit it to let the server generate one, or send generate_tag: false to create an item without a tag. Must not be greater than 255 characters. Example: A1B2C3D4

generate_tag   boolean  optional    

Defaults to true when no tag_number is sent: the server assigns a random unique tag even if the project setting "generate tag numbers" is off. Send false to deliberately create an item without a tag. Example: true

owner_type   string  optional    

Owner party type: person, application or team. Required together with owner_id. This field is required when owner_id is present. Example: team

Must be one of:
  • person
  • application
  • team
owner_id   string  optional    

Id of the owning party (Person UUID, Group id or Team id). Must belong to the same project. This field is required when owner_type is present. Example: 17

owner_person_tag_number   string  optional    

Scanned NFC tag or printed pass number of the owning person — the kiosk path for "this is mine". Cannot be combined with owner_type/owner_id. Example: 0010000101

available_from   string  optional    

Optional start of the availability window. Must be a valid date. Example: 2026-08-01T08:00:00+02:00

available_to   string  optional    

Optional end of the availability window. Must be a valid date. Must be a date after or equal to available_from. Example: 2026-08-10T20:00:00+02:00

image_url   string  optional    

Optional photo URL, also used as the label logo source. Must not be greater than 255 characters. Example: https://storage.example.com/supply/zd421.jpg

id   string  optional    
supply_id   string  optional    
project_id   string  optional    

Show a single device by id, without knowing its supply.

requires authentication

The kiosk scans a tag, gets the id from the tracking response, and re-reads the item here to refresh owner and holder.

Required API permission: “Read supplies” (app\modules\supply\policies\supply_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/supply-items/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/supply-items/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/supply-items/16';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": 17,
        "supply_id": 7,
        "name": "Zebra ZD421 #3",
        "description": null,
        "serial_number": "ZD421-0099123",
        "tag_number": "A1B2C3D4",
        "owner_type": "team",
        "owner_id": "4",
        "owner_name": "Crew Technik",
        "available_from": null,
        "available_to": null,
        "image_url": null,
        "label_url": "https://demo.festiwa.re/supply-label/5/7/17.pdf",
        "latest_tracking_event": null,
        "created_at": "2026-07-27T09:00:00+00:00",
        "updated_at": "2026-07-27T09:00:00+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/supply-items/{supplyItem_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

supplyItem_id   integer     

The ID of the supplyItem. Example: 16

project   integer     

Project id. Example: 16

supplyItem   integer     

Supply item id. Example: 16

Book a tracking event for one or many devices: hand out, take back, send to maintenance.

requires authentication

One event is written per item, so a kiosk can scan a whole box of radios and hand them to one person in a single call. issued, received and transferred need a person (by id or by scan); every other event type is a stock movement and works without one.

Everything a booking touches belongs to the project in the URL: an item or a person of another project answers 404 like an unknown one, an area or a supply order of another project 422. Nothing is written then, not even for the other items of a bulk booking.

Required API permission: “Hand out supplies” (app\modules\supply\policies\supplytracking_manage)

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/supply-tracking-events" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --data "{
    \"event_type\": \"issued\",
    \"supply_item_ids\": [
        16
    ],
    \"supply_item_tag_numbers\": [
        \"architecto\"
    ],
    \"person_id\": \"550e8400-e29b-41d4-a716-446655440000\",
    \"person_tag_number\": \"0010000101\",
    \"supply_order_id\": 42,
    \"area_id\": 3,
    \"stock_location\": \"Warehouse A, Shelf 3\",
    \"geolocation\": \"51.3397,12.3731\",
    \"w3w\": \"filled.count.soap\",
    \"annotations\": \"Cracked housing, sent to repair\",
    \"image_url\": \"https:\\/\\/storage.example.com\\/tracking\\/img001.jpg\",
    \"tracked_at\": \"2026-07-15T10:30:00+02:00\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/supply-tracking-events"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

let body = {
    "event_type": "issued",
    "supply_item_ids": [
        16
    ],
    "supply_item_tag_numbers": [
        "architecto"
    ],
    "person_id": "550e8400-e29b-41d4-a716-446655440000",
    "person_tag_number": "0010000101",
    "supply_order_id": 42,
    "area_id": 3,
    "stock_location": "Warehouse A, Shelf 3",
    "geolocation": "51.3397,12.3731",
    "w3w": "filled.count.soap",
    "annotations": "Cracked housing, sent to repair",
    "image_url": "https:\/\/storage.example.com\/tracking\/img001.jpg",
    "tracked_at": "2026-07-15T10:30:00+02:00"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/supply-tracking-events';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'json' => [
            'event_type' => 'issued',
            'supply_item_ids' => [
                16,
            ],
            'supply_item_tag_numbers' => [
                'architecto',
            ],
            'person_id' => '550e8400-e29b-41d4-a716-446655440000',
            'person_tag_number' => '0010000101',
            'supply_order_id' => 42,
            'area_id' => 3,
            'stock_location' => 'Warehouse A, Shelf 3',
            'geolocation' => '51.3397,12.3731',
            'w3w' => 'filled.count.soap',
            'annotations' => 'Cracked housing, sent to repair',
            'image_url' => 'https://storage.example.com/tracking/img001.jpg',
            'tracked_at' => '2026-07-15T10:30:00+02:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201, Created):


{
    "data": [
        {
            "id": 901,
            "supply_item_id": 17,
            "supply_order_id": null,
            "event_type": "issued",
            "person_id": "550e8400-e29b-41d4-a716-446655440000",
            "user_id": 3,
            "area_id": null,
            "stock_location": null,
            "geolocation": null,
            "w3w": null,
            "annotations": null,
            "image_url": null,
            "tracked_at": "2026-07-27T09:00:00+00:00",
            "created_at": "2026-07-27T09:00:00+00:00",
            "updated_at": "2026-07-27T09:00:00+00:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (400, InvalidScan):


{
    "error": {
        "code": "bad_request",
        "message": "Dieser Pass ist nicht mehr aktuell."
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (404, PersonOfAnotherProject):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "person_tag_number": [
                "The person tag number field is required."
            ]
        }
    }
}
 

Example response (422, AreaOfAnotherProject):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "area_id": [
                "The selected area id is invalid."
            ]
        }
    }
}
 

Request      

POST api/v2/projects/{project_id}/supply-tracking-events

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Body Parameters

event_type   string     

One of: issued, received, stocked, destocked, maintenance, disposed, lost, found, transferred. issued, received and transferred require a person. Example: issued

Must be one of:
  • issued
  • received
  • stocked
  • destocked
  • maintenance
  • disposed
  • lost
  • found
  • transferred
supply_item_ids   integer[]  optional    

The id of an existing record in the s_supply_items table.

supply_item_tag_numbers   string[]  optional    

The tag_number of an existing record in the s_supply_items table.

person_id   string  optional    

UUID of the counterpart person. Required for issued/received/transferred unless person_tag_number is sent. The id of an existing record in the people table. Example: 550e8400-e29b-41d4-a716-446655440000

person_tag_number   string  optional    

Scanned NFC tag or printed pass number of the counterpart person. Example: 0010000101

supply_order_id   integer  optional    

Optional supply order this booking belongs to. The id of an existing record in the s_supply_orders table. Example: 42

area_id   integer  optional    

Optional area where the event happened. The id of an existing record in the areas table. Example: 3

stock_location   string  optional    

Free-text storage location. Example: Warehouse A, Shelf 3

geolocation   string  optional    

GPS coordinates of the event. Example: 51.3397,12.3731

w3w   string  optional    

what3words address. Example: filled.count.soap

annotations   string  optional    

Free-text note, e.g. the damage found during maintenance. Example: Cracked housing, sent to repair

image_url   string  optional    

URL of a photo documenting the event. Example: https://storage.example.com/tracking/img001.jpg

tracked_at   string  optional    

When the event happened. Defaults to now — send it when replaying an offline queue. Must be a valid date. Example: 2026-07-15T10:30:00+02:00

Teams

Paginated list of teams in a project.

requires authentication

Added for the supply kiosk's owner picker ("this device belongs to team X"); it is a plain project-scoped list and useful to any client that needs team names and ids.

Required API permission: “Read teams” (team_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/teams?per_page=25&page=1" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/teams"
);

const params = {
    "per_page": "25",
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/teams';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": 4,
            "project_id": 5,
            "name": "Crew Technik",
            "shortname": "tech",
            "description": null,
            "email": null,
            "team_type_id": 2,
            "team_id": null,
            "order": 100,
            "created_at": "2026-07-27T09:00:00+00:00",
            "updated_at": "2026-07-27T09:00:00+00:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Request      

GET api/v2/projects/{project_id}/teams

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

page   integer  optional    

Page number (1-indexed). Example: 1

A single team of a project.

requires authentication

Same fields as the list, plus the identity relations inline and shallow: parent_team (the team this one sits under) and team_type, each {id, shortname, name} or null. Members are a separate endpoint (GET teams/{team}/members).

Required API permission: “Read teams” (team_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/teams/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/teams/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/teams/16';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": 4,
        "project_id": 5,
        "name": "Crew Technik",
        "shortname": "tech",
        "description": null,
        "email": null,
        "team_type_id": 2,
        "team_id": 3,
        "order": 100,
        "created_at": "2026-07-27T09:00:00+00:00",
        "updated_at": "2026-07-27T09:00:00+00:00",
        "parent_team": {
            "id": 3,
            "shortname": "crew",
            "name": "Crew"
        },
        "team_type": {
            "id": 2,
            "shortname": "department",
            "name": "Department"
        }
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/teams/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   integer     

The ID of the team. Example: 16

project   integer     

Project id. Example: 16

team   integer     

Team id. Example: 16

Paginated list of the members of a team.

requires authentication

Members are the team's staff memberships (the backend's "Teammitglieder"), each with its team role and role dates. Volunteer assignments of the contribution portal (suggested/assigned/confirmed) are not part of this list. Removed memberships are not listed. id is the membership id, person a shallow person (name and e-mail fields hidden by data qualification come back null). A type-restricted API access lists only people of its types.

Required API permission: “Read teams” (team_see) and “Read people and groups” (all_persons_and_applications_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/teams/16/members?per_page=25&page=1" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/teams/16/members"
);

const params = {
    "per_page": "25",
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/teams/16/members';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": 731,
            "person": {
                "id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
                "firstname": "Anna",
                "lastname": "Muster",
                "email": "anna@example.com"
            },
            "team_role": {
                "id": 1,
                "shortname": "lead",
                "name": "Team lead"
            },
            "has_role_since": "2026-06-01",
            "has_role_until": null,
            "created_at": "2026-06-01T09:00:00+00:00",
            "updated_at": "2026-06-01T09:00:00+00:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/teams/{team_id}/members

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

team_id   integer     

The ID of the team. Example: 16

project   integer     

Project id. Example: 16

team   integer     

Team id. Example: 16

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

page   integer  optional    

Page number (1-indexed). Example: 1

Add a person to a team.

requires authentication

Creates the membership (201). When the person already is a member, the call is idempotent: the existing membership is returned (200) and the fields sent in the body (team_role, has_role_since, has_role_until) update it; fields left out stay as they are. A person is never a member twice, also under concurrent calls. Same effect as assigning the person in the backend: calculated fields over the person's teams are recalculated.

To change role or dates of an existing membership without overwriting someone else's change, send the membership's updated_at as last read: a mismatch returns 409 optimistic_lock_failed with the current updated_at and writes nothing. Without updated_at the last writer wins.

This is staff membership, not the volunteer assignment (suggest/confirm) of the contribution portal. Team roles are instance-wide (GET /team-roles). The person in the response is {id} only unless you also hold all_persons_and_applications_see.

Required API permission: “Manage team members” (team_manage)

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/teams/16/members" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --data "{
    \"person_id\": \"01a1e3a6-efbf-4413-9db1-f36e60489254\",
    \"team_role\": \"lead\",
    \"has_role_since\": \"2026-06-01\",
    \"has_role_until\": \"2026-08-31\",
    \"updated_at\": \"2026-06-01T09:00:00+00:00\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/teams/16/members"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

let body = {
    "person_id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
    "team_role": "lead",
    "has_role_since": "2026-06-01",
    "has_role_until": "2026-08-31",
    "updated_at": "2026-06-01T09:00:00+00:00"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/teams/16/members';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'json' => [
            'person_id' => '01a1e3a6-efbf-4413-9db1-f36e60489254',
            'team_role' => 'lead',
            'has_role_since' => '2026-06-01',
            'has_role_until' => '2026-08-31',
            'updated_at' => '2026-06-01T09:00:00+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Already a member (updated or unchanged)):


{
    "data": {
        "id": 731,
        "person": {
            "id": "01a1e3a6-efbf-4413-9db1-f36e60489254"
        },
        "team_role": {
            "id": 2,
            "shortname": "deputy",
            "name": "Deputy"
        },
        "has_role_since": "2026-06-01",
        "has_role_until": null,
        "created_at": "2026-06-01T09:00:00+00:00",
        "updated_at": "2026-06-02T10:00:00+00:00"
    }
}
 

Example response (201, Created):


{
    "data": {
        "id": 731,
        "person": {
            "id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
            "firstname": "Anna",
            "lastname": "Muster",
            "email": "anna@example.com"
        },
        "team_role": {
            "id": 1,
            "shortname": "lead",
            "name": "Team lead"
        },
        "has_role_since": "2026-06-01",
        "has_role_until": null,
        "created_at": "2026-06-01T09:00:00+00:00",
        "updated_at": "2026-06-01T09:00:00+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (409, OptimisticLockFailed):


{
    "error": {
        "code": "optimistic_lock_failed",
        "message": "The resource was modified after your last read. Re-fetch and retry.",
        "errors": {
            "current": {
                "updated_at": "2026-06-02T10:00:00+00:00"
            }
        }
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "person_id": [
                "The selected person_id is not a person of this project."
            ],
            "team_role": [
                "The selected team_role is unknown."
            ]
        }
    }
}
 

Request      

POST api/v2/projects/{project_id}/teams/{team_id}/members

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

team_id   integer     

The ID of the team. Example: 16

project   integer     

Project id. Example: 16

team   integer     

Team id. Example: 16

Body Parameters

person_id   string     

Required. UUID of a person of this project. Must be a valid UUID. Example: 01a1e3a6-efbf-4413-9db1-f36e60489254

team_role   string  optional    

Optional team role, as id or shortname (GET /team-roles). null clears the role of an existing membership; left out, it stays. Example: lead

has_role_since   string  optional    

Optional start date of the role (Y-m-d). null clears it; left out, it stays. Must be a valid date in the format Y-m-d. Example: 2026-06-01

has_role_until   string  optional    

Optional end date of the role (Y-m-d), not before has_role_since. null clears it; left out, it stays. Must be a valid date in the format Y-m-d. Example: 2026-08-31

updated_at   string  optional    

Optional optimistic-lock token for a re-add: the updated_at of the membership as last read (ISO 8601). When the person already is a member and the stored membership changed since, the call returns 409 optimistic_lock_failed and writes nothing. Ignored when the membership is created. Send it whenever you change role or dates of an existing membership. Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-06-01T09:00:00+00:00

Remove a person from a team.

requires authentication

Ends the person's membership (the backend's "remove from team"): the membership is soft-deleted, calculated fields over the person's teams are recalculated. Requires confirm: true in the body. A person who is not a member returns 404.

Required API permission: “Manage team members” (team_manage)

Example request:
curl --request DELETE \
    "https://{instance}.festiwa.re/api/v2/projects/564/teams/16/members/architecto" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"confirm\": true
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/teams/16/members/architecto"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "confirm": true
};

fetch(url, {
    method: "DELETE",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/teams/16/members/architecto';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'confirm' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (204, Removed):

Empty response
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotAMember):


{
    "error": {
        "code": "not_found",
        "message": "Person is not a member of this team."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "confirm": [
                "The confirm field must be accepted."
            ]
        }
    }
}
 

Request      

DELETE api/v2/projects/{project_id}/teams/{team_id}/members/{person_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

team_id   integer     

The ID of the team. Example: 16

person_id   string     

The ID of the person. Example: architecto

project   integer     

Project id. Example: 16

team   integer     

Team id. Example: 16

person   string     

Person UUID. Example: architecto

Body Parameters

confirm   boolean     

Required guard against accidental removal. Must be exactly true; false or omission returns 422 and the membership stays. Must be accepted. Example: true

Paginated list of team roles.

requires authentication

The roles a team membership can carry (team_role on POST teams/{team}/members). Team roles are instance-wide: they belong to no project, so the list is the same in every project. The project in the URL only scopes access (your project allow-list applies).

Required API permission: “Read teams” (team_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/team-roles?per_page=25&page=1" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/team-roles"
);

const params = {
    "per_page": "25",
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/team-roles';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": 1,
            "name": "Team lead",
            "shortname": "lead",
            "description": null
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Request      

GET api/v2/projects/{project_id}/team-roles

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

page   integer  optional    

Page number (1-indexed). Example: 1

Access Control

Check a scanned person against this device's access gates.

requires authentication

The "Scan Access" page of the check-in app. Send the scanned NFC chip UID or pass QR value as code, or a person_id for a manual lookup. The answer is always HTTP 200 — an unknown or superseded badge is a scan outcome, not a request error.

status is one of:

Gates of level access count only while the instance's contract includes the Accesses module; without it the device decides on its access groups alone (identify-only if it has none).

Which person fields appear is an instance setting (access_scan_show_*); disabled fields are absent from the payload entirely rather than nulled.

Required API permission: “Check access” (check_person_access)

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/access-checks" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --data "{
    \"code\": \"04A1B2C3D4E5F6\",
    \"person_id\": \"550e8400-e29b-41d4-a716-446655440000\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/access-checks"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

let body = {
    "code": "04A1B2C3D4E5F6",
    "person_id": "550e8400-e29b-41d4-a716-446655440000"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/access-checks';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'json' => [
            'code' => '04A1B2C3D4E5F6',
            'person_id' => '550e8400-e29b-41d4-a716-446655440000',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Granted):


{
    "data": {
        "status": "granted",
        "person": {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "firstname": "Alex",
            "lastname": "Rieger",
            "fullname": "Alex Rieger",
            "person_types": [
                "Crew"
            ],
            "access_groups": [
                {
                    "id": 104,
                    "name": "Backstage",
                    "shortname": "BS"
                }
            ]
        },
        "matched_gates": [
            {
                "id": 104,
                "project_id": 7,
                "name": "Backstage",
                "shortname": "BS",
                "level": "access_group"
            }
        ],
        "required_gates": [
            {
                "id": 104,
                "project_id": 7,
                "name": "Backstage",
                "shortname": "BS",
                "level": "access_group"
            }
        ],
        "fields": [
            "person_types",
            "access_groups"
        ]
    }
}
 

Example response (200, Denied):


{
    "data": {
        "status": "denied",
        "person": {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "firstname": "Alex",
            "lastname": "Rieger",
            "fullname": "Alex Rieger",
            "person_types": [
                "Visitor"
            ],
            "access_groups": [
                {
                    "id": 99,
                    "name": "Camping",
                    "shortname": "CA"
                }
            ]
        },
        "matched_gates": [],
        "required_gates": [
            {
                "id": 104,
                "project_id": 7,
                "name": "Backstage",
                "shortname": "BS",
                "level": "access_group"
            }
        ],
        "fields": [
            "person_types",
            "access_groups"
        ]
    }
}
 

Example response (200, Devalidated):


{
    "data": {
        "status": "tag_devalidated",
        "person": null,
        "matched_gates": [],
        "required_gates": [],
        "fields": [
            "person_types",
            "access_groups"
        ]
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "code": [
                "The code field is required when person id is not present."
            ]
        }
    }
}
 

Request      

POST api/v2/projects/{project_id}/access-checks

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Body Parameters

code   string  optional    

Scanned value: NFC chip UID or the QR value of a printed pass. Colons are stripped. This field is required when person_id is not present. Must not be greater than 255 characters. Example: 04A1B2C3D4E5F6

person_id   string  optional    

Person to check instead of a scan, for a manual lookup. Mutually exclusive with code. This field is required when code is not present. The id of an existing record in the people table. Example: 550e8400-e29b-41d4-a716-446655440000

Offline dataset for the "Scan Access" page: every scannable person of a project with their codes and access groups.

requires authentication

This is a full snapshot, paginated — not a delta. Deliberately so: a revoked access group or a devalidated badge is a deletion, and an incremental feed that only ships changed rows would leave the removed ones sitting in the device's IndexedDB, letting somebody through a gate they were taken off hours ago. Getting deletions right needs tombstones on three tables; until then the honest primitive is a snapshot the device swaps in wholesale.

To avoid re-downloading it every minute, poll {@see version()} — one cheap request that returns the dataset's fingerprint — and only refetch when it changed.

codes holds every value that resolves to this person when scanned: valid NFC chip UIDs plus the numbers of printed passes (a pass whose QR was never mirrored into nfc_tags still resolves server-side, so it must resolve offline too).

Required API permission: “Check access” (check_person_access)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/access-holders?per_page=100&page=1" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/access-holders"
);

const params = {
    "per_page": "100",
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/access-holders';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '100',
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "firstname": "Alex",
            "lastname": "Rieger",
            "fullname": "Alex Rieger",
            "person_types": [
                "Crew"
            ],
            "access_groups": [
                {
                    "id": 104,
                    "name": "Backstage",
                    "shortname": "BS"
                }
            ],
            "access_group_ids": [
                104
            ],
            "codes": [
                "04A1B2C3D4E5F6",
                "0070000123"
            ]
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 100,
        "total": 1,
        "last_page": 1,
        "version": "7:2026-08-01T18:32:18+00:00",
        "fields": [
            "person_types",
            "access_groups"
        ]
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Request      

GET api/v2/projects/{project_id}/access-holders

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 100

page   integer  optional    

Page number (1-indexed). Example: 1

Fingerprint of the current dataset — poll this instead of refetching the snapshot.

requires authentication

The value is opaque; compare it for equality and nothing else. It changes whenever a person, an access-group assignment, a badge or a pass in this project changes.

Required API permission: “Check access” (check_person_access)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/access-holders/version" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/access-holders/version"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/access-holders/version';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "version": "7:2026-08-01T18:32:18+00:00",
        "total": 842
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Request      

GET api/v2/projects/{project_id}/access-holders/version

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Projects

List projects the authenticated caller can access.

requires authentication

Filtered by ProjectContext::getAllowedProjectIdsForUser(). Callers without an explicit user_projects restriction receive every project on the instance. Use any returned id as the {project} parameter for project-nested v2 endpoints.

Required API permission: none. Any API user. Lists only the projects the API user may use (its project access).

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects?per_page=25&page=1&created_since=2026-06-01T00%3A00%3A00%2B00%3A00&updated_since=2026-06-01T00%3A00%3A00%2B00%3A00" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects"
);

const params = {
    "per_page": "25",
    "page": "1",
    "created_since": "2026-06-01T00:00:00+00:00",
    "updated_since": "2026-06-01T00:00:00+00:00",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'page' => '1',
            'created_since' => '2026-06-01T00:00:00+00:00',
            'updated_since' => '2026-06-01T00:00:00+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (500):

Show headers
cache-control: no-cache, private
content-type: application/json
access-control-allow-origin: *
access-control-expose-headers: Cache-Control, Content-Language, Content-Type, Expires, Last-Modified, Pragma
x-request-id: f5ff7d19-80d1-45fe-a71d-b9481a01ade9
 

{
    "message": "An error occurred and was reported automatically.<br>(Event ID: b498c36880b24130b7bb10cc1d4c7264)<br>We usually resolve errors within a few hours.<br>Please try again later!"
}
 

Request      

GET api/v2/projects

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

page   integer  optional    

Page number (1-indexed). Example: 1

created_since   string  optional    

ISO 8601 timestamp with offset; only records created at or after it. Example: 2026-06-01T00:00:00+00:00

updated_since   string  optional    

ISO 8601 timestamp with offset; only records updated at or after it. Example: 2026-06-01T00:00:00+00:00

Read the project settings.

requires authentication

Every setting the API exposes and this instance offers, with its stored value or, when none is stored, its default. Upload settings return the stored file path (or null); they cannot be changed here. Code templates (mail, ticket, pass and label templates, mail layout, calculated-field templates), secrets and payment terminals are never returned. available_person_types and available_application_types are returned only to users with settings_administrate.

updated_at is the lock token for PATCH; the ETag header can be sent back as If-Match. withFields=1 adds per setting its tab, type, options and whether you may change it (writable, admin = admin role only, read_only).

Rate limited per user (api-v2-config-read).

Required API permission: “Read and change project settings” (app\modules\projects\policies\project_manage)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/settings?withFields=" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/settings"
);

const params = {
    "withFields": "0",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/settings';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'withFields' => '0',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "project_id": 5,
        "updated_at": "2026-11-09T10:00:00+00:00",
        "settings": {
            "frontend_event_name": "Summer Open Air",
            "coupons_enabled": true,
            "ticket_swap_lock_hours": 48,
            "available_languages": [
                "de",
                "en"
            ],
            "invoice_payment_iban": null
        }
    }
}
 

Example response (200, WithFields):


{
    "data": {
        "project_id": 5,
        "updated_at": "2026-11-09T10:00:00+00:00",
        "settings": {
            "coupons_enabled": true,
            "invoice_prefix": "SOA-"
        },
        "fields": {
            "coupons_enabled": {
                "tab": "shop",
                "type": "boolean",
                "access": "writable",
                "multi_language": false
            },
            "invoice_prefix": {
                "tab": "shop",
                "type": "text",
                "access": "admin",
                "multi_language": false
            }
        }
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Example response (429, TooManyRequests):


{
    "error": {
        "code": "too_many_requests",
        "message": "Too many requests."
    }
}
 

Request      

GET api/v2/projects/{project_id}/settings

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 5

Query Parameters

withFields   boolean  optional    

Add fields: tab, type, access and options per setting. Example: false

Change project settings.

requires authentication

Sparse merge: only the settings you send change; null resets one to its default. Send the updated_at you read (optimistic lock); a newer stored version answers 409 optimistic_lock_failed. An If-Match header with the ETag of your read is checked as well. Only values that differ from the current ones are written.

Values are validated as in the backend: the setting's type and own rules, select options of this project (ticket types, areas, event types, form fields of another project are refused). An unknown or hidden setting, a read-only one and one this instance does not offer answer 422, naming the setting.

Billing settings and module switches (invoice_*, payment methods, pass_module_enabled, reseller_shop_enabled, orders_returnable …, access: admin in fields) need the admin role; every change of them is logged. invoice_payment_iban and invoice_payment_payee are never writable.

dry_run=true validates and reports would_change without writing.

The response has the shape of GET (with the new updated_at). Rate limited per user (api-v2-config-write).

Required API permission: “Read and change project settings” (app\modules\projects\policies\project_manage)

Example request:
curl --request PATCH \
    "https://{instance}.festiwa.re/api/v2/projects/564/settings" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "If-Match: \&quot;3f2c…\&quot; Optional: the `ETag` of your last read." \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"settings\": {
        \"coupons_enabled\": true,
        \"ticket_swap_lock_hours\": 24
    },
    \"updated_at\": \"2026-11-09T10:00:00+00:00\",
    \"dry_run\": false
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/settings"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "If-Match": "&quot;3f2c…&quot; Optional: the `ETag` of your last read.",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "settings": {
        "coupons_enabled": true,
        "ticket_swap_lock_hours": 24
    },
    "updated_at": "2026-11-09T10:00:00+00:00",
    "dry_run": false
};

fetch(url, {
    method: "PATCH",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/settings';
$response = $client->patch(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'If-Match' => '"3f2c…" Optional: the `ETag` of your last read.',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'settings' => [
                'coupons_enabled' => true,
                'ticket_swap_lock_hours' => 24,
            ],
            'updated_at' => '2026-11-09T10:00:00+00:00',
            'dry_run' => false,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Saved):


{
    "data": {
        "project_id": 5,
        "updated_at": "2026-11-09T10:05:00+00:00",
        "settings": {
            "coupons_enabled": true,
            "ticket_swap_lock_hours": 24
        }
    }
}
 

Example response (200, DryRun):


{
    "data": {
        "dry_run": true,
        "would_change": {
            "ticket_swap_lock_hours": {
                "from": 48,
                "to": 24
            }
        },
        "updated_at": "2026-11-09T10:00:00+00:00",
        "settings": {
            "coupons_enabled": true,
            "ticket_swap_lock_hours": 48
        }
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (403, AdminOnly):


{
    "error": {
        "code": "permission_denied",
        "message": "Only the admin role may change these settings: invoice_prefix."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Example response (409, OptimisticLockFailed):


{
    "error": {
        "code": "optimistic_lock_failed",
        "message": "The resource was modified after your last read. Re-fetch and retry.",
        "errors": {
            "current": {
                "updated_at": "2026-11-09T10:05:00+00:00"
            }
        }
    }
}
 

Example response (422, Invalid):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "settings.ticket_template": [
                "Unknown setting."
            ],
            "settings.invoice_payment_iban": [
                "This setting is read-only through the API."
            ]
        }
    }
}
 

Example response (429, TooManyRequests):


{
    "error": {
        "code": "too_many_requests",
        "message": "Too many requests."
    }
}
 

Request      

PATCH api/v2/projects/{project_id}/settings

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

If-Match        

Example: "3f2c…" Optional: theETagof your last read.

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 5

Body Parameters

settings   object     

The settings to change, by key (see GET).

updated_at   string     

Optimistic lock: the updated_at you read. Example: 2026-11-09T10:00:00+00:00

dry_run   boolean  optional    

Validate only: report would_change, write nothing. Example: false

Comments

Paginated comments of a Group, oldest first.

requires authentication

Same shape and rules as the Person comments.

Required API permission: “Read people and groups” (all_persons_and_applications_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/applications/16/comments?per_page=25&updated_since=2026-06-01T00%3A00%3A00%2B00%3A00&created_since=2026-06-01T00%3A00%3A00%2B00%3A00" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"per_page\": 16,
    \"updated_since\": \"2026-11-19T01:25:40+01:00\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/applications/16/comments"
);

const params = {
    "per_page": "25",
    "updated_since": "2026-06-01T00:00:00+00:00",
    "created_since": "2026-06-01T00:00:00+00:00",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "per_page": 16,
    "updated_since": "2026-11-19T01:25:40+01:00"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/applications/16/comments';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'updated_since' => '2026-06-01T00:00:00+00:00',
            'created_since' => '2026-06-01T00:00:00+00:00',
        ],
        'json' => [
            'per_page' => 16,
            'updated_since' => '2026-11-19T01:25:40+01:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": 8813,
            "text": "Stage plan received.",
            "author": {
                "id": 3,
                "name": "Backoffice"
            },
            "source": "user",
            "created_at": "2026-06-23T09:00:00+00:00",
            "updated_at": "2026-06-23T09:00:00+00:00",
            "edited_at": null
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "updated_since": [
                "The updated since field must match the format Y-m-d\\TH:i:sP."
            ]
        }
    }
}
 

Request      

GET api/v2/projects/{project_id}/applications/{application_id}/comments

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

application_id   integer     

The ID of the application. Example: 16

project   integer     

Project id. Example: 16

application   integer     

Group id. Example: 16

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

updated_since   string  optional    

ISO 8601 timestamp with offset; only comments updated at or after it. Example: 2026-06-01T00:00:00+00:00

created_since   string  optional    

ISO 8601 timestamp with offset; only records created at or after it. Example: 2026-06-01T00:00:00+00:00

Body Parameters

per_page   integer  optional    

Must be at least 1. Example: 16

updated_since   string  optional    

Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-11-19T01:25:40+01:00

Paginated comments of a Person, oldest first.

requires authentication

author is the backend user who wrote the comment ({id, name}), or null for system comments. source is user or system accordingly. A note saved with a workflow transition carries the acting user and reads user; it cannot be told apart from a comment typed in the backend. Soft-deleted comments are not listed.

Required API permission: “Read people and groups” (all_persons_and_applications_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/people/architecto/comments?per_page=25&updated_since=2026-06-01T00%3A00%3A00%2B00%3A00&created_since=2026-06-01T00%3A00%3A00%2B00%3A00" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"per_page\": 16,
    \"updated_since\": \"2026-11-19T01:25:40+01:00\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/people/architecto/comments"
);

const params = {
    "per_page": "25",
    "updated_since": "2026-06-01T00:00:00+00:00",
    "created_since": "2026-06-01T00:00:00+00:00",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "per_page": 16,
    "updated_since": "2026-11-19T01:25:40+01:00"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/people/architecto/comments';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'updated_since' => '2026-06-01T00:00:00+00:00',
            'created_since' => '2026-06-01T00:00:00+00:00',
        ],
        'json' => [
            'per_page' => 16,
            'updated_since' => '2026-11-19T01:25:40+01:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": 8812,
            "text": "Approved via partner integration.",
            "author": {
                "id": 14,
                "name": "People sync"
            },
            "source": "user",
            "created_at": "2026-06-23T09:00:00+00:00",
            "updated_at": "2026-06-23T09:00:00+00:00",
            "edited_at": null
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "updated_since": [
                "The updated since field must match the format Y-m-d\\TH:i:sP."
            ]
        }
    }
}
 

Request      

GET api/v2/projects/{project_id}/people/{person_id}/comments

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

person_id   string     

The ID of the person. Example: architecto

project   integer     

Project id. Example: 16

person   string     

Person UUID. Example: architecto

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

updated_since   string  optional    

ISO 8601 timestamp with offset; only comments updated at or after it. Example: 2026-06-01T00:00:00+00:00

created_since   string  optional    

ISO 8601 timestamp with offset; only records created at or after it. Example: 2026-06-01T00:00:00+00:00

Body Parameters

per_page   integer  optional    

Must be at least 1. Example: 16

updated_since   string  optional    

Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-11-19T01:25:40+01:00

Contracts

Paginated list of contracts in a project.

requires authentication

subject ({type: person|application, id}) is what the contract is about; the ids in related.contracts of people and groups are these subjects' contracts, so ?person= and ?application= return exactly those. status is the contract state (draft, approved, signed, set_without_signature, canceled, …). Content, signatures and signing IPs are not part of the API. All filters combine (AND).

Required API permission: “List contracts” (contract_manage)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/contracts?per_page=25&status=signed%2Cset_without_signature&updated_since=2026-06-01T00%3A00%3A00%2B00%3A00&person=01a1e3a6-efbf-4413-9db1-f36e60489254&application=812&partner=01a1e3a6-efbf-4413-9db1-f36e60489254&created_since=2026-06-01T00%3A00%3A00%2B00%3A00" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"per_page\": 16,
    \"status\": \"architecto\",
    \"statuses\": [
        \"declined_by_owner\"
    ],
    \"updated_since\": \"2026-11-19T01:25:41+01:00\",
    \"person\": \"a4855dc5-0acb-33c3-b921-f4291f719ca0\",
    \"application\": 66,
    \"partner\": \"977e5426-8d13-3824-86aa-b092f8ae52c5\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/contracts"
);

const params = {
    "per_page": "25",
    "status": "signed,set_without_signature",
    "updated_since": "2026-06-01T00:00:00+00:00",
    "person": "01a1e3a6-efbf-4413-9db1-f36e60489254",
    "application": "812",
    "partner": "01a1e3a6-efbf-4413-9db1-f36e60489254",
    "created_since": "2026-06-01T00:00:00+00:00",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "per_page": 16,
    "status": "architecto",
    "statuses": [
        "declined_by_owner"
    ],
    "updated_since": "2026-11-19T01:25:41+01:00",
    "person": "a4855dc5-0acb-33c3-b921-f4291f719ca0",
    "application": 66,
    "partner": "977e5426-8d13-3824-86aa-b092f8ae52c5"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/contracts';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'status' => 'signed,set_without_signature',
            'updated_since' => '2026-06-01T00:00:00+00:00',
            'person' => '01a1e3a6-efbf-4413-9db1-f36e60489254',
            'application' => '812',
            'partner' => '01a1e3a6-efbf-4413-9db1-f36e60489254',
            'created_since' => '2026-06-01T00:00:00+00:00',
        ],
        'json' => [
            'per_page' => 16,
            'status' => 'architecto',
            'statuses' => [
                'declined_by_owner',
            ],
            'updated_since' => '2026-11-19T01:25:41+01:00',
            'person' => 'a4855dc5-0acb-33c3-b921-f4291f719ca0',
            'application' => 66,
            'partner' => '977e5426-8d13-3824-86aa-b092f8ae52c5',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": 326,
            "contract_number": "V-2026-0042",
            "status": "signed",
            "contract_type": {
                "id": 4,
                "shortname": "ARTIST",
                "name": "Artist contract"
            },
            "subject": {
                "type": "application",
                "id": "812"
            },
            "partner_id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
            "owner_id": "7a2f4d2e-0000-4000-8000-000000000002",
            "pdf_available": true,
            "sent_at": "2026-05-02T10:00:00+02:00",
            "approved_at": "2026-05-01T09:00:00+02:00",
            "partner_feedback_at": null,
            "owner_signed_at": "2026-05-03T12:00:00+02:00",
            "partner_signed_at": "2026-05-02T18:00:00+02:00",
            "owner_set_at": "2026-05-03T12:00:00+02:00",
            "owner_declined_at": null,
            "partner_declined_at": null,
            "owner_revoked_at": null,
            "partner_revoked_at": null,
            "canceled_at": null,
            "paid_at": null,
            "owner_fulfilled_at": null,
            "partner_fulfilled_at": null,
            "fulfilled_at": null,
            "created_at": "2026-05-01T09:00:00+02:00",
            "updated_at": "2026-05-03T12:00:00+02:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "statuses.0": [
                "The selected statuses.0 is invalid."
            ]
        }
    }
}
 

Request      

GET api/v2/projects/{project_id}/contracts

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

status   string  optional    

One or several comma-separated states. Example: signed,set_without_signature

updated_since   string  optional    

ISO 8601 timestamp with offset; contracts updated at or after it. Example: 2026-06-01T00:00:00+00:00

person   string  optional    

Contracts about this Person (UUID) — the ids in the person's related.contracts. Example: 01a1e3a6-efbf-4413-9db1-f36e60489254

application   integer  optional    

Contracts about this Group — the ids in the group's related.contracts. Example: 812

partner   string  optional    

Contracts whose partner is this Person (UUID). Example: 01a1e3a6-efbf-4413-9db1-f36e60489254

created_since   string  optional    

ISO 8601 timestamp with offset; only records created at or after it. Example: 2026-06-01T00:00:00+00:00

Body Parameters

per_page   integer  optional    

Must be at least 1. Example: 16

status   string  optional    

Example: architecto

statuses   string[]  optional    
Must be one of:
  • draft
  • approved
  • declined_by_owner
  • declined_by_partner
  • feedback_by_partner
  • signed_by_owner
  • signed_by_partner
  • signed
  • set_without_signature
  • revoked_by_owner
  • revoked_by_partner
  • paid
  • fulfilled_by_owner
  • fulfilled_by_partner
  • fulfilled
  • canceled
updated_since   string  optional    

Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-11-19T01:25:41+01:00

person   string  optional    

Must be a valid UUID. Example: a4855dc5-0acb-33c3-b921-f4291f719ca0

application   integer  optional    

Must be at least 1. Example: 66

partner   string  optional    

Must be a valid UUID. Example: 977e5426-8d13-3824-86aa-b092f8ae52c5

Paginated list of the contract types of a project.

requires authentication

partner_type names who signs a contract of this type: kind is person or application (a group), id and shortname are the person or group type. The ids match contract_type.id on contracts. Template, layout and settings are not part of the API.

Required API permission: “Read contract types” (contracttype_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/contract-types?per_page=25&created_since=2026-06-01T00%3A00%3A00%2B00%3A00&updated_since=2026-06-01T00%3A00%3A00%2B00%3A00" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/contract-types"
);

const params = {
    "per_page": "25",
    "created_since": "2026-06-01T00:00:00+00:00",
    "updated_since": "2026-06-01T00:00:00+00:00",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/contract-types';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'created_since' => '2026-06-01T00:00:00+00:00',
            'updated_since' => '2026-06-01T00:00:00+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": 4,
            "shortname": "ARTIST",
            "name": "Artist contract",
            "description": null,
            "active": true,
            "is_signable": true,
            "partner_type": {
                "kind": "application",
                "id": 17,
                "shortname": "artist"
            },
            "created_at": "2026-05-01T09:00:00+02:00",
            "updated_at": "2026-05-03T12:00:00+02:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "created_since": [
                "The created since field must match the format Y-m-d\\TH:i:sP."
            ]
        }
    }
}
 

Request      

GET api/v2/projects/{project_id}/contract-types

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

created_since   string  optional    

ISO 8601 timestamp with offset; only records created at or after it. Example: 2026-06-01T00:00:00+00:00

updated_since   string  optional    

ISO 8601 timestamp with offset; only records updated at or after it. Example: 2026-06-01T00:00:00+00:00

Show one contract, including its state and the timestamps of every step.

requires authentication

Required API permission: “Read contracts” (contract_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/contracts/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/contracts/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/contracts/16';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": 326,
        "contract_number": "V-2026-0042",
        "status": "signed",
        "contract_type": {
            "id": 4,
            "shortname": "ARTIST",
            "name": "Artist contract"
        },
        "subject": {
            "type": "application",
            "id": "812"
        },
        "partner_id": "01a1e3a6-efbf-4413-9db1-f36e60489254",
        "owner_id": "7a2f4d2e-0000-4000-8000-000000000002",
        "pdf_available": true,
        "sent_at": "2026-05-02T10:00:00+02:00",
        "approved_at": "2026-05-01T09:00:00+02:00",
        "partner_feedback_at": null,
        "owner_signed_at": "2026-05-03T12:00:00+02:00",
        "partner_signed_at": "2026-05-02T18:00:00+02:00",
        "owner_set_at": "2026-05-03T12:00:00+02:00",
        "owner_declined_at": null,
        "partner_declined_at": null,
        "owner_revoked_at": null,
        "partner_revoked_at": null,
        "canceled_at": null,
        "paid_at": null,
        "owner_fulfilled_at": null,
        "partner_fulfilled_at": null,
        "fulfilled_at": null,
        "created_at": "2026-05-01T09:00:00+02:00",
        "updated_at": "2026-05-03T12:00:00+02:00"
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/contracts/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   integer     

The ID of the contract. Example: 16

project   integer     

Project id. Example: 16

contract   integer     

Contract id. Example: 326

Download the stored PDF of a finalised contract.

requires authentication

Only contracts the owner has finalised (signed or set) carry a stored PDF — the legally relevant document, never re-rendered. 404 for drafts and other contracts without one (pdf_available: false). Nothing is rendered or saved by this call.

Required API permission: “Read contracts” (contract_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/contracts/16/pdf" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/contracts/16/pdf"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/contracts/16/pdf';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


[binary PDF]
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/contracts/{contract_id}/pdf

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

contract_id   integer     

The ID of the contract. Example: 16

project   integer     

Project id. Example: 16

contract   integer     

Contract id. Example: 326

Form Definitions

Validate a form definition.

requires authentication

Runs the deterministic rule set (docs/form-definition-validator-rules.md, ids FD-*) against the stored form definition and returns every finding:

Each finding names its rule, the field and a JSON path into the definition. Findings on a stored definition describe the current state; data-impact findings appear when a change is checked (dry run of an update).

Additionally needs access to the form's person or group type. Rate limited per user (api-v2-config-read).

Required API permission: “Read forms” (formdefinition_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/form-definitions/16/validation" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/form-definitions/16/validation"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/form-definitions/16/validation';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "form_definition_id": 42,
        "valid": false,
        "requires_confirm_data_loss": false,
        "errors": [
            {
                "rule": "FD-L03",
                "severity": "reject",
                "field": null,
                "path": "data.settings.app.triggers.shirt_size.conditions.0.field",
                "message": "A condition of the visibility rule of \"shirt_size\" refers to \"merch\", which is not a field of this form."
            }
        ],
        "warnings": [
            {
                "rule": "FD-C04",
                "severity": "warn",
                "field": "shirt_size",
                "path": "data.fields.shirt_size.label",
                "message": "The label has no text for the active language(s): en."
            }
        ],
        "data_impact": []
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Example response (429, TooManyRequests):


{
    "error": {
        "code": "too_many_requests",
        "message": "Too many requests."
    }
}
 

Request      

GET api/v2/projects/{project_id}/form-definitions/{formDefinition_id}/validation

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

formDefinition_id   integer     

The ID of the formDefinition. Example: 16

project   integer     

Project id. Example: 16

formDefinition   integer     

Form definition id. Example: 42

List the form definitions of a project.

requires authentication

Only forms of the person and group types the user may see (as in the backend). data is left out; add withData=1 to get it.

Rate limited per user (api-v2-config-read).

Required API permission: “Read forms” (formdefinition_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/form-definitions?model=person&withData=&per_page=25&created_since=2026-06-01T00%3A00%3A00%2B00%3A00&updated_since=2026-06-01T00%3A00%3A00%2B00%3A00" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"model\": \"person\",
    \"withData\": false
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/form-definitions"
);

const params = {
    "model": "person",
    "withData": "0",
    "per_page": "25",
    "created_since": "2026-06-01T00:00:00+00:00",
    "updated_since": "2026-06-01T00:00:00+00:00",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "model": "person",
    "withData": false
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/form-definitions';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'model' => 'person',
            'withData' => '0',
            'per_page' => '25',
            'created_since' => '2026-06-01T00:00:00+00:00',
            'updated_since' => '2026-06-01T00:00:00+00:00',
        ],
        'json' => [
            'model' => 'person',
            'withData' => false,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": 42,
            "project_id": 5,
            "name": "Crew",
            "description": null,
            "model": "person",
            "type_shortname": "CrewPerson",
            "related_form_id": null,
            "url_shortname": "crew-2026",
            "tab_label": {
                "de": "Crew",
                "en": "Crew"
            },
            "published": true,
            "published_from": null,
            "published_to": null,
            "created_at": "2026-01-10T09:00:00+00:00",
            "updated_at": "2026-10-08T09:00:00+00:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 25,
        "total": 1
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (429, TooManyRequests):


{
    "error": {
        "code": "too_many_requests",
        "message": "Too many requests."
    }
}
 

Request      

GET api/v2/projects/{project_id}/form-definitions

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Query Parameters

model   string  optional    

Only person forms (person) or group forms (group). Example: person

withData   boolean  optional    

Include data (fields + settings) per form. Example: false

per_page   integer  optional    

Page size (1–100, default 25). Example: 25

created_since   string  optional    

ISO 8601 timestamp with offset; only records created at or after it. Example: 2026-06-01T00:00:00+00:00

updated_since   string  optional    

ISO 8601 timestamp with offset; only records updated at or after it. Example: 2026-06-01T00:00:00+00:00

Body Parameters

model   string  optional    

Example: person

Must be one of:
  • person
  • group
withData   boolean  optional    

Example: false

Show a form definition.

requires authentication

Everything the write endpoint takes, in the stored format: data (fields + settings), texts per language, publication window — plus the read-only functions and calculation (null, or the state of a running recalculation of the calculated fields).

Additionally needs access to the form's person or group type.

Required API permission: “Read forms” (formdefinition_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/form-definitions/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/form-definitions/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/form-definitions/16';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": 42,
        "project_id": 5,
        "name": "Crew",
        "description": null,
        "model": "person",
        "type_shortname": "CrewPerson",
        "related_form_id": null,
        "url_shortname": "crew-2026",
        "tab_label": {
            "de": "Crew",
            "en": "Crew"
        },
        "published": true,
        "published_from": null,
        "published_to": null,
        "created_at": "2026-01-10T09:00:00+00:00",
        "updated_at": "2026-10-08T09:00:00+00:00",
        "html_intro": {
            "de": "<p>Hallo</p>"
        },
        "success_response": null,
        "unpublished_content": null,
        "functions": null,
        "calculation": null,
        "data": {
            "fields": {
                "firstname": {
                    "id": "868f3b29-26d0-4cc9-b377-82751e94b758",
                    "name": "firstname",
                    "type": "text",
                    "label": {
                        "de": "Vorname",
                        "en": "First name"
                    },
                    "views": [
                        "index",
                        "detail",
                        "edit",
                        "app"
                    ],
                    "tab": "name_and_contact"
                }
            },
            "settings": {
                "app": {
                    "triggers": []
                },
                "tabOrder": [
                    "name_and_contact"
                ]
            }
        }
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/form-definitions/{formDefinition_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

formDefinition_id   integer     

The ID of the formDefinition. Example: 16

project   integer     

Project id. Example: 16

formDefinition   integer     

Form definition id. Example: 42

Update a form definition.

requires authentication

PUT and PATCH both route here; PUT requires name, tab_label and data, PATCH keeps what it omits. data is replaced as a whole.

Every write runs the form definition validator (docs/form-definition-validator-rules.md):

When the request changes the fields and the calculated fields of this form are being recalculated, it answers 409 calculation_in_progress with the progress and a Retry-After header (rule FD-X01) — a save would abort and restart the calculation. A dry run still works.

Every save is written to the form's change log (who, when, before/after), like an edit in the backend. Renamed fields move their values. Calculated fields recalculate in the background only when the request changes the fields; editing attributes alone (name, texts, publication) does not recalculate.

model and to_type (the form's type) cannot be changed.

Additionally needs access to the form's person or group type. Rate limited per user (api-v2-config-write).

Required API permission: “Edit forms” (formdefinition_manage)

Example request:
curl --request PUT \
    "https://{instance}.festiwa.re/api/v2/projects/564/form-definitions/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Crew registration\",
    \"description\": \"Main crew form\",
    \"tab_label\": {
        \"de\": \"Crew\",
        \"en\": \"Crew\"
    },
    \"url_shortname\": \"crew-2026\",
    \"published\": true,
    \"published_from\": \"2026-03-01T00:00:00+01:00\",
    \"published_to\": \"2026-06-30T23:59:00+02:00\",
    \"html_intro\": {
        \"de\": \"<p>Willkommen!<\\/p>\",
        \"en\": \"<p>Welcome!<\\/p>\"
    },
    \"success_response\": {
        \"de\": \"<p>Danke!<\\/p>\",
        \"en\": \"<p>Thanks!<\\/p>\"
    },
    \"unpublished_content\": {
        \"de\": \"<p>Geschlossen.<\\/p>\",
        \"en\": \"<p>Closed.<\\/p>\"
    },
    \"data\": {
        \"fields\": {
            \"firstname\": {
                \"id\": \"868f3b29-26d0-4cc9-b377-82751e94b758\",
                \"name\": \"firstname\",
                \"type\": \"text\",
                \"label\": {
                    \"de\": \"Vorname\",
                    \"en\": \"First name\"
                },
                \"views\": [
                    \"index\",
                    \"detail\",
                    \"edit\",
                    \"app\"
                ],
                \"tab\": \"name_and_contact\",
                \"searchable\": true
            }
        },
        \"settings\": {
            \"app\": {
                \"triggers\": []
            },
            \"tabOrder\": [
                \"name_and_contact\"
            ]
        }
    },
    \"updated_at\": \"2026-10-08T09:00:00+00:00\",
    \"dry_run\": true,
    \"confirm_data_loss\": false
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/form-definitions/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "Crew registration",
    "description": "Main crew form",
    "tab_label": {
        "de": "Crew",
        "en": "Crew"
    },
    "url_shortname": "crew-2026",
    "published": true,
    "published_from": "2026-03-01T00:00:00+01:00",
    "published_to": "2026-06-30T23:59:00+02:00",
    "html_intro": {
        "de": "<p>Willkommen!<\/p>",
        "en": "<p>Welcome!<\/p>"
    },
    "success_response": {
        "de": "<p>Danke!<\/p>",
        "en": "<p>Thanks!<\/p>"
    },
    "unpublished_content": {
        "de": "<p>Geschlossen.<\/p>",
        "en": "<p>Closed.<\/p>"
    },
    "data": {
        "fields": {
            "firstname": {
                "id": "868f3b29-26d0-4cc9-b377-82751e94b758",
                "name": "firstname",
                "type": "text",
                "label": {
                    "de": "Vorname",
                    "en": "First name"
                },
                "views": [
                    "index",
                    "detail",
                    "edit",
                    "app"
                ],
                "tab": "name_and_contact",
                "searchable": true
            }
        },
        "settings": {
            "app": {
                "triggers": []
            },
            "tabOrder": [
                "name_and_contact"
            ]
        }
    },
    "updated_at": "2026-10-08T09:00:00+00:00",
    "dry_run": true,
    "confirm_data_loss": false
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/form-definitions/16';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'name' => 'Crew registration',
            'description' => 'Main crew form',
            'tab_label' => [
                'de' => 'Crew',
                'en' => 'Crew',
            ],
            'url_shortname' => 'crew-2026',
            'published' => true,
            'published_from' => '2026-03-01T00:00:00+01:00',
            'published_to' => '2026-06-30T23:59:00+02:00',
            'html_intro' => [
                'de' => '<p>Willkommen!</p>',
                'en' => '<p>Welcome!</p>',
            ],
            'success_response' => [
                'de' => '<p>Danke!</p>',
                'en' => '<p>Thanks!</p>',
            ],
            'unpublished_content' => [
                'de' => '<p>Geschlossen.</p>',
                'en' => '<p>Closed.</p>',
            ],
            'data' => [
                'fields' => [
                    'firstname' => [
                        'id' => '868f3b29-26d0-4cc9-b377-82751e94b758',
                        'name' => 'firstname',
                        'type' => 'text',
                        'label' => [
                            'de' => 'Vorname',
                            'en' => 'First name',
                        ],
                        'views' => [
                            'index',
                            'detail',
                            'edit',
                            'app',
                        ],
                        'tab' => 'name_and_contact',
                        'searchable' => true,
                    ],
                ],
                'settings' => [
                    'app' => [
                        'triggers' => [],
                    ],
                    'tabOrder' => [
                        'name_and_contact',
                    ],
                ],
            ],
            'updated_at' => '2026-10-08T09:00:00+00:00',
            'dry_run' => true,
            'confirm_data_loss' => false,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Saved):


{
    "data": {
        "id": 42,
        "project_id": 5,
        "name": "Crew",
        "model": "person",
        "type_shortname": "CrewPerson",
        "updated_at": "2026-10-08T09:05:00+00:00",
        "calculation": null,
        "data": {
            "fields": {},
            "settings": {}
        }
    },
    "validation": {
        "valid": true,
        "requires_confirm_data_loss": false,
        "errors": [],
        "warnings": [],
        "data_impact": []
    }
}
 

Example response (200, DryRun):


{
    "data": {
        "dry_run": true,
        "would_save": false,
        "validation": {
            "valid": true,
            "requires_confirm_data_loss": true,
            "errors": [],
            "warnings": [],
            "data_impact": [
                {
                    "rule": "FD-D01",
                    "severity": "confirm",
                    "field": "diet",
                    "path": "data.fields.diet",
                    "message": "The field holds values that would become unreachable.",
                    "impact": {
                        "affected_count": 12,
                        "sample_ids": [
                            101,
                            102,
                            103,
                            104,
                            105
                        ],
                        "change": "removed",
                        "recommended_action": "Hide the field instead of removing it."
                    }
                }
            ]
        }
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Example response (409, OptimisticLockFailed):


{
    "error": {
        "code": "optimistic_lock_failed",
        "message": "The resource was modified after your last read. Re-fetch and retry.",
        "errors": {
            "current": {
                "updated_at": "2026-10-08T09:05:00+00:00"
            }
        }
    }
}
 

Example response (409, CalculationInProgress):


{
    "error": {
        "code": "calculation_in_progress",
        "message": "The calculated fields of this form are being recalculated (running, 400 of 1390). Retry after the recalculation has finished.",
        "errors": {
            "calculation": {
                "state": "running",
                "since": "2026-10-08T09:01:00+00:00",
                "done": 400,
                "total": 1390
            }
        }
    }
}
 

Example response (422, Invalid):


{
    "error": {
        "code": "form_definition_invalid",
        "message": "The form definition was not saved: 1 error(s).",
        "errors": {
            "validation": {
                "valid": false,
                "requires_confirm_data_loss": false,
                "errors": [
                    {
                        "rule": "FD-L03",
                        "severity": "reject",
                        "path": "data.settings.app.triggers.shirt_size.conditions.0.field",
                        "message": "A condition of the visibility rule of \"shirt_size\" refers to \"merch\", which is not a field of this form."
                    }
                ],
                "warnings": [],
                "data_impact": []
            }
        }
    }
}
 

Example response (422, ConfirmDataLoss):


{
    "error": {
        "code": "confirm_data_loss_required",
        "message": "The change affects values that records already hold.",
        "errors": {
            "validation": {
                "valid": true,
                "requires_confirm_data_loss": true,
                "errors": [],
                "warnings": [],
                "data_impact": []
            }
        }
    }
}
 

Example response (429, TooManyRequests):


{
    "error": {
        "code": "too_many_requests",
        "message": "Too many requests."
    }
}
 

Request      

PUT api/v2/projects/{project_id}/form-definitions/{formDefinition_id}

PATCH api/v2/projects/{project_id}/form-definitions/{formDefinition_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

formDefinition_id   integer     

The ID of the formDefinition. Example: 16

project   integer     

Project id. Example: 16

formDefinition   integer     

Form definition id. Example: 42

Body Parameters

name   string     

Required on PUT. Display name (max 255). Must not be greater than 255 characters. Example: Crew registration

description   string  optional    

Internal description. Example: Main crew form

tab_label   object     

Required on PUT. Tab label per language; at least one language (rule FD-C19).

url_shortname   string  optional    

Slug of the public form URL: max 24 characters, letters, digits, single -/_, unique (rule FD-C18). Example: crew-2026

published   boolean  optional    

Whether the public form is reachable. Example: true

published_from   string  optional    

Start of the publication window. Must be a valid date. Example: 2026-03-01T00:00:00+01:00

published_to   string  optional    

End of the publication window. Must be a valid date. Example: 2026-06-30T23:59:00+02:00

html_intro   object  optional    

Intro HTML of the public form per language.

success_response   object  optional    

HTML shown after a submission, per language.

unpublished_content   object  optional    

HTML shown outside the publication window, per language.

data   object     

CAUTION: replaces the whole form definition (fields + settings). Read it with GET first, change it, send it back complete. Every rule of docs/form-definition-validator-rules.md runs on it; use dry_run to see the report first. Fields are matched by their id — keep the ids, or a rename becomes remove + add.

updated_at   string     

Optimistic lock: the updated_at you read. A newer stored version answers 409 optimistic_lock_failed. Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-10-08T09:00:00+00:00

dry_run   boolean  optional    

Validate only: returns the validation report and whether the change would be saved, writes nothing. Example: true

confirm_data_loss   boolean  optional    

Required when the report has data_impact findings (a field or option that records already use is removed, renamed or retyped). Check data_impact first. Example: false

Invoices

Paginated list of invoices, cancellations and credit notes of people, groups and orders.

requires authentication

invoiceable names the Person, Group or Order the document belongs to ({type, id}), so a failed person deletion (409 person_has_invoices) can be traced to its documents with ?person=. status is the document state: DRAFT, OPEN, PARTIALLY_PAID, PAID, VOIDED, CREDITED, DONE, PAIDOUT. Money in major units, rounded to the currency. Order invoices that do not exist yet are not created here. All filters combine (AND).

Required API permission: “Read invoices” (invoice_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/invoices?per_page=25&status=OPEN%2CPARTIALLY_PAID&document_type=invoice&created_from=2026-06-01T00%3A00%3A00%2B02%3A00&created_until=2026-07-01T00%3A00%3A00%2B02%3A00&updated_since=2026-06-01T00%3A00%3A00%2B00%3A00&person=01a1e3a6-efbf-4413-9db1-f36e60489254&application=812&order=3f8a4d2e-0000-4000-8000-000000000001&created_since=2026-06-01T00%3A00%3A00%2B00%3A00" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"per_page\": 16,
    \"status\": \"architecto\",
    \"statuses\": [
        \"PARTIALLY_PAID\"
    ],
    \"document_type\": \"invoice\",
    \"created_from\": \"2026-11-19T01:25:41+01:00\",
    \"created_until\": \"2026-11-19T01:25:41+01:00\",
    \"updated_since\": \"2026-11-19T01:25:41+01:00\",
    \"person\": \"a4855dc5-0acb-33c3-b921-f4291f719ca0\",
    \"application\": 66,
    \"order\": \"977e5426-8d13-3824-86aa-b092f8ae52c5\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/invoices"
);

const params = {
    "per_page": "25",
    "status": "OPEN,PARTIALLY_PAID",
    "document_type": "invoice",
    "created_from": "2026-06-01T00:00:00+02:00",
    "created_until": "2026-07-01T00:00:00+02:00",
    "updated_since": "2026-06-01T00:00:00+00:00",
    "person": "01a1e3a6-efbf-4413-9db1-f36e60489254",
    "application": "812",
    "order": "3f8a4d2e-0000-4000-8000-000000000001",
    "created_since": "2026-06-01T00:00:00+00:00",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "per_page": 16,
    "status": "architecto",
    "statuses": [
        "PARTIALLY_PAID"
    ],
    "document_type": "invoice",
    "created_from": "2026-11-19T01:25:41+01:00",
    "created_until": "2026-11-19T01:25:41+01:00",
    "updated_since": "2026-11-19T01:25:41+01:00",
    "person": "a4855dc5-0acb-33c3-b921-f4291f719ca0",
    "application": 66,
    "order": "977e5426-8d13-3824-86aa-b092f8ae52c5"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/invoices';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'status' => 'OPEN,PARTIALLY_PAID',
            'document_type' => 'invoice',
            'created_from' => '2026-06-01T00:00:00+02:00',
            'created_until' => '2026-07-01T00:00:00+02:00',
            'updated_since' => '2026-06-01T00:00:00+00:00',
            'person' => '01a1e3a6-efbf-4413-9db1-f36e60489254',
            'application' => '812',
            'order' => '3f8a4d2e-0000-4000-8000-000000000001',
            'created_since' => '2026-06-01T00:00:00+00:00',
        ],
        'json' => [
            'per_page' => 16,
            'status' => 'architecto',
            'statuses' => [
                'PARTIALLY_PAID',
            ],
            'document_type' => 'invoice',
            'created_from' => '2026-11-19T01:25:41+01:00',
            'created_until' => '2026-11-19T01:25:41+01:00',
            'updated_since' => '2026-11-19T01:25:41+01:00',
            'person' => 'a4855dc5-0acb-33c3-b921-f4291f719ca0',
            'application' => 66,
            'order' => '977e5426-8d13-3824-86aa-b092f8ae52c5',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": 880,
            "invoice_number": "RE-2026-0042",
            "document_type": "invoice",
            "status": "OPEN",
            "invoiceable": {
                "type": "application",
                "id": "812"
            },
            "invoice_type": {
                "id": 3,
                "name": "Exhibitor fee"
            },
            "original_invoice_id": null,
            "currency": "EUR",
            "total_amount": 238,
            "total_net": 200,
            "total_tax": 38,
            "paid_amount": 0,
            "open_amount": 238,
            "delivered_date": "2026-07-12T00:00:00+02:00",
            "created_at": "2026-06-02T10:00:00+02:00",
            "updated_at": "2026-06-02T10:00:00+02:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "statuses.0": [
                "The selected statuses.0 is invalid."
            ]
        }
    }
}
 

Request      

GET api/v2/projects/{project_id}/invoices

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 16

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

status   string  optional    

One or several comma-separated states, case-insensitive. Example: OPEN,PARTIALLY_PAID

document_type   string  optional    

invoice, cancellation or credit_note. Example: invoice

created_from   string  optional    

ISO 8601 timestamp with offset; documents created at or after it. Example: 2026-06-01T00:00:00+02:00

created_until   string  optional    

ISO 8601 timestamp with offset; documents created before it (exclusive). Example: 2026-07-01T00:00:00+02:00

updated_since   string  optional    

ISO 8601 timestamp with offset; documents updated at or after it. Example: 2026-06-01T00:00:00+00:00

person   string  optional    

Only documents of this Person (UUID). Example: 01a1e3a6-efbf-4413-9db1-f36e60489254

application   integer  optional    

Only documents of this Group. Example: 812

order   string  optional    

Only documents of this Order (UUID). Example: 3f8a4d2e-0000-4000-8000-000000000001

created_since   string  optional    

ISO 8601 timestamp with offset; only documents created at or after it, the same as created_from. Example: 2026-06-01T00:00:00+00:00

Body Parameters

per_page   integer  optional    

Must be at least 1. Example: 16

status   string  optional    

Example: architecto

statuses   string[]  optional    
Must be one of:
  • DRAFT
  • OPEN
  • PARTIALLY_PAID
  • PAID
  • VOIDED
  • CREDITED
  • DONE
  • PAIDOUT
document_type   string  optional    

Example: invoice

Must be one of:
  • invoice
  • cancellation
  • credit_note
created_from   string  optional    

Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-11-19T01:25:41+01:00

created_until   string  optional    

Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-11-19T01:25:41+01:00

updated_since   string  optional    

Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-11-19T01:25:41+01:00

person   string  optional    

Must be a valid UUID. Example: a4855dc5-0acb-33c3-b921-f4291f719ca0

application   integer  optional    

Must be at least 1. Example: 66

order   string  optional    

Must be a valid UUID. Example: 977e5426-8d13-3824-86aa-b092f8ae52c5

Show one invoice with billing address, payment terms and positions.

requires authentication

Required API permission: “Read invoices” (invoice_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/invoices/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/invoices/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/invoices/16';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": 880,
        "invoice_number": "RE-2026-0042",
        "document_type": "invoice",
        "status": "OPEN",
        "invoiceable": {
            "type": "application",
            "id": "812"
        },
        "invoice_type": {
            "id": 3,
            "name": "Exhibitor fee"
        },
        "original_invoice_id": null,
        "currency": "EUR",
        "total_amount": 238,
        "total_net": 200,
        "total_tax": 38,
        "paid_amount": 0,
        "open_amount": 238,
        "delivered_date": "2026-07-12T00:00:00+02:00",
        "created_at": "2026-06-02T10:00:00+02:00",
        "updated_at": "2026-06-02T10:00:00+02:00",
        "billing_address": "Example GmbH, Hauptstr. 1, 04109 Leipzig, DE",
        "payment_terms": "14 days net",
        "positions": [
            {
                "shortname": "Stand fee",
                "price": 200,
                "amount": 1,
                "unit": "",
                "totalPrice": 238,
                "totalTax": 38,
                "totalNet": 200,
                "currency": "EUR",
                "tax": 19,
                "service_type": "default",
                "reverse_charge_applies": false
            }
        ]
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/invoices/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   integer     

The ID of the invoice. Example: 16

project   integer     

Project id. Example: 16

invoice   integer     

Invoice id. Example: 880

Download the invoice as PDF.

requires authentication

Rendered on request from the stored invoice, the same document the backend's "download invoice" actions produce (with the e-invoice XML embedded when the project's export setting says so). Nothing is created or saved. 404 when the invoice has nothing to render it for — a person/group invoice without recipient person, or an order invoice whose order is gone.

Required API permission: “Read invoices” (invoice_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/invoices/16/pdf" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/invoices/16/pdf"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/invoices/16/pdf';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


[binary PDF]
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "Not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/invoices/{invoice_id}/pdf

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

invoice_id   integer     

The ID of the invoice. Example: 16

project   integer     

Project id. Example: 16

invoice   integer     

Invoice id. Example: 880

Users

List users

requires authentication

Paginated, ordered by id. Needs user_see.

Required API permission: “Read users and roles” (user_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/users?per_page=25&page=1&role=Event+Manager&project=5&is_api_user=&search=doe&with_roles=1&with_projects=1" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/users"
);

const params = {
    "per_page": "25",
    "page": "1",
    "role": "Event Manager",
    "project": "5",
    "is_api_user": "0",
    "search": "doe",
    "with_roles": "1",
    "with_projects": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/users';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'page' => '1',
            'role' => 'Event Manager',
            'project' => '5',
            'is_api_user' => '0',
            'search' => 'doe',
            'with_roles' => '1',
            'with_projects' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": 12,
            "name": "jdoe",
            "email": "jdoe@example.com",
            "person_id": null,
            "locale": null,
            "is_api_user": false,
            "email_verified_at": null,
            "last_seen_at": "2026-11-09T09:00:00+00:00",
            "created_at": "2026-01-10T09:00:00+00:00",
            "updated_at": "2026-11-01T09:00:00+00:00",
            "roles": [
                {
                    "id": 3,
                    "name": "Event Manager"
                }
            ]
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Request      

GET api/v2/users

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

page   integer  optional    

Page number (1-indexed). Example: 1

role   string  optional    

Only users holding this role (id or name, see GET /api/v2/roles). Example: Event Manager

project   integer  optional    

Only users whose project access lists this project id (within the project limit of the API access). Example: 5

is_api_user   boolean  optional    

true: only API users (listed for Admin access only); false: only other users. Example: false

search   string  optional    

Part of the username or email address. Example: doe

with_roles   boolean  optional    

Add roles [{id, name}] to every user. Example: true

with_projects   boolean  optional    

Add user_projects [{id, shortname, name}] to every user (empty = every project). Example: true

Create a user

requires authentication

Needs user_administrate, and an API access without project or type restriction (users are shared by every project). Roles can only be assigned when the API access holds them itself (assignable on GET /api/v2/roles). A deleted user with the same email is restored with exactly the roles and projects of this request.

Required API permission: “Create and delete users and assign roles” (user_administrate)

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/users" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --data "{
    \"name\": \"jdoe\",
    \"email\": \"jdoe@example.com\",
    \"password\": \"secureP4ss!\",
    \"send_signup_link\": false,
    \"roles\": [
        \"architecto\"
    ],
    \"user_projects\": [
        16
    ]
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/users"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

let body = {
    "name": "jdoe",
    "email": "jdoe@example.com",
    "password": "secureP4ss!",
    "send_signup_link": false,
    "roles": [
        "architecto"
    ],
    "user_projects": [
        16
    ]
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/users';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'json' => [
            'name' => 'jdoe',
            'email' => 'jdoe@example.com',
            'password' => 'secureP4ss!',
            'send_signup_link' => false,
            'roles' => [
                'architecto',
            ],
            'user_projects' => [
                16,
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201, Created):


{
    "data": {
        "id": 13,
        "name": "jdoe",
        "email": "jdoe@example.com",
        "person_id": null,
        "locale": null,
        "is_api_user": false,
        "email_verified_at": null,
        "last_seen_at": null,
        "created_at": "2026-11-09T09:00:00+00:00",
        "updated_at": "2026-11-09T09:00:00+00:00",
        "roles": [
            {
                "id": 3,
                "name": "Event Manager"
            }
        ],
        "user_projects": [],
        "signup_link": {
            "url": "https://example.festiwa.re/firstlogin/abc",
            "status": "sent"
        }
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (403, RoleNotAssignable):


{
    "error": {
        "code": "role_assignment_denied",
        "message": "These roles cannot be assigned or removed by this API access, because it does not hold them itself or they contain permissions it does not hold: Admin"
    }
}
 

Example response (403, ProjectRestricted):


{
    "error": {
        "code": "cross_project_access_denied",
        "message": "Users are shared by every project of the instance. This API access is limited to certain projects, so it cannot create, change or delete users."
    }
}
 

Example response (403, UserLimitReached):


{
    "error": {
        "code": "user_limit_reached",
        "message": "The booked number of users with access to the administration is used up. Remove a user or extend the package before adding another one."
    }
}
 

Example response (409, DeletedUserConflict):


{
    "error": {
        "code": "deleted_user_conflict",
        "message": "This email address belongs to a deleted API user or to a deleted user with individual permissions. Such a user cannot be restored through the API; permanently delete it first."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "email": [
                "The email has already been taken."
            ]
        }
    }
}
 

Request      

POST api/v2/users

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

Body Parameters

name   string     

Unique username. Must not be greater than 255 characters. Example: jdoe

email   string     

Unique email address. If a deleted user has it, that user is restored with exactly the roles and projects of this request. Must be a valid email address. Must not be greater than 255 characters. Example: jdoe@example.com

password   string  optional    

Password (min 8 characters), sent with password_confirmation. Optional when send_signup_link is true. Never returned. This field is required unless send_signup_link is in true. Must be at least 8 characters. Example: secureP4ss!

send_signup_link   boolean  optional    

When true, an invitation email with a one-time signup link is sent; without a password the user has no usable password until then. Example: false

roles   string[]     
user_projects   integer[]  optional    

The id of an existing record in the projects table.

id   string  optional    
data   string  optional    
locale   string  optional    
person_id   string  optional    
permissions   string  optional    
api_type_scope   string  optional    

Show a user

requires authentication

With roles and user_projects (empty = every project). Needs user_see.

Required API permission: “Read users and roles” (user_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/users/12" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/users/12"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/users/12';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": 12,
        "name": "jdoe",
        "email": "jdoe@example.com",
        "person_id": null,
        "locale": null,
        "is_api_user": false,
        "email_verified_at": null,
        "last_seen_at": "2026-11-09T09:00:00+00:00",
        "created_at": "2026-01-10T09:00:00+00:00",
        "updated_at": "2026-11-01T09:00:00+00:00",
        "roles": [
            {
                "id": 3,
                "name": "Event Manager"
            }
        ],
        "user_projects": [
            {
                "id": 5,
                "shortname": "fest26",
                "name": "Festival 2026"
            }
        ]
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Request      

GET api/v2/users/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   integer     

User id. Example: 12

Update a user

requires authentication

PUT replaces name, email, roles and user_projects (all required, the lists may be empty); PATCH changes only what it sends. The password changes only when sent. Optimistic lock via updated_at.

Needs user_manage; roles or user_projects in the body need user_administrate, so PUT always does. The API access must not be limited to projects or types. API users, the system access, Super Admins and users holding a role the API access does not hold itself cannot be changed (403 user_protected).

Required API permission: “Edit users” (user_manage)

Example request:
curl --request PUT \
    "https://{instance}.festiwa.re/api/v2/users/12" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"jdoe\",
    \"email\": \"jdoe@example.com\",
    \"password\": \"secureP4ss!\",
    \"send_signup_link\": false,
    \"roles\": [
        \"architecto\"
    ],
    \"user_projects\": [
        16
    ],
    \"updated_at\": \"2026-11-09T09:00:00+00:00\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/users/12"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "jdoe",
    "email": "jdoe@example.com",
    "password": "secureP4ss!",
    "send_signup_link": false,
    "roles": [
        "architecto"
    ],
    "user_projects": [
        16
    ],
    "updated_at": "2026-11-09T09:00:00+00:00"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/users/12';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'name' => 'jdoe',
            'email' => 'jdoe@example.com',
            'password' => 'secureP4ss!',
            'send_signup_link' => false,
            'roles' => [
                'architecto',
            ],
            'user_projects' => [
                16,
            ],
            'updated_at' => '2026-11-09T09:00:00+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": 12,
        "name": "jdoe",
        "email": "jdoe@example.com",
        "person_id": null,
        "locale": null,
        "is_api_user": false,
        "email_verified_at": null,
        "last_seen_at": null,
        "created_at": "2026-01-10T09:00:00+00:00",
        "updated_at": "2026-11-09T12:00:00+00:00",
        "roles": [
            {
                "id": 3,
                "name": "Event Manager"
            }
        ],
        "user_projects": []
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (403, UserProtected):


{
    "error": {
        "code": "user_protected",
        "message": "This user holds roles this API access does not hold itself (Admin), so it cannot be changed or deleted through it."
    }
}
 

Example response (403, RoleNotAssignable):


{
    "error": {
        "code": "role_assignment_denied",
        "message": "These roles cannot be assigned or removed by this API access, because it does not hold them itself or they contain permissions it does not hold: Admin"
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (409, OptimisticLockFailed):


{
    "error": {
        "code": "optimistic_lock_failed",
        "message": "The resource was modified after your last read. Re-fetch and retry.",
        "errors": {
            "current": {
                "updated_at": "2026-11-09T12:00:00+00:00"
            }
        }
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "updated_at": [
                "The updated at field is required."
            ]
        }
    }
}
 

Request      

PUT api/v2/users/{id}

PATCH api/v2/users/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   integer     

User id. Example: 12

Body Parameters

name   string     

Required on PUT, optional on PATCH. Unique username. Must not be greater than 255 characters. Example: jdoe

email   string     

Required on PUT, optional on PATCH. Unique email address. Must be a valid email address. Must not be greater than 255 characters. Example: jdoe@example.com

password   string  optional    

Optional on PUT and PATCH: a new password (min 8 characters), sent with password_confirmation. Never returned. Must be at least 8 characters. Example: secureP4ss!

send_signup_link   boolean  optional    

When true and the user has no signup link yet, an invitation email with one is sent. Example: false

roles   string[]     
user_projects   integer[]  optional    

The id of an existing record in the projects table.

updated_at   string     

Required ISO 8601 last-known timestamp (optimistic-lock token). Role and project changes move it too. Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-11-09T09:00:00+00:00

id   string  optional    
data   string  optional    
locale   string  optional    
person_id   string  optional    
permissions   string  optional    
api_type_scope   string  optional    

Delete a user

requires authentication

Soft delete; needs {"confirm": true} and user_administrate, and an API access without project or type restriction. The same users as on update are protected; an API access cannot delete its own user.

Required API permission: “Create and delete users and assign roles” (user_administrate)

Example request:
curl --request DELETE \
    "https://{instance}.festiwa.re/api/v2/users/12" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"confirm\": true
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/users/12"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "confirm": true
};

fetch(url, {
    method: "DELETE",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/users/12';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'confirm' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (204, Deleted):

Empty response
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Example response (403, UserProtected):


{
    "error": {
        "code": "user_protected",
        "message": "This user is a festiware administrator and cannot be changed or deleted through this API access."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (409, Self):


{
    "error": {
        "code": "cannot_delete_self",
        "message": "An API access cannot delete its own user."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "confirm": [
                "The confirm field must be accepted."
            ]
        }
    }
}
 

Request      

DELETE api/v2/users/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   integer     

User id. Example: 12

Body Parameters

confirm   boolean     

Required guard against accidental deletion. Must be exactly true: false or omission returns 422 and leaves the user intact. Must be accepted. Example: true

List roles

requires authentication

The roles that can be given to users, in their backend order. Small and instance-wide, so not paginated. assignable: whether this API access may assign or remove the role on POST/PUT/PATCH /api/v2/users (it holds the role itself and every protected permission in it). Needs user_see.

Required API permission: “Read users and roles” (user_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/roles" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/roles"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/roles';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": 2,
            "name": "Admin",
            "guard": "web",
            "assignable": false
        },
        {
            "id": 3,
            "name": "Event Manager",
            "guard": "web",
            "assignable": true
        }
    ]
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You are not authorized to perform this action."
    }
}
 

Request      

GET api/v2/roles

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

The calling API access

requires authentication

Who the token belongs to and what it may do: no permission needed.

permissions lists every API permission (as on the API user in the backend) this access holds, a higher level including the lower ones. api_grant: ticked directly on the API user. via_role: comes from a role of the user. Endpoints of API v2 accept either; the workflow endpoints (and the older API v1) only accept api_grant.

projects: null = every project, otherwise the only projects this access may work in. type_scope: null = every person and group type, otherwise the only types it sees. token: the OAuth client and scopes of the token used for this request.

Required API permission: none. Any API user. Describes only the calling API access itself: its permissions, project access, type restriction and token.

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/me" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/me"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/me';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": 42,
        "name": "n8n integration",
        "email": "api-n8n@example.com",
        "guard": "api",
        "is_api_user": true,
        "is_super_admin": false,
        "permissions": [
            {
                "name": "all_persons_and_applications_see",
                "label": "Read people and groups",
                "via_role": false,
                "api_grant": true
            }
        ],
        "projects": [
            {
                "id": 5,
                "shortname": "fest26",
                "name": "Festival 2026"
            }
        ],
        "type_scope": {
            "person_types": [
                {
                    "id": 3,
                    "shortname": "Crew"
                }
            ],
            "application_types": []
        },
        "token": {
            "client_id": "9a1c0f00-0000-4000-8000-000000000000",
            "scopes": [],
            "expires_at": "2027-11-09T09:00:00+00:00"
        }
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Request      

GET api/v2/me

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Webhooks

Register, change and remove the webhooks of a project, so an integration (n8n, your own script) can set up its own receiver instead of someone configuring it in the backend. Attach the events that call a webhook through the webhook's triggers endpoints.

Every call is a POST to the webhook's url with a JSON envelope:

{"event": "person.updated", "timestamp": "2026-11-09T10:30:00+00:00",
 "triggered_by": {"source": "nova|api|system|web", "user_email": "user@example.com"},
 "data": { … the record … }}

plus the headers X-Event-Type, X-Resource-Type, X-EXECUTION-ID, X-Instance-Id, X-Instance-Name and the webhook's own headers. A payload_mapping replaces the envelope with your own body template. Full event catalog: see "Webhook events" (FWT-3091).

Only project webhooks are visible here. Webhooks set up in the backend for the whole instance (no project) are not listed and answer 404. A project webhook only fires for triggers of its own project. Active webhooks count against the package quota max_webhooks, counted per instance.

List the project's webhooks.

requires authentication

Required API permission: “Send webhook responses” (webhook_manage)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/webhooks?per_page=25&page=1" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/webhooks"
);

const params = {
    "per_page": "25",
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/webhooks';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Listed):


{
    "data": [
        {
            "id": 7,
            "name": "n8n: new crew members",
            "url": "https://n8n.example.com/webhook/3f1c",
            "active": true,
            "timeout_seconds": null,
            "effective_timeout_seconds": 15,
            "headers": {
                "X-API-TOKEN": "***"
            },
            "has_payload_mapping": false,
            "payload_mapping": null,
            "project": {
                "id": 2,
                "shortname": "FEST26"
            },
            "triggers_count": 1,
            "created_at": "2026-11-09T10:00:00+00:00",
            "updated_at": "2026-11-09T10:00:00+00:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": "…",
        "last": "…",
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (429, TooManyRequests):


{
    "error": {
        "code": "too_many_requests",
        "message": "Too many requests."
    }
}
 

Request      

GET api/v2/projects/{project_id}/webhooks

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 2

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

page   integer  optional    

Page number (1-indexed). Example: 1

Create a webhook.

requires authentication

The webhook belongs to the project of the URL. It does nothing until you attach a trigger (POST …/webhooks/{webhook}/triggers). An active webhook needs a free slot of the package quota max_webhooks (counted per instance, all projects): without one the answer is 422 quota_exceeded; create it with "active": false and switch it on later.

Required API permission: “Manage webhooks” (webhook_administrate)

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/webhooks" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --data "{
    \"name\": \"n8n: new crew members\",
    \"url\": \"https:\\/\\/n8n.example.com\\/webhook\\/3f1c\",
    \"active\": true,
    \"timeout_seconds\": 30,
    \"headers\": [
        \"b\"
    ]
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/webhooks"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

let body = {
    "name": "n8n: new crew members",
    "url": "https:\/\/n8n.example.com\/webhook\/3f1c",
    "active": true,
    "timeout_seconds": 30,
    "headers": [
        "b"
    ]
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/webhooks';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'json' => [
            'name' => 'n8n: new crew members',
            'url' => 'https://n8n.example.com/webhook/3f1c',
            'active' => true,
            'timeout_seconds' => 30,
            'headers' => [
                'b',
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201, Created):


{
    "data": {
        "id": 7,
        "name": "n8n: new crew members",
        "url": "https://n8n.example.com/webhook/3f1c",
        "active": true,
        "timeout_seconds": null,
        "effective_timeout_seconds": 15,
        "headers": {
            "X-API-TOKEN": "***"
        },
        "has_payload_mapping": false,
        "payload_mapping": null,
        "project": {
            "id": 2,
            "shortname": "FEST26"
        },
        "triggers_count": 0,
        "created_at": "2026-11-09T10:00:00+00:00",
        "updated_at": "2026-11-09T10:00:00+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "url": [
                "The url field must start with one of the following: https://."
            ]
        }
    }
}
 

Example response (422, QuotaExceeded):


{
    "error": {
        "code": "quota_exceeded",
        "message": "Your package allows 3 active webhooks; 3 are in use.",
        "errors": {
            "active": [
                "Your package allows 3 active webhooks; 3 are in use."
            ]
        }
    }
}
 

Example response (429, TooManyRequests):


{
    "error": {
        "code": "too_many_requests",
        "message": "Too many requests."
    }
}
 

Request      

POST api/v2/projects/{project_id}/webhooks

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 2

Body Parameters

name   string     

Display name (max 255 chars). Must not be greater than 255 characters. Example: n8n: new crew members

url   string     

Receiver URL. Must be https:// (max 255 chars). Must be a valid URL. Must start with one of https:// Must not be greater than 255 characters. Example: https://n8n.example.com/webhook/3f1c

active   boolean  optional    

Whether the webhook is called. Default true. An active webhook counts against the package quota max_webhooks (instance-wide). Example: true

timeout_seconds   integer  optional    

Seconds to wait for the receiver, 1 to 60. Null or omitted = the default (effective_timeout_seconds in the response). Must be at least 1. Must not be greater than 60. Example: 30

headers   string[]  optional    

Must not be greater than 1000 characters.

payload_mapping   object  optional    

Optional body template that replaces the default payload envelope (same format as the backend field "Body mapping"): an object of key => node, each node with a type of path, literal, object or list. twig nodes are backend-only and refused here. Returned as stored (not masked): put tokens into headers, not into literal nodes. Null = default envelope.

Show a webhook.

requires authentication

Required API permission: “Send webhook responses” (webhook_manage)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/webhooks/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/webhooks/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/webhooks/16';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": 7,
        "name": "n8n: new crew members",
        "url": "https://n8n.example.com/webhook/3f1c",
        "active": true,
        "timeout_seconds": 30,
        "effective_timeout_seconds": 30,
        "headers": {
            "X-API-TOKEN": "***"
        },
        "has_payload_mapping": false,
        "payload_mapping": null,
        "project": {
            "id": 2,
            "shortname": "FEST26"
        },
        "triggers_count": 1,
        "created_at": "2026-11-09T10:00:00+00:00",
        "updated_at": "2026-11-09T10:00:00+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (429, TooManyRequests):


{
    "error": {
        "code": "too_many_requests",
        "message": "Too many requests."
    }
}
 

Request      

GET api/v2/projects/{project_id}/webhooks/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   integer     

The ID of the webhook. Example: 16

project   integer     

Project id. Example: 2

webhook   integer     

Webhook id (must belong to the project). Example: 7

Update a webhook.

requires authentication

Sparse merge: only the fields you send change. headers is replaced as a whole when sent (values are masked in every response, so send all of them). updated_at from your last read is required; a newer stored value returns 409. Switching an inactive webhook on needs a free slot of max_webhooks (422 quota_exceeded).

Changing url sends the webhook's records somewhere else, so:

Required API permission: “Send webhook responses” (webhook_manage)

Example request:
curl --request PATCH \
    "https://{instance}.festiwa.re/api/v2/projects/564/webhooks/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"n8n: new crew members\",
    \"url\": \"https:\\/\\/n8n.example.com\\/webhook\\/3f1c\",
    \"active\": true,
    \"timeout_seconds\": 30,
    \"headers\": [
        \"b\"
    ],
    \"updated_at\": \"2026-11-09T10:00:00+00:00\"
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/webhooks/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "n8n: new crew members",
    "url": "https:\/\/n8n.example.com\/webhook\/3f1c",
    "active": true,
    "timeout_seconds": 30,
    "headers": [
        "b"
    ],
    "updated_at": "2026-11-09T10:00:00+00:00"
};

fetch(url, {
    method: "PATCH",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/webhooks/16';
$response = $client->patch(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'name' => 'n8n: new crew members',
            'url' => 'https://n8n.example.com/webhook/3f1c',
            'active' => true,
            'timeout_seconds' => 30,
            'headers' => [
                'b',
            ],
            'updated_at' => '2026-11-09T10:00:00+00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Updated):


{
    "data": {
        "id": 7,
        "name": "n8n: crew sync",
        "url": "https://n8n.example.com/webhook/3f1c",
        "active": true,
        "timeout_seconds": 30,
        "effective_timeout_seconds": 30,
        "headers": {
            "X-API-TOKEN": "***"
        },
        "has_payload_mapping": false,
        "payload_mapping": null,
        "project": {
            "id": 2,
            "shortname": "FEST26"
        },
        "triggers_count": 1,
        "created_at": "2026-11-09T10:00:00+00:00",
        "updated_at": "2026-11-09T10:05:00+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (409, OptimisticLockFailed):


{
    "error": {
        "code": "optimistic_lock_failed",
        "message": "The resource was modified after your last read. Re-fetch and retry.",
        "errors": {
            "current": {
                "updated_at": "2026-11-09T10:05:00+00:00"
            }
        }
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "timeout_seconds": [
                "The timeout seconds field must not be greater than 60."
            ]
        }
    }
}
 

Example response (422, QuotaExceeded):


{
    "error": {
        "code": "quota_exceeded",
        "message": "Your package allows 3 active webhooks; 3 are in use.",
        "errors": {
            "active": [
                "Your package allows 3 active webhooks; 3 are in use."
            ]
        }
    }
}
 

Example response (429, TooManyRequests):


{
    "error": {
        "code": "too_many_requests",
        "message": "Too many requests."
    }
}
 

Request      

PATCH api/v2/projects/{project_id}/webhooks/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   integer     

The ID of the webhook. Example: 16

project   integer     

Project id. Example: 2

webhook   integer     

Webhook id (must belong to the project). Example: 7

Body Parameters

name   string  optional    

Display name (max 255 chars). Must not be greater than 255 characters. Example: n8n: new crew members

url   string  optional    

Receiver URL. Must be https:// (max 255 chars). Must be a valid URL. Must start with one of https:// Must not be greater than 255 characters. Example: https://n8n.example.com/webhook/3f1c

active   boolean  optional    

Whether the webhook is called. Default true. An active webhook counts against the package quota max_webhooks (instance-wide). Example: true

timeout_seconds   integer  optional    

Seconds to wait for the receiver, 1 to 60. Null or omitted = the default (effective_timeout_seconds in the response). Must be at least 1. Must not be greater than 60. Example: 30

headers   string[]  optional    

Must not be greater than 1000 characters.

payload_mapping   object  optional    

Optional body template that replaces the default payload envelope (same format as the backend field "Body mapping"): an object of key => node, each node with a type of path, literal, object or list. twig nodes are backend-only and refused here. Returned as stored (not masked): put tokens into headers, not into literal nodes. Null = default envelope.

updated_at   string     

The updated_at of your last read (ISO 8601). A newer stored value returns 409 optimistic_lock_failed. Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-11-09T10:00:00+00:00

Delete a webhook.

requires authentication

Requires {"confirm": true}. Removes the webhook, its call log, and every trigger that calls it (also triggers in other projects that reference it, so none is left pointing at nothing). Calls already queued are not withdrawn. Deleting triggers needs workflow_administrate. An API user restricted to some projects gets 403 cross_project_access_denied when a trigger of a project outside that list references the webhook; it has to be removed in the backend first.

Required API permission: “Manage webhooks” (webhook_administrate)

Depending on the request also: “Create and delete triggers” (workflow_administrate)

Example request:
curl --request DELETE \
    "https://{instance}.festiwa.re/api/v2/projects/564/webhooks/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"confirm\": true
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/webhooks/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "confirm": true
};

fetch(url, {
    method: "DELETE",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/webhooks/16';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'confirm' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Deleted):


{
    "data": {
        "id": 7,
        "deleted": true,
        "detached_triggers": 2
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (403, CrossProjectTriggers):


{
    "error": {
        "code": "cross_project_access_denied",
        "message": "1 trigger(s) of other projects call this webhook. Remove them in the backend first.",
        "errors": {
            "foreign_triggers": 1
        }
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (422, ConfirmMissing):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "confirm": [
                "The confirm field is required."
            ]
        }
    }
}
 

Example response (429, TooManyRequests):


{
    "error": {
        "code": "too_many_requests",
        "message": "Too many requests."
    }
}
 

Request      

DELETE api/v2/projects/{project_id}/webhooks/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   integer     

The ID of the webhook. Example: 16

project   integer     

Project id. Example: 2

webhook   integer     

Webhook id (must belong to the project). Example: 7

Body Parameters

confirm   boolean     

Required guard against accidental deletion. Must be exactly true — false or omission returns 422 and leaves the webhook and its triggers intact. Must be accepted. Example: true

List a webhook's triggers.

requires authentication

The triggers of this project that call the webhook.

Required API permission: “Send webhook responses” (webhook_manage) and “Read workflows” (workflow_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/webhooks/16/triggers?per_page=25&page=1" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/webhooks/16/triggers"
);

const params = {
    "per_page": "25",
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/webhooks/16/triggers';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Listed):


{
    "data": [
        {
            "id": 91,
            "name": "Webhook n8n: crew sync: Person",
            "model": "Person",
            "events": [
                "created",
                "updated"
            ],
            "conditions": null,
            "active": true,
            "updated_at": "2026-11-09T10:00:00+00:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    },
    "links": {
        "first": "…",
        "last": "…",
        "prev": null,
        "next": null
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (429, TooManyRequests):


{
    "error": {
        "code": "too_many_requests",
        "message": "Too many requests."
    }
}
 

Request      

GET api/v2/projects/{project_id}/webhooks/{webhook_id}/triggers

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

webhook_id   integer     

The ID of the webhook. Example: 16

project   integer     

Project id. Example: 2

webhook   integer     

Webhook id (must belong to the project). Example: 7

Query Parameters

per_page   integer  optional    

Page size, clamped to 100. Example: 25

page   integer  optional    

Page number (1-indexed). Example: 1

Attach a trigger.

requires authentication

Creates a model-event trigger in this project that calls the webhook. conditions are checked for their structure and operators (rules WT-08, WT-09 of docs/workflow-trigger-validator-rules.md); a broken tree returns 422 workflow_trigger_invalid with the findings. Field names in conditions are not checked against a form.

Every call sends the whole record to the webhook's URL, so you also need the read permission of the observed model (e.g. all_persons_and_applications_see for Person and Application, invoice_see for Invoice). For Person and Application, a data qualification that hides a form field of the project from you refuses the attach with 403 data_qualification_restricted: the webhook would send that field.

Required API permission: “Manage webhooks” (webhook_administrate) and “Create and delete triggers” (workflow_administrate)

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/webhooks/16/triggers" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --data "{
    \"model\": \"Person\",
    \"events\": [
        \"portal_update\"
    ],
    \"name\": \"n8n crew sync\",
    \"conditions\": {
        \"and\": [
            {
                \"field\": \"data.shirt\",
                \"operator\": \"==\",
                \"value\": \"m\"
            }
        ]
    },
    \"active\": true
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/webhooks/16/triggers"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

let body = {
    "model": "Person",
    "events": [
        "portal_update"
    ],
    "name": "n8n crew sync",
    "conditions": {
        "and": [
            {
                "field": "data.shirt",
                "operator": "==",
                "value": "m"
            }
        ]
    },
    "active": true
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/webhooks/16/triggers';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'json' => [
            'model' => 'Person',
            'events' => [
                'portal_update',
            ],
            'name' => 'n8n crew sync',
            'conditions' => [
                'and' => [
                    [
                        'field' => 'data.shirt',
                        'operator' => '==',
                        'value' => 'm',
                    ],
                ],
            ],
            'active' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201, Attached):


{
    "data": {
        "id": 91,
        "name": "Webhook n8n: crew sync: Person",
        "model": "Person",
        "events": [
            "created",
            "updated"
        ],
        "conditions": null,
        "active": true,
        "updated_at": "2026-11-09T10:00:00+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (403, DataQualificationRestricted):


{
    "error": {
        "code": "data_qualification_restricted",
        "message": "A webhook sends every field of a Person, but data qualifications hide 2 of its fields from you. Ask an admin for access to those data qualifications."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (422, ValidationFailed):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "events": [
                "The event \"restored\" must exist for the model Team. Allowed: created, updated, deleted."
            ]
        }
    }
}
 

Example response (422, Invalid):


{
    "error": {
        "code": "workflow_trigger_invalid",
        "message": "The trigger was not saved: 1 blocking error(s).",
        "errors": {
            "validation": {
                "valid": false,
                "requires_confirm_data_loss": false,
                "errors": [
                    {
                        "rule": "WT-09",
                        "severity": "reject",
                        "field": null,
                        "path": "conditions.and.0.operator",
                        "message": "WT-09 at conditions.and.0.operator: Unknown operator \"~\".",
                        "hint": "Use one of: in not_in = …"
                    }
                ],
                "warnings": [],
                "data_impact": []
            }
        }
    }
}
 

Example response (429, TooManyRequests):


{
    "error": {
        "code": "too_many_requests",
        "message": "Too many requests."
    }
}
 

Request      

POST api/v2/projects/{project_id}/webhooks/{webhook_id}/triggers

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

webhook_id   integer     

The ID of the webhook. Example: 16

project   integer     

Project id. Example: 2

webhook   integer     

Webhook id (must belong to the project). Example: 7

Body Parameters

model   string     

Short class name of the observed model, one of: Application, Area, Contract, Coupon, Invoice, Order, OrderStatus, Person, SchedulerEvent, SchedulerEventType, SchedulerJob, SchedulerPlan, Supply, SupplyCategory, SupplyItem, Team, TeamRole, TicketCode, TicketCodeStatus, TicketType. (Application is what the backend calls a group.) Each call sends the whole record, so you also need the read permission of that model (e.g. all_persons_and_applications_see for Person and Application). Workflow step triggers are not attached here. Example: Person

Must be one of:
  • Application
  • Area
  • Contract
  • Coupon
  • Invoice
  • Order
  • OrderStatus
  • Person
  • SchedulerEvent
  • SchedulerEventType
  • SchedulerJob
  • SchedulerPlan
  • Supply
  • SupplyCategory
  • SupplyItem
  • Team
  • TeamRole
  • TicketCode
  • TicketCodeStatus
  • TicketType
events   string[]  optional    
Must be one of:
  • created
  • updated
  • deleted
  • restored
  • portal_update
name   string  optional    

Trigger name shown in the backend. Default: "Webhook : ". Must not be greater than 255 characters. Example: n8n crew sync

conditions   object  optional    

Optional run conditions: a tree of {"and": [...]} / {"or": [...]} groups with {"field", "operator", "value"} leaves.

active   boolean  optional    

Whether the trigger fires. Default true. Example: true

Detach a trigger.

requires authentication

Requires {"confirm": true}. Deletes the trigger; the webhook stays.

Required API permission: “Manage webhooks” (webhook_administrate) and “Create and delete triggers” (workflow_administrate)

Example request:
curl --request DELETE \
    "https://{instance}.festiwa.re/api/v2/projects/564/webhooks/16/triggers/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"confirm\": true
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/webhooks/16/triggers/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "confirm": true
};

fetch(url, {
    method: "DELETE",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/webhooks/16/triggers/16';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'confirm' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Detached):


{
    "data": {
        "id": 91,
        "deleted": true
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (422, ConfirmMissing):


{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "errors": {
            "confirm": [
                "The confirm field is required."
            ]
        }
    }
}
 

Example response (429, TooManyRequests):


{
    "error": {
        "code": "too_many_requests",
        "message": "Too many requests."
    }
}
 

Request      

DELETE api/v2/projects/{project_id}/webhooks/{webhook_id}/triggers/{workflowTrigger_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

webhook_id   integer     

The ID of the webhook. Example: 16

workflowTrigger_id   integer     

The ID of the workflowTrigger. Example: 16

project   integer     

Project id. Example: 2

webhook   integer     

Webhook id (must belong to the project). Example: 7

workflowTrigger   integer     

Trigger id (must call this webhook, in this project). Example: 91

Body Parameters

confirm   boolean     

Required guard against accidental deletion. Must be exactly true; false or omission returns 422 and leaves the trigger intact. Must be accepted. Example: true

Workflows

Export a workflow as a portable payload.

requires authentication

Serialises the workflow, its steps and triggers into a project-agnostic payload that uses shortnames instead of project-local ids. Feed the result straight into the import endpoint.

Required API permission: “Read workflows” (workflow_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/workflows/16/export" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/workflows/16/export"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/workflows/16/export';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Exported):


{
    "data": {
        "version": 1,
        "workflow_shortname": "onboarding",
        "type_shortname": "artist",
        "type_model": "person",
        "name": "Onboarding",
        "steps": [
            {
                "shortname": "NEW",
                "is_start": true,
                "triggers": [
                    {
                        "action_type": "notify_user",
                        "active": true,
                        "data": {
                            "notifiable_id": "crew@example.com"
                        }
                    }
                ]
            }
        ]
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/workflows/{workflow_id}/export

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

workflow_id   integer     

The ID of the workflow. Example: 16

project   integer     

Project id. Example: 1

workflow   integer     

Workflow id (must belong to the project). Example: 5

Import a workflow into a project.

requires authentication

Resolves every reference in the payload against the target project. If everything resolves the workflow is created (or replaces a same-shortname workflow with no started journey) with all triggers on. A person or group type has exactly one workflow per project: if the target type already has a workflow under another shortname, the import is a showstopper (issue code type_has_other_workflow, token = that workflow's shortname); import it under that shortname to replace it. A missing dependency is a blocker: the import is refused (422) and nothing is written — unless deactivate_unresolved is set, which commits with the affected triggers switched off (listed in the report). A problem on a start or endpoint step is always a showstopper and cannot be waived. A trigger that leaves a value its action cannot run without empty counts as a missing dependency too (issue code required_value_missing, field = the data key; create_event: area, fieldname, duration), and so does one whose value is unusable (required_value_invalid, token = the value; create_event: duration that is not a whole number of at least 1 minute, e.g. 0); complete it via the trigger update endpoint before switching it on.

Required API permission: “Edit workflows” (workflow_manage)

Example request:
curl --request POST \
    "https://{instance}.festiwa.re/api/v2/projects/564/workflows/import" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "Idempotency-Key: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47" \
    --data "{
    \"payload\": {
        \"workflow_shortname\": \"onboarding\",
        \"type_shortname\": \"artist\",
        \"steps\": [
            []
        ]
    },
    \"target_type\": \"artist\",
    \"deactivate_unresolved\": false
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/workflows/import"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": "3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47",
};

let body = {
    "payload": {
        "workflow_shortname": "onboarding",
        "type_shortname": "artist",
        "steps": [
            []
        ]
    },
    "target_type": "artist",
    "deactivate_unresolved": false
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/workflows/import';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Idempotency-Key' => '3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47',
        ],
        'json' => [
            'payload' => [
                'workflow_shortname' => 'onboarding',
                'type_shortname' => 'artist',
                'steps' => [
                    [],
                ],
            ],
            'target_type' => 'artist',
            'deactivate_unresolved' => false,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Imported):


{
    "data": {
        "committed": true,
        "workflow_id": 42,
        "steps_created": 3,
        "triggers_created": 5,
        "deactivated_triggers": [],
        "issues": []
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (422, Blockers):


{
    "error": {
        "code": "import_has_blockers",
        "message": "The workflow has unresolved references or triggers with an empty or invalid required value. Prepare the target or re-send with deactivate_unresolved to import the affected triggers switched off.",
        "report": {
            "can_commit": false,
            "issues": [
                {
                    "severity": "blocker",
                    "code": "reference_unresolved",
                    "step_shortname": "NEW",
                    "field": "area",
                    "token": "mainstage"
                }
            ]
        }
    }
}
 

Example response (422, Showstoppers):


{
    "error": {
        "code": "import_has_showstoppers",
        "message": "The workflow cannot be imported. Resolve the showstoppers in the report first.",
        "report": {
            "can_commit": false,
            "issues": [
                {
                    "severity": "showstopper",
                    "code": "workflow_type_mismatch",
                    "token": "artist"
                }
            ]
        }
    }
}
 

Request      

POST api/v2/projects/{project_id}/workflows/import

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Idempotency-Key        

Example: 3f2c8a4e-9b1d-4c6e-8f7a-2d5b1e0c9a47

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Target project id. Example: 2

Body Parameters

payload   object     

The exported workflow payload (from the export endpoint).

workflow_shortname   string     

Workflow shortname. Example: onboarding

type_shortname   string     

Person/group type shortname. Example: artist

steps   object[]     

The workflow steps with their triggers.

target_type   string     

Shortname of the target type; must match the payload type. Example: artist

deactivate_unresolved   boolean  optional    

Commit despite blockers, importing unresolvable triggers switched off. Does not override a showstopper. Default: false. Example: false

List a workflow's triggers.

requires authentication

Lists every trigger of the workflow's steps. Filter by on/off with active to find the triggers an import switched off, then complete them via the update endpoint.

Required API permission: “Read workflows” (workflow_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/workflows/16/triggers?active=&created_since=2026-06-01T00%3A00%3A00%2B00%3A00&updated_since=2026-06-01T00%3A00%3A00%2B00%3A00%0A%0AAdditionally+needs+access+to+the+workflow%27s+person+or+group+type." \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/workflows/16/triggers"
);

const params = {
    "active": "0",
    "created_since": "2026-06-01T00:00:00+00:00",
    "updated_since": "2026-06-01T00:00:00+00:00

Additionally needs access to the workflow's person or group type.",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/workflows/16/triggers';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'active' => '0',
            'created_since' => '2026-06-01T00:00:00+00:00',
            'updated_since' => '2026-06-01T00:00:00+00:00

Additionally needs access to the workflow's person or group type.',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Listed):


{
    "data": [
        {
            "id": 77,
            "name": "Notify crew",
            "action_type": "notify_user",
            "triggers_on": [
                "enter"
            ],
            "active": false,
            "observed_id": 42,
            "data": {
                "notifiable_id": null
            }
        }
    ]
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/workflows/{workflow_id}/triggers

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

workflow_id   integer     

The ID of the workflow. Example: 16

project   integer     

Project id. Example: 2

workflow   integer     

Workflow id (must belong to the project). Example: 42

Query Parameters

active   boolean  optional    

Filter by trigger state: 1 for on, 0 for off. Omit for all. Example: false

created_since   string  optional    

ISO 8601 timestamp with offset; only records created at or after it. Example: 2026-06-01T00:00:00+00:00

updated_since   string  optional    

ISO 8601 timestamp with offset; only records updated at or after it. Example: `2026-06-01T00:00:00+00:00

Additionally needs access to the workflow's person or group type.`

Update a workflow trigger.

requires authentication

Fix and reactivate a trigger after an import (merge missing values into data, set active), or edit its content: texts, conditions, name, delay. Scoped to the project; only triggers of a workflow step.

Every request runs the trigger validator (docs/workflow-trigger-validator-rules.md, WT-*): Twig syntax with line numbers, unknown placeholders, an allow-list of Twig constructs, the condition tree, references to deleted records, the delay range, values an action cannot run without (WT-16; create_event: data.area (area id of the project), data.fieldname (the datetime field the event starts at) and data.duration (minutes, a whole number of at least 1; 0 is refused) must not be empty). What you send must be clean, including errors it already had; errors the stored trigger already had in parts you do not send (preexisting: true) do not block. Switching a trigger on validates all of it. Any error → 422 workflow_trigger_invalid; every finding names the rule, the path, what is wrong and a hint how to fix it. {"active": false} alone always saves (emergency stop). dry_run=true returns the report without saving. Unknown placeholders that are filled at run time can be accepted with force=true (softens WT-06 only) — every forced save is logged. Every save is written to the trigger's change log.

Required API permission: “Edit workflows” (workflow_manage)

Example request:
curl --request PATCH \
    "https://{instance}.festiwa.re/api/v2/projects/564/workflow-triggers/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Welcome mail\",
    \"active\": true,
    \"data\": {
        \"subject\": {
            \"de\": \"Willkommen {{ firstname }}\",
            \"en\": \"Welcome {{ firstname }}\"
        }
    },
    \"conditions\": {
        \"and\": [
            {
                \"field\": \"data.shirt_size\",
                \"operator\": \"==\",
                \"value\": \"m\"
            }
        ]
    },
    \"delay_minutes\": 30,
    \"updated_at\": \"2026-10-08T09:00:00+00:00\",
    \"dry_run\": true,
    \"force\": false
}"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/workflow-triggers/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "Welcome mail",
    "active": true,
    "data": {
        "subject": {
            "de": "Willkommen {{ firstname }}",
            "en": "Welcome {{ firstname }}"
        }
    },
    "conditions": {
        "and": [
            {
                "field": "data.shirt_size",
                "operator": "==",
                "value": "m"
            }
        ]
    },
    "delay_minutes": 30,
    "updated_at": "2026-10-08T09:00:00+00:00",
    "dry_run": true,
    "force": false
};

fetch(url, {
    method: "PATCH",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/workflow-triggers/16';
$response = $client->patch(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'name' => 'Welcome mail',
            'active' => true,
            'data' => [
                'subject' => [
                    'de' => 'Willkommen {{ firstname }}',
                    'en' => 'Welcome {{ firstname }}',
                ],
            ],
            'conditions' => [
                'and' => [
                    [
                        'field' => 'data.shirt_size',
                        'operator' => '==',
                        'value' => 'm',
                    ],
                ],
            ],
            'delay_minutes' => 30,
            'updated_at' => '2026-10-08T09:00:00+00:00',
            'dry_run' => true,
            'force' => false,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Updated):


{
    "data": {
        "id": 77,
        "name": "Notify crew",
        "action_type": "notify_user",
        "triggers_on": [
            "enter"
        ],
        "active": true,
        "observed_id": 42,
        "data": {
            "notifiable_id": 123
        },
        "conditions": null,
        "delay_minutes": null,
        "updated_at": "2026-10-08T09:05:00+00:00"
    },
    "validation": {
        "valid": true,
        "requires_confirm_data_loss": false,
        "errors": [],
        "warnings": [],
        "data_impact": []
    }
}
 

Example response (200, DryRun):


{
    "data": {
        "dry_run": true,
        "would_save": false,
        "validation": {
            "valid": false,
            "requires_confirm_data_loss": false,
            "errors": [
                {
                    "rule": "WT-05",
                    "severity": "reject",
                    "field": "content",
                    "path": "data.content.de",
                    "message": "WT-05 at data.content.de: Twig syntax error in line 3: Unclosed \"if\".",
                    "hint": "Fix the Twig in line 3: every {% if %} / {% for %} needs its {% endif %} / {% endfor %}, every \"{{\" its \"}}\", every \"{%\" its \"%}\", every quote its closing quote."
                }
            ],
            "warnings": [],
            "data_impact": []
        }
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Example response (409, OptimisticLockFailed):


{
    "error": {
        "code": "optimistic_lock_failed",
        "message": "The resource was modified after your last read. Re-fetch and retry.",
        "errors": {
            "current": {
                "updated_at": "2026-10-08T09:05:00+00:00"
            }
        }
    }
}
 

Example response (422, Invalid):


{
    "error": {
        "code": "workflow_trigger_invalid",
        "message": "The trigger was not saved: 1 blocking error(s). Every entry in error.errors.validation.errors names the rule, the path, what is wrong and a \"hint\" how to fix it; entries with \"preexisting\": true do not block. Deactivating the trigger ({\"active\": false}) is always possible.",
        "errors": {
            "validation": {
                "valid": false,
                "requires_confirm_data_loss": false,
                "errors": [
                    {
                        "rule": "WT-07",
                        "severity": "reject",
                        "field": "content",
                        "path": "data.content.de",
                        "message": "WT-07 at data.content.de, line 1: The function `config_get()` is not allowed in templates: templates may only transform and format values, not read server state or run code.",
                        "hint": "Allowed functions: …"
                    }
                ],
                "warnings": [],
                "data_impact": []
            }
        }
    }
}
 

Example response (429, TooManyRequests):


{
    "error": {
        "code": "too_many_requests",
        "message": "Too many requests."
    }
}
 

Request      

PATCH api/v2/projects/{project_id}/workflow-triggers/{workflowTrigger_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

workflowTrigger_id   integer     

The ID of the workflowTrigger. Example: 16

project   integer     

Project id. Example: 2

workflowTrigger   integer     

Workflow trigger id (must belong to the project). Example: 77

Body Parameters

name   string  optional    

Display name. Must not be greater than 255 characters. Example: Welcome mail

active   boolean  optional    

Switch the trigger on/off. Switching on validates the whole trigger, also errors it already had (WT-13). {"active": false} alone (optionally with updated_at, dry_run, force) always saves — the emergency stop, also for a trigger with errors. Example: true

data   object  optional    

Keys to merge into the trigger data (shallow merge; keys of the trigger type only): subject and content (string or {"de": …, "en": …}), reply_to, notifiable_id, … Texts are Twig: syntax, placeholders and an allow-list are checked. A key you send must be fully valid, also errors it already had. Some actions need values that must not be empty (WT-16): create_event needs area (id of an area of this project), fieldname (the datetime field the event starts at) and duration (minutes, a whole number of at least 1); clearing one, setting duration to 0 or another unusable value, or switching on a trigger that lacks one, is refused.

conditions   object  optional    

Replaces the run conditions: {"and": [...]} / {"or": [...]} groups with {"field", "operator", "value"} leaves; null removes them.

delay_minutes   string  optional    

Delay before the action runs: empty/0 or 1–1440. Example: 30

updated_at   string  optional    

Optimistic lock: the updated_at you read. When sent, a newer stored version answers 409 optimistic_lock_failed. Recommended for content edits. Must be a valid date in the format Y-m-d\TH:i:sP. Example: 2026-10-08T09:00:00+00:00

dry_run   boolean  optional    

Validate only: returns the report and would_save, writes nothing. Example: true

force   boolean  optional    

Accept unknown placeholders (rule WT-06) that are filled at run time. Softens nothing else. Every forced save is logged. Example: false

List the workflows of a project.

requires authentication

Only workflows of the person and group types the user may see (as in the backend).

Required API permission: “Read workflows” (workflow_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/workflows?per_page=25" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/workflows"
);

const params = {
    "per_page": "25",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/workflows';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '25',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": [
        {
            "id": 42,
            "project_id": 2,
            "name": "Crew",
            "shortname": "crew",
            "description": null,
            "type": {
                "id": 7,
                "shortname": "CrewPerson",
                "model": "person"
            },
            "created_at": "2026-01-10T09:00:00+00:00",
            "updated_at": "2026-10-08T09:00:00+00:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 25,
        "total": 1
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Request      

GET api/v2/projects/{project_id}/workflows

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

project   integer     

Project id. Example: 2

Query Parameters

per_page   integer  optional    

Page size (1–100, default 25). Example: 25

Show a workflow with its steps.

requires authentication

Steps in their order, each with the ids of its triggers.

Required API permission: “Read workflows” (workflow_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/workflows/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/workflows/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/workflows/16';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": 42,
        "project_id": 2,
        "name": "Crew",
        "shortname": "crew",
        "description": null,
        "type": {
            "id": 7,
            "shortname": "CrewPerson",
            "model": "person"
        },
        "created_at": "2026-01-10T09:00:00+00:00",
        "updated_at": "2026-10-08T09:00:00+00:00",
        "steps": [
            {
                "id": 5,
                "name": "Applied",
                "shortname": "applied",
                "description": null,
                "is_start": true,
                "is_endpoint": false,
                "inactive": false,
                "previous_id": null,
                "trigger_ids": [
                    77,
                    78
                ]
            }
        ]
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/workflows/{id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

id   integer     

The ID of the workflow. Example: 16

project   integer     

Project id. Example: 2

workflow   integer     

Workflow id (must belong to the project). Example: 42

Show a workflow trigger.

requires authentication

The full trigger: texts (data.subject, data.content), recipients and other settings in data, run conditions, delay_minutes, active, and updated_at for the optimistic lock.

Required API permission: “Read workflows” (workflow_see)

Example request:
curl --request GET \
    --get "https://{instance}.festiwa.re/api/v2/projects/564/workflow-triggers/16" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://{instance}.festiwa.re/api/v2/projects/564/workflow-triggers/16"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://{instance}.festiwa.re/api/v2/projects/564/workflow-triggers/16';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, OK):


{
    "data": {
        "id": 77,
        "name": "Welcome mail",
        "action_type": "notify_self",
        "triggers_on": [
            "enter"
        ],
        "active": true,
        "observed_id": 42,
        "data": {
            "subject": {
                "de": "Willkommen {{ firstname }}"
            },
            "content": {
                "de": "<p>Hallo {{ firstname }}</p>"
            }
        },
        "conditions": null,
        "delay_minutes": null,
        "updated_at": "2026-10-08T09:00:00+00:00"
    }
}
 

Example response (401, Unauthorized):


{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required."
    }
}
 

Example response (403, Forbidden):


{
    "error": {
        "code": "permission_denied",
        "message": "You do not have permission to perform this action."
    }
}
 

Example response (404, NotFound):


{
    "error": {
        "code": "not_found",
        "message": "The requested resource was not found."
    }
}
 

Request      

GET api/v2/projects/{project_id}/workflow-triggers/{workflowTrigger_id}

Headers

Authorization        

Example: Bearer {ACCESS_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

project_id   integer     

The ID of the project. Example: 564

workflowTrigger_id   integer     

The ID of the workflowTrigger. Example: 16

project   integer     

Project id. Example: 2

workflowTrigger   integer     

Workflow trigger id (must belong to the project). Example: 77

Webhooks

festiware can call an HTTPS endpoint of yours whenever a record changes. This section lists every record type (model) that can send such a call, the events, the payload and how delivery works.

Overview

Envelope and headers

Unless the webhook has a payload mapping (see "Mapped payloads"), every call is a POST with this JSON body:

Key Content
event Wire name <resource>.<event>, e.g. person.updated.
timestamp ISO 8601 time at which the payload was built for sending (not the time of the change).
triggered_by source: system (console command or queued job), nova (backend), api (a request to festiware's API, which includes the portal and the ticket shop) or web (any other request); user_email of the logged-in user, null when there is none. A call sent again from the backend also carries retry_of, the id of the original delivery (see "Delivery, retries and timeout").
data The record, see the event catalog below.
{
    "event": "person.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": "…"
    }
}

Headers of every call:

Header Content
Content-Type application/json.
X-EXECUTION-ID Id of this delivery in festiware (webhook execution).
webhook-id Same id as X-EXECUTION-ID, as a string. Identical for the automatic retries of one delivery: use it to drop duplicates. A call sent again from the backend is a new delivery with a new id.
webhook-timestamp Unix time at which the call was queued. A call deferred by the rate limit carries the time of each actual attempt instead.
X-Event-Type Same as event in the envelope, also for mapped payloads.
X-Resource-Type Class name of the observed record, e.g. Person, NFCTag, WorkflowStep.
X-Instance-Id Id of the festiware instance that sends.
X-Instance-Name Short name of the festiware instance that sends.

Custom headers set on the webhook are added to these and override a default header of the same name.

Calls are not signed. There is no signature header. Protect your endpoint with HTTPS and a secret custom header (e.g. X-Webhook-Secret or Authorization) that you check on every call.

Delivery, retries and timeout

Rate limit and loop guard

Event timing, deduplication and what fires nothing

Event catalog

Every model below can be observed by a webhook trigger. The wire name is <resource>.<event> and is the same in the event field and in the X-Event-Type header. "Nested" lists the keys of data that hold related records; most of them carry only a few fields (id, name) of the related record, not the full record.

Model Wire name Events Payload data Nested
Application application.* created, updated, deleted, restored, portal_update ApplicationResource owner, application_type
Area area.* created, updated, deleted AreaResource –
Contract contract.* created, updated, deleted ContractResource partner, owner, contract_type
ContractType contract_type.* created, updated, deleted ContractTypeResource –
Coupon coupon.* created, updated, deleted CouponResource –
FormSubmission form_submission.* created, updated, deleted FormSubmissionResource form_definition, submittable
Invoice invoice.* created, updated, deleted InvoiceResource invoiceable
Meal meal.* created, updated, deleted, restored MealResource –
MealOrder meal_order.* created, updated, deleted MealOrderResource person, meal
MealType meal_type.* created, updated, deleted MealTypeResource areas
NFCTag n_f_c_tag.* created, updated, deleted, restored NFCTagResource person
Order order.* created, updated, deleted, restored OrderResource person, order_positions, order_statuses, transactions
OrderStatus order_status.* created, updated, deleted own toWebhookData() –
Pass pass.* created, updated, deleted, restored PassResource person, access
Person person.* created, updated, deleted, restored, portal_update PersonResource person_types, teams, events, jobs, current_nfc_tag, tickets_owned, orders, contracts, applicationsAsOwner, applicationsAsMember, passes, coupons
PersonType person_type.* created, updated, deleted PersonTypeResource –
SchedulerEvent scheduler_event.* created, updated, deleted, restored SchedulerEventResource area, schedulerEventType, attendees, jobs, applications
SchedulerEventType scheduler_event_type.* created, updated, deleted, restored SchedulerEventTypeResource –
SchedulerJob scheduler_job.* created, updated, deleted, restored SchedulerJobResource event, person, check_in_person, check_out_person
SchedulerPlan scheduler_plan.* created, updated, deleted, restored SchedulerPlanResource –
Supply supply.* created, updated, deleted SupplyResource supply_categories
SupplyCategory supply_category.* created, updated, deleted SupplyCategoryResource –
SupplyItem supply_item.* created, updated, deleted, restored SupplyItemResource supply, owner
SupplyOrder supply_order.* created, updated, deleted SupplyOrderResource person, supply_items
Team team.* created, updated, deleted TeamResource members, team_type
TeamRole team_role.* created, updated, deleted TeamRoleResource –
TicketCode ticket_code.* created, updated, deleted, restored own toWebhookData() current_ticket_code_status, current_nfc_tag
TicketCodeStatus ticket_code_status.* created, updated, deleted TicketCodeStatusResource ticket_code
TicketType ticket_type.* created, updated, deleted, restored TicketTypeResource –
Transaction transaction.* created, updated, deleted TransactionResource transactable
Voucher voucher.* created, updated, deleted VoucherResource recipient, beneficiary
Workflow workflow.* created, updated, deleted WorkflowResource steps
WorkflowStep workflow_step.* enter, leave resource of the person or group person_types, teams, events, jobs, current_nfc_tag, tickets_owned, orders, contracts, applicationsAsOwner, applicationsAsMember, passes, coupons

Application events

A group (company, crew, band, association) registered for a project, with a contact person (owner) and members.

Events: application.created, application.updated, application.deleted, application.restored, application.portal_update

Side effects and gaps:

Example (application.created):

{
    "event": "application.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "name": "Hamill LLC",
        "data": {
            "name": "Hamill LLC",
            "offer": "i"
        },
        "calculated_data": [],
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00",
        "deleted_at": null,
        "owner": null,
        "application_type": {
            "id": 2,
            "name": "Crew",
            "shortname": "CREW"
        },
        "scheduler_event": null,
        "form_submissions": null
    }
}

Area events

A location on the event site (stage, gate, camp, catering point), used by shifts and meal types.

Events: area.created, area.updated, area.deleted

Side effects and gaps:

Example (area.created):

{
    "event": "area.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "name": "Sint Stage",
        "shortname": null,
        "description": null,
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00"
    }
}

Contract events

A contract between the organiser (owner) and a partner person or group, based on a contract type.

Events: contract.created, contract.updated, contract.deleted

Side effects and gaps:

Example (contract.created):

{
    "event": "contract.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "contract_number": "C-2735",
        "current_state": "draft",
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00",
        "partner": {
            "id": "00000000-0000-4000-8000-000000000001",
            "name": "Price",
            "firstname": "Wilmer"
        },
        "owner": {
            "id": "00000000-0000-4000-8000-000000000002",
            "name": "Schinner",
            "firstname": "Jeanette"
        },
        "contract_type": {
            "id": 2,
            "name": "Artist contract",
            "shortname": "ARTIST"
        }
    }
}

ContractType events

A contract type: the kind of contract a contract is made from, and the person type of its partners.

Events: contract_type.created, contract_type.updated, contract_type.deleted

Example (contract_type.created):

{
    "event": "contract_type.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "name": "Artist contract",
        "shortname": "ARTIST",
        "is_signable": 1,
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00"
    }
}

Coupon events

A discount code for the ticket shop.

Events: coupon.created, coupon.updated, coupon.deleted

Side effects and gaps:

Example (coupon.created):

{
    "event": "coupon.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "code": "NPXG-1295",
        "type": "absolute",
        "description": null,
        "value": null,
        "active": 1,
        "is_singleuse": 1,
        "valid_from": null,
        "valid_until": null,
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00",
        "person": null
    }
}

FormSubmission events

One submission of a portal or registration form, with its raw data and processing status.

Events: form_submission.created, form_submission.updated, form_submission.deleted

Example (form_submission.created):

{
    "event": "form_submission.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "status": 0,
        "data": {
            "firstname": "Walton"
        },
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00",
        "form_definition": {
            "id": 2,
            "name": "Registration",
            "type": null
        },
        "submittable": null
    }
}

Invoice events

An invoice or credit note, for an order or for a person or group.

Events: invoice.created, invoice.updated, invoice.deleted

Side effects and gaps:

Example (invoice.created):

{
    "event": "invoice.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "invoice_number": "INV-0268",
        "prefix": "INV",
        "running_number": 1,
        "type": null,
        "document_type": null,
        "state": null,
        "description": null,
        "recipient": {
            "lastname": "Feest",
            "firstname": "Kelli"
        },
        "delivered_date": null,
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00",
        "invoiceable": {
            "id": "00000000-0000-4000-8000-000000000001",
            "type": "Order"
        }
    }
}

Meal events

A meal served at a time slot (e.g. Saturday lunch), of a meal type.

Events: meal.created, meal.updated, meal.deleted, meal.restored

Example (meal.created):

{
    "event": "meal.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "name": "Lunch",
        "description": null,
        "price": null,
        "cost": null,
        "stock": null,
        "max_per_order": 1,
        "served_from": "2026-06-01T10:00:00+02:00",
        "served_until": "2026-06-01T12:00:00+02:00",
        "published_from": null,
        "published_until": null,
        "bookable_from": null,
        "bookable_until": null,
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00",
        "meal_type": {
            "id": 2,
            "name": "Crew catering"
        }
    }
}

MealOrder events

A booking of a meal for a person.

Events: meal_order.created, meal_order.updated, meal_order.deleted

Side effects and gaps:

Example (meal_order.created):

{
    "event": "meal_order.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "amount": 1,
        "amount_consumed": 0,
        "status": "open",
        "ordered_at": null,
        "consumed_at": null,
        "is_adhoc_order": 0,
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00",
        "person": {
            "id": "00000000-0000-4000-8000-000000000001",
            "name": "Huel",
            "firstname": "Deborah"
        },
        "meal": {
            "id": 2,
            "name": "Lunch"
        }
    }
}

MealType events

A kind of meal (breakfast, lunch, crew catering) with the areas where it is served.

Events: meal_type.created, meal_type.updated, meal_type.deleted

Example (meal_type.created):

{
    "event": "meal_type.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "name": "Crew catering",
        "display_name": null,
        "description": null,
        "category": null,
        "areas": [],
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00"
    }
}

NFCTag events

An NFC chip or pass number linked to a person and/or a ticket.

Events: n_f_c_tag.created, n_f_c_tag.updated, n_f_c_tag.deleted, n_f_c_tag.restored

Example (n_f_c_tag.created):

{
    "event": "n_f_c_tag.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "tag_id": "0478OE89EN68",
        "tag_description": null,
        "is_valid": true,
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00",
        "person": null
    }
}

Order events

A ticket shop order with its positions, statuses and payments.

Events: order.created, order.updated, order.deleted, order.restored

Side effects and gaps:

Example (order.created):

{
    "event": "order.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": "00000000-0000-4000-8000-000000000001",
        "order_number": "26-06-ABC-DEF",
        "total_price": 0,
        "currency": "EUR",
        "payment_type": "bank",
        "email": "9ACC2FF9@example.com",
        "firstname": "Katheryn",
        "lastname": "Schneider",
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00",
        "deleted_at": null,
        "person": null,
        "order_positions": [],
        "order_statuses": [
            {
                "id": 1,
                "created_at": "2026-06-01T10:00:00+02:00",
                "order_status_type": null
            }
        ],
        "transactions": []
    }
}

OrderStatus events

One status entry in an order's history (OPEN, PAID, CANCELLED, ...). The payload is the ORDER, not the status row.

Events: order_status.created, order_status.updated, order_status.deleted

Side effects and gaps:

Example (order_status.created):

{
    "event": "order_status.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": "00000000-0000-4000-8000-000000000001",
        "orderNumber": "26-06-ABC-DEF",
        "total_price": 0,
        "currency": "EUR",
        "email": "94D3AD35@example.com",
        "firstname": "Lisette",
        "lastname": "Corwin",
        "address": "58356 Koepp Ferry",
        "address2": null,
        "zip": "30789",
        "city": "Conroyberg",
        "country": "Mauritius",
        "company": null,
        "vat_id": null,
        "payment_type": "bank",
        "payment_provider_oid": null,
        "data": null,
        "project_id": "Saison 1",
        "donation": null,
        "primary_order_id": null,
        "order_positions": [],
        "ticket_codes": [],
        "current_order_status": "OPEN"
    }
}

Pass events

A pass of a person for an access type.

Events: pass.created, pass.updated, pass.deleted, pass.restored

Example (pass.created):

{
    "event": "pass.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "name": "Backstage pass",
        "role": null,
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00",
        "person": {
            "id": "00000000-0000-4000-8000-000000000001",
            "name": "Keebler",
            "firstname": "Tod"
        },
        "access": {
            "id": 2,
            "name": "Backstage"
        }
    }
}

Person events

A person in a project: volunteer, artist, guest, visitor, staff member, depending on the person type.

Events: person.created, person.updated, person.deleted, person.restored, person.portal_update

Side effects and gaps:

Example (person.created):

{
    "event": "person.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": "00000000-0000-4000-8000-000000000001",
        "name": "Ernser",
        "firstname": "Ferne",
        "data": {
            "name": "Ernser",
            "email": "joaquin.gulgowski@example.com",
            "firstname": "Ferne",
            "phone_mobile": "904-270-1857"
        },
        "calculated_data": [],
        "checked_in_at": null,
        "deactivated_at": null,
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00",
        "person_types": [],
        "teams": [],
        "events": [],
        "jobs": [],
        "current_nfc_tag": null,
        "tickets_owned": [],
        "orders": [],
        "contracts": [],
        "applicationsAsOwner": [],
        "applicationsAsMember": [],
        "passes": [],
        "coupons": []
    }
}

PersonType events

A person type (category) such as Volunteer, Artist or Visitor, with its own forms and workflow.

Events: person_type.created, person_type.updated, person_type.deleted

Side effects and gaps:

Example (person_type.created):

{
    "event": "person_type.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "name": "Velit Crew",
        "shortname": "CATALOG_PT",
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00"
    }
}

SchedulerEvent events

A shift or programme slot in the scheduler, with its area, event type, attendees and jobs.

Events: scheduler_event.created, scheduler_event.updated, scheduler_event.deleted, scheduler_event.restored

Side effects and gaps:

Example (scheduler_event.created):

{
    "event": "scheduler_event.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": "00000000-0000-4000-8000-000000000001",
        "name": "Bar shift",
        "description": null,
        "start_at": "2026-06-01T10:00:00+02:00",
        "end_at": "2026-06-01T14:00:00+02:00",
        "scheduler_event_series_id": null,
        "series_slot_at": null,
        "data": null,
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00",
        "area": null,
        "schedulerEventType": null,
        "attendees": [],
        "jobs": [],
        "applications": []
    }
}

SchedulerEventType events

A category of scheduler events (e.g. Bar shift, Concert), with its colour.

Events: scheduler_event_type.created, scheduler_event_type.updated, scheduler_event_type.deleted, scheduler_event_type.restored

Example (scheduler_event_type.created):

{
    "event": "scheduler_event_type.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "name": "Bar shift",
        "color": "#FF0000",
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00"
    }
}

SchedulerJob events

A job (position) inside a scheduler event, assigned to a person, with check-in and check-out times.

Events: scheduler_job.created, scheduler_job.updated, scheduler_job.deleted, scheduler_job.restored

Side effects and gaps:

Example (scheduler_job.created):

{
    "event": "scheduler_job.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "name": "Bar",
        "allowed_teams": [],
        "checkedin_at": null,
        "accomplished_at": null,
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00",
        "event": {
            "id": "00000000-0000-4000-8000-000000000001",
            "name": "Bar shift",
            "start_at": "2026-06-01T08:00:00.000000Z",
            "end_at": "2026-06-01T12:00:00.000000Z"
        },
        "person": null,
        "check_in_person": null,
        "check_out_person": null
    }
}

SchedulerPlan events

A scheduler plan: a named time range that groups events, e.g. a festival weekend.

Events: scheduler_plan.created, scheduler_plan.updated, scheduler_plan.deleted, scheduler_plan.restored

Example (scheduler_plan.created):

{
    "event": "scheduler_plan.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "name": "Festival weekend",
        "shortname": "WEEKEND",
        "description": null,
        "start_at": "2026-06-01T10:00:00+02:00",
        "end_at": "2026-06-04T10:00:00+02:00",
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00"
    }
}

Supply events

A supply article (e.g. radio, wristband, T-shirt) in categories, with its items.

Events: supply.created, supply.updated, supply.deleted

Side effects and gaps:

Example (supply.created):

{
    "event": "supply.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "name": "ipsam",
        "description": "Provident ullam dolorum voluptatibus quae sapiente quia dolores.",
        "image_url": "https://via.placeholder.com/640x480.png/009944?text=et",
        "requires_existing_stock": 0,
        "allow_partial_duration": 0,
        "orderable_from": null,
        "orderable_to": null,
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00",
        "supply_categories": []
    }
}

SupplyCategory events

A category of supplies.

Events: supply_category.created, supply_category.updated, supply_category.deleted

Example (supply_category.created):

{
    "event": "supply_category.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "name": "Radios",
        "description": "Odit perspiciatis aut sed eveniet minus.",
        "image_url": null,
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00"
    }
}

SupplyItem events

One physical item of a supply (e.g. radio no. 12), possibly handed out to an owner.

Events: supply_item.created, supply_item.updated, supply_item.deleted, supply_item.restored

Example (supply_item.created):

{
    "event": "supply_item.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "name": "Radio 22",
        "description": null,
        "serial_number": null,
        "tag_number": null,
        "available_from": null,
        "available_to": null,
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00",
        "deleted_at": null,
        "supply": {
            "id": 2,
            "name": "facilis"
        },
        "owner": null
    }
}

SupplyOrder events

An order of a supply for a person.

Events: supply_order.created, supply_order.updated, supply_order.deleted

Side effects and gaps:

Example (supply_order.created):

{
    "event": "supply_order.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "amount": 1,
        "annotations": null,
        "directions": null,
        "order_from": null,
        "order_to": null,
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00",
        "person": {
            "id": "00000000-0000-4000-8000-000000000001",
            "name": "Schaefer",
            "firstname": "Grady"
        },
        "supply_items": []
    }
}

Team events

A team (e.g. Bar, Security) with its team type and members.

Events: team.created, team.updated, team.deleted

Side effects and gaps:

Example (team.created):

{
    "event": "team.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "name": "omnis",
        "shortname": "ALIQUAM",
        "description": null,
        "email": null,
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00",
        "members": [],
        "team_type": null
    }
}

TeamRole events

A role a team member can hold (e.g. Team lead).

Events: team_role.created, team_role.updated, team_role.deleted

Side effects and gaps:

Example (team_role.created):

{
    "event": "team_role.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "name": "Team lead",
        "shortname": "LEAD",
        "description": null,
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00"
    }
}

TicketCode events

A ticket (ticket code) of a ticket type, owned by a person or not yet personalised. The payload is the ticket record itself (not a webhook resource) with its current status and current NFC tag.

Events: ticket_code.created, ticket_code.updated, ticket_code.deleted, ticket_code.restored

Side effects and gaps:

Example (ticket_code.created):

{
    "event": "ticket_code.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": "00000000-0000-4000-8000-000000000001",
        "code": "6003NA22K00B",
        "source": null,
        "owner_id": null,
        "issuable_type": null,
        "issuable_id": null,
        "ticket_type_id": 1,
        "data": [],
        "additional_html_rendered": null,
        "additional_html_fingerprint": null,
        "mail_sent_at": null,
        "change_counter": 0,
        "created_at": "2026-06-01T08:00:00.000000Z",
        "updated_at": "2026-06-01T08:00:00.000000Z",
        "deleted_at": null,
        "order_position_id": null,
        "project_id": 1,
        "current_ticket_code_status": {
            "id": 1,
            "ticket_status": "valid",
            "source": null,
            "source_ref": null,
            "occurred_at": null,
            "ticket_code_id": "00000000-0000-4000-8000-000000000001",
            "created_at": "2026-06-01T08:00:00.000000Z",
            "updated_at": "2026-06-01T08:00:00.000000Z",
            "created_by": 1
        },
        "current_nfc_tag": null
    }
}

TicketCodeStatus events

One status entry in a ticket's history (valid, redeemed, revoked, ...), with its ticket.

Events: ticket_code_status.created, ticket_code_status.updated, ticket_code_status.deleted

Example (ticket_code_status.created):

{
    "event": "ticket_code_status.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "ticket_status": "valid",
        "created_at": "2026-06-01T10:00:00+02:00",
        "ticket_code": {
            "id": "00000000-0000-4000-8000-000000000001",
            "code": "72DFV4CPW017",
            "current_status": "valid"
        }
    }
}

TicketType events

A ticket type (e.g. Weekend ticket) that ticket codes and shop offers are made of.

Events: ticket_type.created, ticket_type.updated, ticket_type.deleted, ticket_type.restored

Side effects and gaps:

Example (ticket_type.created):

{
    "event": "ticket_type.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "name": "Weekend ticket",
        "shortname": "WKND",
        "description": "A776BB6298D9EE6C",
        "special_ticket": null,
        "available_in_backend": 1,
        "valid_from": null,
        "valid_to": null,
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00"
    }
}

Transaction events

A payment or refund booked on an order or another payable record.

Events: transaction.created, transaction.updated, transaction.deleted

Side effects and gaps:

Example (transaction.created):

{
    "event": "transaction.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "transaction_number": "72F7E6B473BAD513",
        "transaction_type": "bank",
        "balance": 0,
        "currency": "EUR",
        "reference": "059B7F239456BB65",
        "payment_method": null,
        "email": null,
        "psp_reference": null,
        "registered_at": "2026-06-01T10:00:00+02:00",
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00",
        "transactable": null
    }
}

Voucher events

A voucher of a voucher type, issued to a recipient and redeemed by a beneficiary.

Events: voucher.created, voucher.updated, voucher.deleted

Side effects and gaps:

Example (voucher.created):

{
    "event": "voucher.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": "00000000-0000-4000-8000-000000000001",
        "code": "5E37EC",
        "name": null,
        "type": "DRINK",
        "description": null,
        "value": null,
        "status": "Offen",
        "is_usable": true,
        "is_used": false,
        "is_revoked": false,
        "used_at": null,
        "revoked_at": null,
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00",
        "recipient": {
            "id": "00000000-0000-4000-8000-000000000002",
            "name": "Swaniawski",
            "firstname": "Jaylin"
        },
        "beneficiary": null
    }
}

Workflow events

The workflow of a person or group type in a project, with its steps.

Events: workflow.created, workflow.updated, workflow.deleted

Side effects and gaps:

Example (workflow.created):

{
    "event": "workflow.created",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": 1,
        "name": "Enim est quia nam.",
        "shortname": "AC6D7B19",
        "description": null,
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00",
        "steps": []
    }
}

Workflow step events

A step of a workflow. Its events are enter and leave; the payload data is the person or group that moved, not the step.

Events: workflow_step.enter, workflow_step.leave. X-Resource-Type is WorkflowStep. A trigger for these events is set on one step, so the step is known from the trigger; the step id is not in the payload.

data is the person (person resource, as in person.*) or the group (as in application.*) that entered or left the step.

Example (workflow_step.enter, a person):

{
    "event": "workflow_step.enter",
    "timestamp": "2026-06-01T10:00:00+02:00",
    "triggered_by": {
        "source": "api",
        "user_email": "api-user@example.com"
    },
    "data": {
        "id": "00000000-0000-4000-8000-000000000001",
        "name": "Lakin",
        "firstname": "Pierre",
        "data": {
            "name": "Lakin",
            "email": "santa.larkin@example.com",
            "firstname": "Pierre",
            "phone_mobile": "469-724-2067"
        },
        "calculated_data": [],
        "checked_in_at": null,
        "deactivated_at": null,
        "created_at": "2026-06-01T10:00:00+02:00",
        "updated_at": "2026-06-01T10:00:00+02:00",
        "person_types": [],
        "teams": [],
        "events": [],
        "jobs": [],
        "current_nfc_tag": null,
        "tickets_owned": [],
        "orders": [],
        "contracts": [],
        "applicationsAsOwner": [],
        "applicationsAsMember": [],
        "passes": [],
        "coupons": []
    }
}

Mapped payloads

A webhook can carry a payload mapping, set up in the backend for receivers that expect a fixed format. Then the body is only the mapped object, without the envelope (event, timestamp, triggered_by, data). The headers stay the same, so X-Event-Type still tells the event. The paths of a mapping refer to the keys of data as shown in the catalog above.