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
- A festiware instance with backend admin access
- Any HTTP client or library that supports OAuth 2.0 Authorization Code: your own code, automation tools such as n8n, Make or Zapier, Postman, Insomnia
Step 1 — Create an API User
In the festiware backend: API Users → Create API User
- Enter a descriptive name (e.g.
People sync) - Tick the API permissions the integration needs (e.g. “Read people and groups”, “Manage ticket types”). Every endpoint names its permission; the overview is under API permissions. No role is needed.
- Optional: restrict the API user to specific person and group types (Person and group types → Only these types). It then lists only people with at least one of those person types and groups of those group types; a single person or group of another type answers
404, a filter or body naming another type403with error codetype_not_allowed, nested people and groups of other types (group members, owners, event attendees) carry only theirid. Forms and workflows of other types are left out (403 type_not_allowedwhen requested directly);GET /person-typesandGET /application-typeslist only the chosen types. An update that would remove a person's last chosen person type answers422(the person would drop out of the API user's reach). A restricted API user cannot use the v1 people, group and form endpoints. Orders, tickets, invoices, contracts and check-in follow their own permissions only. - Form fields marked as protected (bank details, health data) come in plain text only with the API permission “Read protected fields” on the API user itself; a role does not count. Without it API v2 leaves them out.
- Form fields tagged with a data qualification come only when the API user holds it: section Data qualifications of the API user, per qualification read or read + write (shown only when the instance defines data qualifications). You can grant a qualification only at a level you hold yourself.
- Optional: restrict the API user to specific projects (Project Access). A restricted user gets
403with error codecross_project_access_deniedon every/projects/{project}/…route outside that list, andGET /projectslists only the projects it may use. Without a restriction the user reaches every project of the instance. - Redirect URI: enter the callback URL of your tool or app (exact match, see Understanding the Redirect URI). Left empty, the instance default applies.
- Save. festiware generates the password and the OAuth client (Authorization Code) for this API user automatically.
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:
- The redirect URI does not have to point to your tool, your server, or anything reachable at all. It is only the address the browser is sent to after a successful login — tools like Postman intercept that redirect locally and never actually load the URL.
- The only hard requirement: the redirect/callback URI configured in your tool must exactly match the one registered on the API user (Step 1) — same scheme, host, path, no extra trailing slash.
- On a mismatch the login fails with a redirect-URI error. Fix it on either side: change the callback URL in your tool, or change the Redirect URI field of the API user in the backend (the OAuth client follows it).
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:
- Open the authorization URL in a browser with
response_type=code,client_id,redirect_uri(exactly as registered in Step 1) and a randomstate:https://{instance}.festiwa.re/oauth/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&state={state} - Log in with the API-user email + password from the credentials file (Step 2). The consent screen shows the client name → Authorize.
- The browser is sent to your redirect URI with
?code=…&state=…. Check thatstatematches, 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
- Access tokens expire after 1 hour. Exchange the refresh token for a new access token before or after expiry:
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}
- Each refresh returns a new refresh token as well; keep the latest one.
- Refresh tokens are valid for 1 year; after that, run the browser authorization (Step 3) once more.
- If the client secret is compromised: run Actions → Reset Credentials on the API user. It issues a new password and OAuth client and invalidates the old ones at once. Download the credentials again (Step 2) and authorize again (Step 3).
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
- In n8n: Credentials → New → OAuth2 API. Register n8n's callback URL
https://{n8n-instance}/rest/oauth2-credential/callbackas 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) |
- 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.
- n8n stores the refresh token and renews the access token automatically, no manual action.
- 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
- Import or create a request/collection and open the Authorization tab → Type OAuth 2.0.
- 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 |
- 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. - 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.
- 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.
- A retry with the same key and the same payload within 24 hours does not run again. It returns the stored response with the same status and body, plus the header
Idempotent-Replayed: true. - A key is scoped to the API user and the endpoint, including the project and resource ids in the path. The same key on another endpoint, another project or by another API user is a separate request. The payload covers the query string and the body; the order of object keys does not matter.
- The same key with a different payload answers
422witherror.code=idempotency_key_reused. This includes the same body with another query string (e.g.?dry_run=trueadded). - If the API user's permissions, its Project Access or its type restriction changed since the key was first used, the stored response is not replayed: the API answers
409witherror.code=idempotency_permissions_changed. Send the request again with a new key; it then runs with the current permissions. - While the first request with that key is still running, a second one answers
409witherror.code=idempotency_in_progressandRetry-After: 1. - An invalid key answers
422witherror.code=idempotency_key_invalid. - Only successful responses (
2xx) and validation errors (422) are stored.5xx,401,403,404,409and429are not; you may retry them with the same key. PUT,PATCHandDELETEignore the header: they are protected by the optimistic lock (updated_atin the body, orIf-Matchwhere an endpoint names it) and, for destructive actions, byconfirm: true.- A replayed call still counts against the daily call allowance.
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}/peopleGET /projects/{project}/people/{person}GET /projects/{project}/applicationsGET /projects/{project}/applications/{application}GET /projects/{project}/applications/{application}/files/{field}GET /projects/{project}/people/{person}/files/{field}GET /projects/{project}/applications/{application}/commentsGET /projects/{project}/people/{person}/commentsGET /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/bulkPOST /projects/{project}/people/{person}/transitionsPOST /projects/{project}/applications/transitions/bulkPOST /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}/peopleDELETE /projects/{project}/people/{person}POST /projects/{project}/applicationsDELETE /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}/settingsGET /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}/settingsPUT, PATCH /projects/{project}/application-types/{applicationType}/settings |
Users & roles
| API permission | Key | Includes | Endpoints (API v2) |
|---|---|---|---|
| Read users and roles | user_see |
— | GET /usersGET /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 /usersDELETE /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}/validationGET /projects/{project}/form-definitionsGET /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-checksGET /projects/{project}/access-holdersGET /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}/ordersGET /projects/{project}/orders/{order}GET /projects/{project}/offer-categoriesGET /projects/{project}/offer-categories/{category}GET /projects/{project}/offerable-optionsGET /projects/{project}/offerable-options/{option}GET /projects/{project}/offer-categories/{category}/offersGET /projects/{project}/offersGET /projects/{project}/offers/{offer} |
| Manage offers | order_administrate |
Read orders and offers | POST /projects/{project}/offer-categoriesPUT, PATCH /projects/{project}/offer-categories/{category}DELETE /projects/{project}/offer-categories/{category}POST /projects/{project}/offerable-optionsPUT, PATCH /projects/{project}/offerable-options/{option}DELETE /projects/{project}/offerable-options/{option}POST /projects/{project}/offersPUT, PATCH /projects/{project}/offers/{offer}DELETE /projects/{project}/offers/{offer} |
| Read tickets | ticketcode_see |
— | GET /projects/{project}/ticket-typesGET /projects/{project}/ticket-types/{ticket_type}GET /projects/{project}/ticket-codesGET /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-typesPUT, 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}/couponsGET /projects/{project}/coupons/{coupon} |
| Manage coupons | app\modules\coupons\policies\coupon_administrate |
Read coupons | POST /projects/{project}/couponsPATCH /projects/{project}/coupons/{coupon}DELETE /projects/{project}/coupons/{coupon} |
| Read invoices | invoice_see |
— | GET /projects/{project}/invoicesGET /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}/eventsGET /projects/{project}/event-types |
| Read areas | area_see |
— | GET /projects/{project}/areasGET /projects/{project}/area-typesGET /projects/{project}/area-types/{type} |
| Read teams | team_see |
— | GET /projects/{project}/people (depending on the request)GET /projects/{project}/teamsGET /projects/{project}/teams/{team}GET /projects/{project}/teams/{team}/membersGET /projects/{project}/team-roles |
| Manage team members | team_manage |
Read teams | POST /projects/{project}/teams/{team}/membersDELETE /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-typesDELETE /projects/{project}/area-types/{type} |
| Edit scheduler | scheduler_manage |
Read scheduler | — |
| Manage scheduler | scheduler_administrate |
Edit scheduler, Read scheduler | POST /projects/{project}/event-plansDELETE /projects/{project}/event-plans/{plan}POST /projects/{project}/event-typesPUT, 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}/suppliesGET /projects/{project}/supply-categoriesGET /projects/{project}/supplies/{supply}/itemsGET /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}/exportGET /projects/{project}/workflows/{workflow}/triggersGET /projects/{project}/workflowsGET /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/importPATCH /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}/triggersDELETE /projects/{project}/webhooks/{webhook}/triggers/{workflowTrigger} |
| Send webhook responses | webhook_manage |
— | GET /projects/{project}/webhooksGET /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}/webhooksDELETE /projects/{project}/webhooks/{webhook}POST /projects/{project}/webhooks/{webhook}/triggersDELETE /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}/settingsPATCH /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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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 ofdataandcalculated_data, also of nested people and groups, and a nested person's name or e-mail or a group'snameisnull.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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 ofdataandcalculated_data, also of nested people and groups, and a nested person's name or e-mail or a group'snameisnull.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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 ofdataandcalculated_data, also of nested people and groups, and a nested person's name or e-mail or a group'snameisnull.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Update a Person.
requires authentication
Both PUT and PATCH route here. The behavioural switch is replaceMissing:
- PUT → replaceMissing=true (full replace; absent
datakeys cleared) - PATCH → replaceMissing=false (sparse merge; absent keys preserved)
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 ofdataandcalculated_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 aPUTthat leaves it out), andwarningsnames 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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Advance many Persons in one request.
requires authentication
force=false(default): every id is pre-validated; if ANY would fail, the response is 400bulk_validation_failedwith afailed_idsarray and no Person is transitioned.force=true: every id is processed; failures are reported per-entity inside a 200 response. Sync/async dispatch still follows ChangeWorkflowStepJob::$maxModelsForAsync (default 25); above that threshold the response is 202dispatched.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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 ofdataandcalculated_data, also of nested people and groups, and a nested person's name or e-mail or a group'snameisnull.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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 ofdataandcalculated_data, also of nested people and groups, and a nested person's name or e-mail or a group'snameisnull.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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 ofdataandcalculated_data, also of nested people and groups, and a nested person's name or e-mail or a group'snameisnull.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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 ofdataandcalculated_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 aPUTthat leaves it out), andwarningsnames 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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Advance many Groups in one request.
requires authentication
force=false(default): every id is pre-validated; if ANY would fail, the response is 400bulk_validation_failedwith afailed_idsarray and no Group is transitioned.force=true: every id is processed; failures are reported per-entity inside a 200 response. Sync/async dispatch still follows ChangeWorkflowStepJob::$maxModelsForAsync (default 25); above that threshold the response is 202dispatched.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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 answers404and uploading or deleting one422.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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 answers404and uploading or deleting one422.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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 answers404and uploading or deleting one422.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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 answers404and uploading or deleting one422.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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 answers404and uploading or deleting one422.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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 answers404and uploading or deleting one422.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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 ofdataandcalculated_data, also of nested people and groups, and a nested person's name or e-mail or a group'snameisnull.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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 ofdataandcalculated_data, also of nested people and groups, and a nested person's name or e-mail or a group'snameisnull.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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!"
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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 ofdataandcalculated_data, also of nested people and groups, and a nested person's name or e-mail or a group'snameisnull.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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 ofdataandcalculated_data, also of nested people and groups, and a nested person's name or e-mail or a group'snameisnull.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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 ofdataandcalculated_data, also of nested people and groups, and a nested person's name or e-mail or a group'snameisnull.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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 ofdataandcalculated_data, also of nested people and groups, and a nested person's name or e-mail or a group'snameisnull.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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"
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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:
granted— the person holds at least one configured gatedenied— the person holds none of them; compareaccess_groupsagainstrequired_gatesidentified— no gate is configured for this project on this user, so no verdict is rendered. This is the identify-only mode ("whose wristband is this?"), not an error.tag_devalidated— the badge exists but was superseded (pass reprinted) or deleted. Show this differently from a denial: the person is usually entitled, the badge is stale.unknown— nothing resolves for this code
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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!"
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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: \"3f2c…\" 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": ""3f2c…" 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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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:
errors— would block saving (reject)warnings— saving works, but something is probably not what the author intendeddata_impact— needsconfirm_data_loss=trueon a write
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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):
- What you change must be clean: every error on a field, settings section or attribute the
request changes → 422
form_definition_invalid, nothing saved — old errors in it included, so legacy flaws are fixed on the way. Errors elsewhere that the stored version already had (preexisting: true) are reported but do not block. Each finding names the rule, the JSON path, what is wrong and, inhint, how to fix it. data_impact→ 422confirm_data_loss_requiredunlessconfirm_data_loss=true.dry_run=true→ 200 with the report andwould_save, nothing saved.- Twig code of calculated fields may only transform and format values (rule FD-L13).
- Changing data qualification (
dqt_ids) of a field, or deleting a protected field, needs the admin role (rule FD-X02).
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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:
- when the webhook has
headersor apayload_mapping, send them again in the same request ({}/nullto drop them): stored header values never follow a URL you pick (422 otherwise); - you need the read permission of every model this project's triggers of the webhook send
(same rule as attaching a trigger: 403
permission_denied/data_qualification_restricted).
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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"
}
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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
- A webhook is the endpoint: URL, optional custom headers, timeout and an optional payload mapping. Webhooks are set up in the festiware backend. Managing them through the API v2 is in preparation; this page will link to those endpoints once they are released.
- A webhook is sent by a trigger with the action "Call webhook". The trigger observes one model (e.g. Person) and the events it reacts to (
created,updated, ...), or one workflow step (enter,leave). - A trigger can be limited by conditions and to one person or group type, and it can be delayed by a number of minutes. A delayed call sends the record as it is when the delay is over.
- The event catalog below is generated from the festiware code. The examples use invented data.
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
- Calls are queued per festiware instance and sent by a background worker as
POSTwith a JSON body. - An attempt succeeds when your endpoint answers with a 2xx status. Any other status, a connection error or a timeout is a failure.
- Timeout per attempt: 15 s, or the timeout set on the webhook, at most 60 s.
- 3 attempts in total. After a failed attempt festiware waits 10 s, then 100 s before the next one. When the last attempt fails, the call is given up.
- Every call is logged in the backend (webhook executions). A failed or rate-limited call can be sent again from there. Such a manual retry is a new delivery:
- it sends the current state of the record;
eventandX-Event-Typeare<resource>.retrywith the resource of the record itself, e.g.person.retry; for a workflow step call that is the person or group (person.retry,application.retry,X-Resource-TypePersonorApplication), notworkflow_step.*;triggered_by.sourceisnovaandtriggered_by.retry_ofis the id of the original delivery (itswebhook-id);- it has a new
webhook-id/X-EXECUTION-ID. When you have already processed the original, useretry_ofto drop it.
- Duplicates: when your endpoint is slower than the timeout, festiware counts the attempt as failed and sends it again, although your endpoint may have processed it. Answer quickly and process afterwards, ask for a longer webhook timeout, and drop calls whose
webhook-idyou have already processed. - Order: calls are not guaranteed to arrive in order of the changes (retries, deferred calls). When order matters, read the current record through the API.
Rate limit and loop guard
- An instance sends at most 60 webhook calls per minute by default; the instance's contract can set a different limit, never more than 600 per minute.
- Calls over the limit are deferred, not dropped: each is queued for the next free slot. Only when the backlog would exceed 900 s of calls (7200 s on instances without a limit) are further calls refused and logged as rate limited (
backlog_full). - Loop guard: when the same webhook fires for the same record more than 20 times in 10 minutes or more than 60 times in an hour, that webhook is paused for that record for 600 s; its calls are logged as rate limited (
loop_guard). The usual cause is a receiver that writes back to festiware and so fires the webhook again. - An inactive webhook sends nothing. Calls deferred before it was switched off still go out.
Event timing, deduplication and what fires nothing
created,updatedandrestoredare sent after the request (or console command) that made the change has finished, with the record as it is then, read again from the database. Relations saved later in the same request, such as the person types of a new person, are included.deletedis sent after the request too, with the record as it was when it was deleted.portal_updateandworkflow_step.*are sent during the request.- Per request, a trigger sends one call per record and event: a record saved twice in one request sends one
updated. - Trigger options can skip a call: an inactive trigger, "skip after backend creation", "once per journey".
- Fires nothing:
- Changes stored only in a link table: the person types of a person, team members, attendees and groups of a scheduler event, group members, the items of a supply order. Only a save of the record itself in the same request sends an
updated. - Bulk changes that festiware writes with a single database query instead of saving each record (example: syncing a scheduler plan from the teams' demand removes jobs this way).
- Calculated fields recomputed after a change are saved without events. Exception: when a form is saved and its calculated fields are recomputed for all records,
updatedtriggers that have a condition fire for the records whose condition turns from false to true. - The internal directory copies of persons and groups (project 0).
- Records of a deleted project.
- Changes stored only in a link table: the person types of a person, team members, attendees and groups of a scheduler event, group members, the items of a supply order. Only a save of the record itself in the same request sends an
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:
- Saving the group through a portal form (update) fires
application.portal_updatein addition toapplication.updated. - Deleting a group also deletes members that have a single person type and no other group (
person.deleted); other members are only detached, which fires nothing. - Moving the group to another workflow step fires
workflow_step.leaveandworkflow_step.enter(see "Workflow step events"), notapplication.updated. - Adding or removing members writes a pivot table and fires nothing.
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:
- An area that scheduler events still use cannot be deleted: the delete is refused and nothing fires.
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:
- A person with a contract that is not cancelled cannot be deleted, so no
person.deletedfollows.
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:
- Redeeming a coupon writes the coupon onto an order position of the order, not onto the coupon: the coupon fires nothing, watch
order.*instead. - A coupon that was used in an order cannot be deleted: the delete is refused and nothing fires.
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:
- An order gets its invoice (
invoice.created) the first time its invoice PDF is produced (ticket mail, invoice download, backend invoice action); later runs reuse it. - A refund creates a credit note, which is an invoice record too (
invoice.created).
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:
- A meal order that can no longer be changed (e.g. already consumed) is not deleted, and nothing fires.
- Deleting a person deletes its meal orders one by one (
meal_order.deletedeach).
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:
- Creating an order creates its first status OPEN (
order_status.created). - Every status change creates an
order_status.created; saving that status writescurrent_statuson the order, which firesorder.updatedwhen the value changes. - Status PAID queues the ticket issue unless the order already has tickets: each ticket issued fires
ticket_code.createdandticket_code_status.created. - Status CANCELLED, RETURNREQUESTED or RETURNED, and deleting the order, revoke its tickets where the ticket state allows it (
ticket_code_status.createdper ticket).
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:
datais the order this status belongs to (order resource), so receivers see the order after the change; readcurrent_order_statusfrom it.- A payment (transaction) that brings the open amount to zero creates status PAID (CONFLICTING instead for some cancelled orders).
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:
- Saving the person through a portal form (update) fires
person.portal_updatein addition toperson.updated. - Creating a person in the backend starts the workflow of its types:
workflow_step.enteron the first step. - Moving the person to another workflow step fires
workflow_step.leaveandworkflow_step.enter, notperson.updated. - Deleting a person revokes its tickets (
ticket_code_status.createdper ticket) and deletes its meal orders and received vouchers (meal_order.deleted,voucher.deleted). - A person with shifts, contracts or invoices cannot be deleted in the backend: the delete is refused and nothing fires.
- Deleting the last ticket of a visitor (only person type Visitor, still in workflow step REGISTERED) deletes the visitor too (
person.deleted). - The internal directory copy of a person (project 0) never fires.
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:
- Creating a person type creates its workflow in every project (
workflow.createdper project). - Deleting a person type deletes its workflows (
workflow.deleted). - Giving a person a type or taking it away writes a pivot table and fires nothing on the person or the type.
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:
- Deleting an event deletes its jobs one by one (
scheduler_job.deletedeach). - Adding or removing attendees and groups writes a pivot table and fires nothing.
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:
- A job saved without a name is saved a second time with a generated name, so
scheduler_job.createdis followed byscheduler_job.updated. - Restoring a job whose event is deleted restores the event too (
scheduler_event.restored). - Changing the allowed teams of a job updates its event quietly: no
scheduler_event.updated. - Syncing a plan from the teams' demand removes surplus jobs with one query: no
scheduler_job.deletedfor them.
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:
- A supply that still has items (also deleted ones) cannot be deleted: the delete is refused and nothing fires.
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:
- Assigning items to a supply order writes a pivot table and fires nothing.
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:
- A team that scheduler jobs still reference cannot be deleted: the delete is refused and nothing fires.
- Adding or removing team members writes a pivot table and fires nothing.
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:
- A role still held by team members cannot be deleted: the delete is refused and nothing fires.
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:
- Creating a ticket creates its first status (
ticket_code_status.created). - Every status change (redeemed, revoked, ...) is a new
ticket_code_status.created; the ticket row itself does not change, so noticket_code.updated. - Deleting the last ticket of a visitor can delete the visitor (
person.deleted, see Person).
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:
- A ticket type with offers or codes cannot be deleted: the delete is refused and nothing fires.
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:
- A transaction saved to an order that brings the open amount to zero creates status PAID (
order_status.created, see Order for what follows).
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:
- Redeeming a voucher fires
voucher.updated(beneficiary andused_atset).
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:
- Deleting a workflow deletes its steps; steps fire no CRUD events.
- The last workflow of a default type in a project is not deleted, and nothing fires.
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.
workflow_step.leave(old step) andworkflow_step.enter(new step) fire before the new step is stored; the person or group row itself is not saved.- These calls are queued during the request, the model events of the same request only after it (see "Event timing"). A
workflow_step.enterfor a person created in the backend can therefore arrive before itsperson.created.
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.