{ "openapi": "3.0.0", "info": { "title": "UiTPAS API", "version": "4.0", "contact": { "name": "publiq helpdesk", "email": "technical-support@publiq.be", "url": "https://docs.publiq.be" }, "description": "With UiTPAS API 4.0 you can retrieve ticket prices and register ticket sales for passholders. You can also save UiTPAS points and exchange them for rewards for a passholder, and much more." }, "servers": [ { "url": "https://api-test.uitpas.be", "description": "Testing" }, { "url": "https://api.uitpas.be", "description": "Production" } ], "tags": [ { "name": "Associations" }, { "name": "Card Systems" }, { "name": "Cards" }, { "name": "Checkins" }, { "name": "Current Passholder" }, { "name": "Events" }, { "name": "Financial reports" }, { "name": "Grouppasses" }, { "name": "Kiosk devices" }, { "name": "Kiosks" }, { "name": "Orders" }, { "name": "Organizers" }, { "name": "Passholder Family" }, { "name": "Passholders" }, { "name": "Permissions" }, { "name": "Rewards" }, { "name": "Schools" }, { "name": "SocialTariffValidation" }, { "name": "Ticket sales" }, { "name": "UiTiD" } ], "paths": { "/tariffs": { "parameters": [], "get": { "summary": "Get tariffs", "tags": [ "Ticket sales" ], "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TariffsResponse" }, "examples": { "Single tariff example": { "value": { "available": [ { "id": "SOCIALTARIFF-1", "name": "Kansentarief", "price": 1.5, "type": "SOCIALTARIFF", "remaining": 1 } ] } }, "Multiple tariffs example": { "value": { "available": [ { "id": "SOCIALTARIFF-1", "name": "Kansentarief", "price": 1.5, "remaining": 1, "type": "SOCIALTARIFF" }, { "id": "COUPON1234", "name": "Cultuurbon 6 euro", "price": 4, "remaining": 1, "type": "COUPON" }, { "id": "COUPON2345", "name": "2 euro korting op een specifiek event", "price": 8, "remaining": 1, "type": "COUPON" } ] } }, "Single tariff with multiple number of tickets": { "value": { "available": [ { "id": "SOCIALTARIFF", "name": "Kansentarief", "price": 1.5, "remaining": 20, "type": "SOCIALTARIFF" } ] } }, "No available tariffs with message about social tariff": { "value": { "available": [], "endUserMessage": { "nl": "Je hebt geen recht meer op kansentarief voor deze activiteit. Je kan maximaal 1 ticket per maand kopen aan kansentarief voor deze activiteit." } } }, "Coupon tariff with message about social tariff": { "value": { "available": [ { "id": "COUPON2345", "name": "2 euro korting op een specifiek event", "price": 8, "remaining": 1, "type": "COUPON" } ], "endUserMessage": { "nl": "Je hebt geen recht meer op kansentarief voor deze activiteit. Je kan maximaal 1 ticket per maand kopen aan kansentarief voor deze activiteit." } } }, "No available tariffs with message about coupon": { "value": { "available": [], "endUserMessage": { "nl": "Je hebt een coupon voor deze activiteit, maar je kan hiermee maximaal 1 ticket per maand kopen." } } } } } } }, "400": { "description": "Bad Request. The response will include a JSON body with more details in the form of a RFC7807 error model. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/event-not-found\n* https://api.publiq.be/probs/uitpas/passholder-not-found\n* https://api.publiq.be/probs/uitpas/passholder-no-active-cardsystems\n* https://api.publiq.be/probs/uitpas/social-tariff-expired\n* https://api.publiq.be/probs/uitpas/social-tariff-suspended\n* https://api.publiq.be/probs/uitpas/invalid-uitpasnumber\n* https://api.publiq.be/probs/uitpas/invalid-card\n* https://api.publiq.be/probs/uitpas/invalid-card-status\n\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Event not found": { "value": { "type": "https://api.publiq.be/probs/uitpas/event-not-found", "title": "Event id 267B6FCF-46F8-4DA2-8D7D-AADCD2C2715E not found", "status": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "get-tariffs", "description": "Returns the possible UiTPAS discounted **tariffs for an event and a passholder**.\n\nThis UiTPAS tariffs are calculated based on:\n\n- **The regular price** of the ticket.\nThis is the price your user would have to pay for the specific ticket without UiTPAS discount.\n- **The UiTPAS number** of the passholder. UiTPAS discounts are personal so it's important to identify the passholder to retrieve a list of possible tariffs.\n- **The event id** of the UiTdatabank event. UiTPAS discounts are limited to specific UiTdatabank events, so it's important to specify the event id to retrieve a list of possible tariffs.\n\n> ##### Important\n> The regular price of the ticket should generally be one of the price categories set on the event in UiTdatabank to make financial reporting clearer.\n\nThe caller of this request must have `TARIFFS_READ` permission for the organizer of the given event.", "security": [ { "USER_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] }, { "CLIENT_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] } ], "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "regularPrice", "description": "The regular price the passholder would have to pay for the ticket if they are not eligible for discounts", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "eventId", "description": "The id of the event for which the ticket is sold", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "uitpasNumber", "description": "UiTPAS Number identifying the passholder who wants to buy a ticket", "required": true }, { "schema": { "type": "string", "enum": [ "ANY", "SOCIALTARIFF", "COUPON" ], "default": "ANY" }, "in": "query", "name": "type", "description": "Return only available tariffs of this type. Defaults to ANY type.", "required": false } ] } }, "/tariffs/static": { "parameters": [], "get": { "summary": "Get static tariffs without passholder", "tags": [ "Ticket sales" ], "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TariffsResponse" }, "examples": { "Social tariff": { "value": { "available": [ { "id": "SOCIALTARIFF-1", "name": "Kansentarief", "price": 1.5, "type": "SOCIALTARIFF", "remaining": 1 } ] } } } } } }, "400": { "description": "Bad Request. The response will include a JSON body with more details in the form of a RFC7807 error model. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/event-not-found\n* https://api.publiq.be/probs/uitpas/social-tariff-not-available\n\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Event not found": { "value": { "type": "https://api.publiq.be/probs/uitpas/event-not-found", "title": "Event id 267B6FCF-46F8-4DA2-8D7D-AADCD2C2715E not found", "status": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "get-tariffs-static", "description": "Returns the **static** UiTPAS discounted **tariffs for an event**.\n \n\n \n> ##### Important\n> UiTPAS tariffs are different for each indiviual passholder, but this endpoint does NOT take the passholder into consideration. Use this endpoint only in specific cases, e.g. when listing the UiTPAS tariff before the passholder is known. The actual passholder tariffs might be different than this response. Use [GET /tariffs](/reference/uitpas.json/paths/~1tariffs/get) to retrieve indidivual tariffs for a passholder.\n \n\nThis UiTPAS tariffs are calculated based on:\n\n- **The regular price** of the ticket.\nThis is the price your user would have to pay for the specific ticket without UiTPAS discount.\n- **The event id** of the UiTdatabank event. UiTPAS discounts are limited to specific UiTdatabank events, so it's important to specify the event id to retrieve a list of possible tariffs.\n\nBecause the passholder is unknown, UiTPAS will return the tariffs for a passholder with social tariff, who lives in the same region as the event organizer.\n\nThe caller of this request must have `TARIFFS_READ` permission for the organizer of the given event.", "security": [ { "USER_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] }, { "CLIENT_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] } ], "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "regularPrice", "description": "The regular price the passholder would have to pay for the ticket if they are not eligible for discounts", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "eventId", "description": "The id of the event for which the ticket is sold", "required": true } ] } }, "/ticket-sales": { "parameters": [], "post": { "summary": "Register ticket sale(s)", "tags": [ "Ticket sales" ], "operationId": "post-ticket-sales", "responses": { "200": { "description": "Ticket sale registration(s) succeeded", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TicketSale" } }, "examples": { "Single ticket sale example": { "value": [ { "id": "21345", "tariff": { "id": "COUPON1234", "name": "Cultuurbon 6 euro", "price": 1.5, "type": "COUPON" }, "uitpasNumber": "0560002524314", "eventId": "31e926e2-a35f-11eb-bcbc-0242ac130002", "regularPrice": 10, "regularPriceLabel": "Optional descriptive label of the regular price. Used in financial reporting." } ] }, "Multiple ticket sales example": { "value": [ { "id": "21345", "tariff": { "id": "COUPON1234", "name": "Cultuurbon 6 euro", "price": 4, "type": "COUPON" }, "uitpasNumber": "0560002524314", "eventId": "31e926e2-a35f-11eb-bcbc-0242ac130002", "regularPrice": 10, "regularPriceLabel": "Optional descriptive label of the regular price. Used in financial reporting." }, { "id": "21346", "tariff": { "id": "SOCIALTARIFF", "name": "Kansentarief", "price": 1.5, "type": "SOCIALTARIFF" }, "uitpasNumber": "0940002524123", "eventId": "31e926e2-a35f-11eb-bcbc-0242ac130002", "regularPrice": 10, "regularPriceLabel": "Optional descriptive label of the regular price. Used in financial reporting." } ] } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data\n* https://api.publiq.be/probs/uitpas/social-tariff-expired\n* https://api.publiq.be/probs/uitpas/social-tariff-suspended\n* https://api.publiq.be/probs/uitpas/maximum-reached\n* https://api.publiq.be/probs/uitpas/invalid-number-of-tickets\n* https://api.publiq.be/probs/uitpas/event-not-found\n* https://api.publiq.be/probs/uitpas/passholder-not-found\n* https://api.publiq.be/probs/uitpas/invalid-uitpasnumber\n* https://api.publiq.be/probs/uitpas/invalid-card\n* https://api.publiq.be/probs/uitpas/invalid-card-status\n* https://api.publiq.be/probs/uitpas/passholder-no-active-cardsystems\n* https://api.publiq.be/probs/uitpas/invalid-coupon\n\n\nThe type indicates the error on one of the failed ticket sale registrations. All other ticket sale registration in the request will be rolled back in case of an error.\n\nThe property `jsonPointer` will a referene to the erroneous `TicketSaleRequest` object if applicable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Social tariff discount expired": { "value": { "type": "https://api.publiq.be/probs/uitpas/social-tariff-discount-expired", "title": "Social tariff discount expired", "status": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "description": "Registers one or more new ticket sales **with a discounted UiTPAS tariff**, so the UiTPAS organiser can get reimbursed for the discount.\n\nBefore you can register a discounted ticket sale, you will need to request the possible discounted tariffs from the `GET /tariffs` endpoint and let your end user pick one of the available tariffs. Afterward, you can register a ticket sale using this endpoint. \n\nYou will need:\n\n- The `uitpasNumber` of the passholder buying the ticket.\n- The `eventId` of the UiTdatabank event.\n- The chosen `tariff` from the `GET /tariffs` request. (only the `id` is required)\n- The `regularPrice` the passholder would normally have to pay for this ticket\n\nOptionally you can include:\n- a `regularPriceLabel` describing the regular price if you have multiple price \ncategories, which can be useful in the financial reporting overview.\n\nIf you want to register more than one ticket sale for the same passholder, for the same event, at the same tariff, use multiple `TicketSale` objects in this request. Do note this is only possible if `remaining` was higher than one in the `GET /tariffs` request.\n\nThe `passholder` field of `TicketSale` is ignored in the request body. It is included in the response if applicable (passholder can be empty in some cases, e.g. for group passes), but only if the caller of this request has `PASSHOLDERS_SEARCH` permission.\n\n\n\n> ##### Error handling\n> **If one of the ticket sales is invalid** (for example the chosen tariff is incorrect or expired), **none of the ticket sales will be registered**. You will instead get an error response with more details about the problem, and can then retry the registration without the incorrect ticket sales or ask the end user to change the tickets and/or tariffs that they want.\n\nThe caller of this request must have `TICKETSALES_REGISTER` permission for the organizer of the given event.\n", "security": [ { "USER_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] }, { "CLIENT_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TicketSale" } }, "examples": { "Example for one ticket sale": { "value": [ { "tariff": { "id": "COUPON1234" }, "uitpasNumber": "0560002524314", "eventId": "31e926e2-a35f-11eb-bcbc-0242ac130002", "regularPrice": 10, "regularPriceLabel": "Optional descriptive label of the regular price. Used in financial reporting." } ] }, "Example for multiple ticket sales": { "value": [ { "tariff": { "id": "COUPON1234" }, "uitpasNumber": "0560002524314", "eventId": "31e926e2-a35f-11eb-bcbc-0242ac130002", "regularPrice": 10, "regularPriceLabel": "Base tariff" }, { "tariff": { "id": "SOCIALTARIFF" }, "uitpasNumber": "0930002523422", "eventId": "31e926e2-a35f-11eb-bcbc-0242ac130002", "regularPrice": 10, "regularPriceLabel": "Base tariff" }, { "tariff": { "id": "REWARD21343" }, "uitpasNumber": "0985002524385", "eventId": "31e926e2-a35f-11eb-bcbc-0242ac130002", "regularPrice": 10 } ] }, "Example for multiple ticket sales at the same tariff": { "value": [ { "uitpasNumber": "0560002524314", "tariff": { "id": "SOCIALTARIFF" }, "eventId": "31e926e2-a35f-11eb-bcbc-0242ac130002", "regularPrice": 10, "regularPriceLabel": "Optional descriptive label of the regular price. Used in financial reporting." }, { "uitpasNumber": "0560002524314", "tariff": { "id": "SOCIALTARIFF" }, "eventId": "31e926e2-a35f-11eb-bcbc-0242ac130002", "regularPrice": 10, "regularPriceLabel": "Optional descriptive label of the regular price. Used in financial reporting." }, { "uitpasNumber": "0560002524314", "tariff": { "id": "SOCIALTARIFF" }, "eventId": "31e926e2-a35f-11eb-bcbc-0242ac130002", "regularPrice": 10, "regularPriceLabel": "Optional descriptive label of the regular price. Used in financial reporting." }, { "uitpasNumber": "0560002524314", "tariff": { "id": "SOCIALTARIFF" }, "eventId": "31e926e2-a35f-11eb-bcbc-0242ac130002", "regularPrice": 10, "regularPriceLabel": "Optional descriptive label of the regular price. Used in financial reporting." }, { "uitpasNumber": "0560002524314", "tariff": { "id": "SOCIALTARIFF" }, "eventId": "31e926e2-a35f-11eb-bcbc-0242ac130002", "regularPrice": 10, "regularPriceLabel": "Optional descriptive label of the regular price. Used in financial reporting." } ] }, "Example using a reward tariff": { "value": [ { "tariff": { "id": "REWARD1234" }, "uitpasNumber": "0560002524314", "eventId": "31e926e2-a35f-11eb-bcbc-0242ac130002", "regularPrice": 10 } ] } } } }, "description": "One or more new ticket sales to register." } }, "get": { "summary": "Retrieve existing ticket sales", "tags": [ "Ticket sales" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketSalesPaginatedResponse" }, "examples": { "Example without passholder (default)": { "value": { "totalItems": 2, "member": [ { "id": "21345", "creationDate": "2026-08-24T12:57:02Z", "tariff": { "id": "COUPON1234", "name": "Cultuurbon 6 euro", "price": 4, "type": "COUPON" }, "uitpasNumber": "0560002524314", "eventId": "31e926e2-a35f-11eb-bcbc-0242ac130002", "regularPrice": 10, "regularPriceLabel": "Optional descriptive label of the regular price. Used in financial reporting." }, { "id": "21346", "creationDate": "2026-08-24T13:45:59Z", "tariff": { "id": "COUPON1234", "name": "Cultuurbon 6 euro", "price": 1.5, "type": "COUPON" }, "uitpasNumber": "0560002524314", "eventId": "31e926e2-a35f-11eb-bcbc-0242ac130002", "regularPrice": 10, "regularPriceLabel": "Optional descriptive label of the regular price. Used in financial reporting." } ] } }, "Example with passholder (PASSHOLDERS_SEARCH permission required)": { "value": { "totalItems": 2, "member": [ { "id": "21345", "creationDate": "2026-08-24T12:57:02Z", "tariff": { "id": "COUPON1234", "name": "Cultuurbon 6 euro", "price": 4, "type": "COUPON" }, "uitpasNumber": "0560002524314", "eventId": "31e926e2-a35f-11eb-bcbc-0242ac130002", "regularPrice": 10, "regularPriceLabel": "Optional descriptive label of the regular price. Used in financial reporting.", "passholder": { "id": "1be0fb53-0695-405b-ac09-deafead650af", "name": "Peeters", "firstName": "Marc", "inszNumber": "00000009007", "dateOfBirth": "2000-01-01", "postalCode": "9300", "address": { "postalCode": "9300", "city": "Aalst" }, "creationDate": "2012-08-24T14:15:22+00:00", "registrationOrganizer": { "id": "1234", "name": "Example UiTPAS Organizer" }, "points": 10, "uitidStatus": "UNREGISTERED", "uitpasNumber": "0930012345615", "cardSystemMemberships": [ { "cardSystem": { "id": 12, "name": "UiTPAS Oostende", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "8400", "name": "Oostende" } ], "permanent": true }, "uitpasNumber": "0930012345615", "currentCard": { "uitpasNumber": "0930012345615", "status": "ACTIVE" }, "status": "ACTIVE", "socialTariff": { "status": "ACTIVE", "endDate": "2022-08-24T14:15:22+00:00", "inGracePeriod": false, "expired": false } } ] } }, { "id": "21346", "creationDate": "2026-08-21T12:12:02Z", "tariff": { "id": "COUPON1234", "name": "Cultuurbon 6 euro", "price": 1.5, "type": "COUPON" }, "uitpasNumber": "0560002524314", "eventId": "31e926e2-a35f-11eb-bcbc-0242ac130002", "regularPrice": 10, "regularPriceLabel": "Optional descriptive label of the regular price. Used in financial reporting.", "passholder": { "id": "1be0fb53-0695-405b-ac09-deafead650af", "name": "Peeters", "firstName": "Marc", "inszNumber": "00000009007", "dateOfBirth": "2000-01-01", "postalCode": "9300", "address": { "postalCode": "9300", "city": "Aalst" }, "creationDate": "2012-08-24T14:15:22+00:00", "registrationOrganizer": { "id": "1234", "name": "Example UiTPAS Organizer" }, "points": 10, "uitidStatus": "UNREGISTERED", "uitpasNumber": "0930012345615", "cardSystemMemberships": [ { "cardSystem": { "id": 12, "name": "UiTPAS Oostende", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "8400", "name": "Oostende" } ], "permanent": true }, "uitpasNumber": "0930012345615", "currentCard": { "uitpasNumber": "0930012345615", "status": "ACTIVE" }, "status": "ACTIVE", "socialTariff": { "status": "ACTIVE", "endDate": "2022-08-24T14:15:22+00:00", "inGracePeriod": false, "expired": false } } ] } } ] } } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/url/query-limit-exceeded\n\nThe detail property might include more information for the client developer.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "get-ticket-sales", "description": "Retrieve ticket sales based on search parameters. At least one of the following query paramaters is required: `eventId`, `passholderId`. If `passholderId` is specified, then also `organizerId` is required.\n\nThe caller of this request must have `TICKETSALES_SEARCH` permission for the organizer of the given event.\n\nThe `passholder` is included in the response if applicable (passholder can be empty in some cases, e.g. for group passes), and only if the caller of this request has PASSHOLDERS_SEARCH permission.", "security": [ { "USER_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] }, { "CLIENT_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] } ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "eventId", "description": "Filter ticket sales on this UiTdatabank event." }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" }, { "schema": { "type": "string" }, "in": "query", "name": "passholderId", "description": "Filter ticket sales on this passholder. Filtering on `organizerId` is required when using this filter." }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "organizerId", "description": "Filter ticket sales for events of this organizer, or events taking place on the location of this organizer.", "explode": true }, { "schema": { "type": "string" }, "in": "query", "name": "eventTitle", "description": "Filter ticket sales on this (partial) UiTdatabank event title." } ] } }, "/checkins": { "parameters": [], "post": { "summary": "Check in passholder", "operationId": "post-checkins", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checkin" }, "examples": { "Example with passholder": { "value": { "id": "7b2547d6-0110-4a3c-9498-84a373d4ee5a", "eventId": "31e926e2-a35f-11eb-bcbc-0242ac130002", "uitpasNumber": "0560002524314", "points": 1, "passholder": { "id": "8703fee0-29cc-452c-b1af-94ef494d4196", "name": "Peeters", "firstName": "Marc", "inszNumber": "00000009007", "dateOfBirth": "2000-01-01", "postalCode": "9300", "address": { "postalCode": "9300", "city": "Aalst" }, "creationDate": "2012-08-24T14:15:22+00:00", "registrationOrganizer": { "id": "1234", "name": "Example UiTPAS Organizer" }, "points": 10, "uitidStatus": "UNREGISTERED", "uitpasNumber": "0560002524314", "cardSystemMemberships": [ { "cardSystem": { "id": 1, "name": "UiTPAS Dender", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "9300", "name": "Aalst" }, { "postalCode": "9400", "name": "Ninove" } ], "permanent": true }, "uitpasNumber": "0560002524314", "currentCard": { "uitpasNumber": "0560002524314", "status": "ACTIVE" }, "status": "ACTIVE", "socialTariff": { "status": "ACTIVE", "endDate": "2022-08-24T14:15:22+00:00", "inGracePeriod": false, "expired": false } } ] } } }, "Example without passholder": { "value": { "id": "7b2547d6-0110-4a3c-9498-84a373d4ee5a", "eventId": "31e926e2-a35f-11eb-bcbc-0242ac130002", "uitpasNumber": "0560002524314", "points": 1 } } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data\n* https://api.publiq.be/probs/uitpas/checkin-not-allowed\n* https://api.publiq.be/probs/uitpas/event-not-found\n* https://api.publiq.be/probs/uitpas/passholder-not-found\n* https://api.publiq.be/probs/uitpas/invalid-uitpasnumber\n* https://api.publiq.be/probs/uitpas/invalid-card\n* https://api.publiq.be/probs/uitpas/invalid-card-status\n* https://api.publiq.be/probs/uitpas/passholder-no-active-cardsystems\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Social tariff discount expired": { "value": { "type": "https://api.publiq.be/probs/uitpas/social-tariff-discount-expired", "title": "Social tariff discount expired", "status": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "description": "Check in a passholder at a given event.\n\nYou will need:\n- The `uitpasNumber` of the passholder\n- The `eventId` of the UiTdatabank event.\n\n> Checking in a passholder is only possible during the opening hours of the event and a certain period before and after. A client will receive an error of type `https://api.publiq.be/probs/uitpas/checkin-not-allowed` when a check-in is not allowed. The `endUserMessage` field of that error response will also contain a user-readable error message.\n\nIf you need to check-in a passholder based on a check-in code (e.g. a QR code), use [POST /passholders/passholderId/checkins](/reference/uitpas.json/paths/~1passholders~1passholderId~1checkins/post) instead.\n\nThe caller of this request must have `CHECKINS_WRITE` permission for the organizer of the given event.\n", "security": [ { "USER_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] }, { "CLIENT_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checkin" }, "examples": { "Example": { "value": { "eventId": "CBA2D826-9E85-47BD-8E0B-2BC7882E68FB", "uitpasNumber": "0900000095902" } } } } }, "description": "Check-in request body" }, "tags": [ "Checkins" ] }, "get": { "summary": "Search check-ins", "operationId": "get-checkins", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckinsPaginatedCollection" }, "examples": { "Example": { "value": { "totalItems": 3, "member": [ { "id": "7b2547d6-0110-4a3c-9498-84a373d4ee5a", "creationDate": "2026-08-24T12:57:02Z", "eventId": "31e926e2-a35f-11eb-bcbc-0242ac130002", "uitpasNumber": "0560002524314", "points": 1, "passholder": { "id": "8703fee0-29cc-452c-b1af-94ef494d4196", "name": "Peeters", "firstName": "Marc", "inszNumber": "00000009007", "dateOfBirth": "2000-01-01", "postalCode": "9300", "address": { "postalCode": "9300", "city": "Aalst" }, "creationDate": "2012-08-24T14:15:22+00:00", "registrationOrganizer": { "id": "1234", "name": "Example UiTPAS Organizer" }, "points": 10, "uitidStatus": "UNREGISTERED", "uitpasNumber": "0560002524314", "cardSystemMemberships": [ { "cardSystem": { "id": 1, "name": "UiTPAS Dender", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "9300", "name": "Aalst" }, { "postalCode": "9400", "name": "Ninove" } ], "permanent": true }, "uitpasNumber": "0560002524314", "currentCard": { "uitpasNumber": "0560002524314", "status": "ACTIVE" }, "status": "ACTIVE", "socialTariff": { "status": "ACTIVE", "endDate": "2022-08-24T14:15:22+00:00", "inGracePeriod": false, "expired": false } } ] } }, { "id": "7b2547d6-0110-4a3c-9498-84a373d4ee5a", "creationDate": "2026-08-24T12:57:03Z", "eventId": "31e926e2-a35f-11eb-bcbc-0242ac130002", "uitpasNumber": "0560002524314", "points": 1, "passholder": { "id": "8703fee0-29cc-452c-b1af-94ef494d4196", "name": "Peeters", "firstName": "Marc", "inszNumber": "00000009007", "dateOfBirth": "2000-01-01", "postalCode": "9300", "address": { "postalCode": "9300", "city": "Aalst" }, "creationDate": "2012-08-24T14:15:22+00:00", "registrationOrganizer": { "id": "1234", "name": "Example UiTPAS Organizer" }, "points": 10, "uitidStatus": "UNREGISTERED", "uitpasNumber": "0560002524314", "cardSystemMemberships": [ { "cardSystem": { "id": 1, "name": "UiTPAS Dender", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "9300", "name": "Aalst" }, { "postalCode": "9400", "name": "Ninove" } ], "permanent": true }, "uitpasNumber": "0560002524314", "currentCard": { "uitpasNumber": "0560002524314", "status": "ACTIVE" }, "status": "ACTIVE", "socialTariff": { "status": "ACTIVE", "endDate": "2022-08-24T14:15:22+00:00", "inGracePeriod": false, "expired": false } } ] } }, { "id": "7b2547d6-0110-4a3c-9498-84a373d4ee5a", "creationDate": "2026-08-24T12:57:04Z", "eventId": "31e926e2-a35f-11eb-bcbc-0242ac130002", "uitpasNumber": "0560002524314", "points": 1, "passholder": { "id": "8703fee0-29cc-452c-b1af-94ef494d4196", "name": "Peeters", "firstName": "Marc", "inszNumber": "00000009007", "dateOfBirth": "2000-01-01", "postalCode": "9300", "address": { "postalCode": "9300", "city": "Aalst" }, "creationDate": "2012-08-24T14:15:22+00:00", "registrationOrganizer": { "id": "1234", "name": "Example UiTPAS Organizer" }, "points": 10, "uitidStatus": "UNREGISTERED", "uitpasNumber": "0560002524314", "cardSystemMemberships": [ { "cardSystem": { "id": 1, "name": "UiTPAS Dender", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "9300", "name": "Aalst" }, { "postalCode": "9400", "name": "Ninove" } ], "permanent": true }, "uitpasNumber": "0560002524314", "currentCard": { "uitpasNumber": "0560002524314", "status": "ACTIVE" }, "status": "ACTIVE", "socialTariff": { "status": "ACTIVE", "endDate": "2022-08-24T14:15:22+00:00", "inGracePeriod": false, "expired": false } } ] } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "description": "Retrieve check-ins based on search parameters.\n\nThe order of check-ins is always newest first.\n\nThe `passholder` property is never included in the response.\n\nThe caller of this method must have `CHECKINS_READ` permission.", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "passholderId", "description": "Filter on check-ins of this passholder", "required": true }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "organizerId", "description": "ID of the organizer of the event of the check-in.", "required": true, "explode": true }, { "schema": { "type": "string" }, "in": "query", "name": "eventTitle", "description": "Filter checkins on this (partial) UiTdatabank event title." } ], "tags": [ "Checkins" ] } }, "/checkins/{checkinId}": { "parameters": [ { "schema": { "type": "string" }, "name": "checkinId", "in": "path", "required": true, "description": "Id of the checkin" } ], "delete": { "summary": "Delete a check-in", "operationId": "delete-checkins-checkinId", "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Checkins" ], "description": "Delete a checkin.\n\nThe caller of this request must have `CHECKINS_WRITE` permission for the organizer of the given event.\n", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ] } }, "/checkin-status": { "parameters": [], "get": { "summary": "Get checkin status", "operationId": "get-checkin-status", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckinStatus" }, "examples": { "Example allowed": { "value": { "allowed": true } }, "Example not allowed": { "value": { "allowed": false, "endUserMessage": { "nl": "Deze activiteit is afgelopen, je kan op deze activiteit geen punt meer sparen." } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found\n\nPossible error types:\n\n* https://api.publiq.be/probs/uitpas/event-not-found\n* https://api.publiq.be/probs/uitpas/passholder-not-found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Retrieves the current checkin status for a passholder and a given event.\n\nThe caller of this request must have `CHECKINS_WRITE` permission for the organizer of the given event.", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "uitpasNumber", "required": true, "description": "UiTPAS number of the passholder who wants to checkin" }, { "schema": { "type": "string" }, "in": "query", "name": "eventId", "required": true, "description": "Id of the event where the passholder wants to checkin" } ], "tags": [ "Checkins" ] } }, "/ticket-sales/{ticketSaleId}": { "parameters": [ { "schema": { "type": "string" }, "name": "ticketSaleId", "in": "path", "required": true, "description": "Id of the previously registered ticket sale" } ], "delete": { "summary": "Cancel a ticket sale registration", "operationId": "delete-ticket-sales", "responses": { "204": { "description": "No content. The ticket sale was successfully canceled." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Ticket Sale not found": { "value": { "type": "https://api.publiq.be/probs/uitpas/ticket-sale-not-found", "title": "Ticket sale not found", "status": 404 } } } } } } }, "description": "Cancels a single ticket sale registration by its id. (Returned in the response of the ticket sale registration request.)\n\nThe caller of this request must have `TICKETSALES_REGISTER` permission for the organizer of the event of the ticketsale.", "tags": [ "Ticket sales" ], "security": [ { "USER_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] }, { "CLIENT_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] } ] } }, "/permissions": { "get": { "summary": "Get permissions", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizerPermissions" } }, "examples": { "Example with multiple organizers": { "value": [ { "organizer": { "id": "c097fa2e-d9be-42e6-b41a-ec3d4d4cbad1", "name": "CC De Werf" }, "permissions": [ "TARIFFS_READ", "TICKETSALES_SEARCH" ], "permissionDetails": [ { "id": "TARIFFS_READ", "label": { "nl": "Tarieven opvragen" }, "cardSystemIds": [ 1 ] }, { "id": "TICKETSALES_SEARCH", "label": { "nl": "Ticketsales zoeken" }, "cardSystemIds": [ 1 ] } ], "linkedOrganizers": [ { "organizer": { "id": "347e6177-4add-4fa8-a7fe-6e60127bfb12", "name": "Sportdienst" }, "permissionDetails": [ { "id": "CHECKINS_WRITE", "label": { "nl": "Punten sparen" }, "cardSystemIds": [ 1 ] } ] } ] }, { "organizer": { "id": "fd7e6177-4add-4fa8-a7fe-6e60127bfb35", "name": "CC De Schakel" }, "permissions": [ "ORGANIZERS_SEARCH" ], "permissionDetails": [ { "id": "ORGANIZERS_SEARCH", "label": { "nl": "Organisators zoeken" }, "cardSystemIds": [ 1 ] } ] } ] }, "Example with one organizer": { "value": [ { "organizer": { "id": "c097fa2e-d9be-42e6-b41a-ec3d4d4cbad1", "name": "CC De Werf" }, "permissions": [ "TARIFFS_READ", "TICKETSALES_SEARCH" ], "permissionDetails": [ { "id": "TARIFFS_READ", "label": { "nl": "Tarieven opvragen" }, "cardSystemIds": [ 1 ] }, { "id": "TICKETSALES_SEARCH", "label": { "nl": "Ticketsales zoeken" }, "cardSystemIds": [ 1 ] } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "get-permissions", "description": "Lists the organizers that the current user or client (depending on the token) has access to including a list of its permissions.\n\nThe OrganizerPermission response object can also contain `linkedOrganizers` for which admins of this organizer also have access to.\n\nUse this endpoint if you obtained a user or client access token and need to know its organizer permissions. Use [GET /permissions/clientID](/reference/uitpas.json/paths/~1permissions~1clientId/get) to manage permissions for any client.", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "tags": [ "Permissions" ] }, "parameters": [] }, "/events/{eventId}/card-systems": { "parameters": [ { "schema": { "type": "string" }, "name": "eventId", "in": "path", "required": true, "description": "The id of the event" } ], "put": { "summary": "Update event card systems", "operationId": "put-events-card-systems", "responses": { "204": { "description": "EventCardSytems updated. No content." }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data\n* https://api.publiq.be/probs/uitpas/invalid-card-system\n* https://api.publiq.be/probs/uitpas/cardsystem-not-found\n* https://api.publiq.be/probs/uitpas/distributionkey-not-found\n* https://api.publiq.be/probs/uitpas/invalid-distributionkey\n* https://api.publiq.be/probs/uitpas/event-already-has-ticketsales\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/event-not-found\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "description": "List of all possible (enabled and disabled) EventCardSystem objects", "type": "array", "items": { "$ref": "#/components/schemas/EventCardSystem" } }, "examples": { "Example": { "value": [ { "id": 1, "enabled": true, "manualDistributionKeys": [ { "id": 123, "enabled": true } ] }, { "id": 8, "enabled": false } ] } } } }, "description": "New list of card systems that an event is related to. Will overwrite the old list." }, "description": "Update the `EventCardSystem` objects of the given event.\n\nThe `EventCardSystem` object specifies that the event is available in\nthis specific card system and optionally what manual distribution keys are enabled.\n\nThis update is used to toggle the `enabled` state for specific card systems or distribution keys.\n\nTo update the `enabled` state for card systems or distribution keys, you typically retrieve the possible `EventCardSystem` objects first using `GET /events/{eventId}/card-systems`. You can then reuse the response from the `GET` request, \naltering the `enabled` state. Note that you can also omit the name properties. \nOnly the required fields are used in this update request.\n\nHowever, in case you know the card system(s) and distribution key(s) in advance, you might also make this `PUT` request without prior `GET` e.g. in case you need to disable all card systems for an event, you can simply put an empty array `[]` to indicate that (missing card systems in the array will be treated the same way as card systems with `enabled: \"false\"`).\nAlso note the implementation of this `PUT` endpoint is robust enough to allow updating card systems before the event is known in UiTPAS. (so even before the `GET` returns a valid HTTP 200 response).\n\n\n\n\n> **This endpoint is only needed for exceptional cases.** In most cases card systems and distribution keys are set automatically on events, so you don't need to retrieve or change them.\n\nThe caller of this request must have `EVENTS_UPDATE` permission for the organizer of this event or the caller of this request must have \"Aanbod bewerken\" permission in the UiTdatabank for the given event.\n", "security": [ { "USER_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] }, { "CLIENT_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] } ], "tags": [ "Events" ] }, "get": { "summary": "Get event card systems", "operationId": "get-events-card-systems", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EventCardSystem" } }, "examples": { "Example": { "value": [ { "id": 1, "name": "UiTPAS Dender", "enabled": true, "manualDistributionKeys": [ { "id": 123, "name": "3 euro per dag", "enabled": true } ] }, { "id": 8, "name": "UiTPAS Gent", "enabled": true } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/event-not-found\n\nThe detail property might include more information for the client developer.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Retrieve social tariff settings specific for this card system and the given postal code.\n\nThis caller of this method, identified by client identification, client access token or user access token, does not require any permissions.", "security": [ { "USER_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] }, { "CLIENT_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] } ], "tags": [ "Events" ] } }, "/permissions/{clientId}": { "get": { "summary": "Get permissions for a client", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizerPermissions" } }, "examples": { "Example": { "value": [ { "organizer": { "id": "c097fa2e-d9be-42e6-b41a-ec3d4d4cbad1", "name": "CC De Werf" }, "permissionDetails": [ { "id": "TARIFFS_READ", "label": { "nl": "Tarieven opvragen" }, "cardSystemIds": [ 1 ] }, { "id": "TICKETSALES_SEARCH", "label": { "nl": "Ticketsales zoeken" }, "cardSystemIds": [ 1 ] } ] }, { "organizer": { "id": "fd7e6177-4add-4fa8-a7fe-6e60127bfb35", "name": "CC De Schakel" }, "permissionDetails": [ { "id": "ORGANIZERS_SEARCH", "label": { "nl": "Organisators zoeken" }, "cardSystemIds": [ 1 ] } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not found. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/client-not-found\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get-permissions-clientId", "description": "Lists the organizer permissions of the given client ID.\n\nUse this endpoint to manage permissions for any client. Use [GET /permissions](/reference/uitpas.json/paths/~1permissions/get) to retrieve permissions for your token (current client or user).\n\nThe caller of this request must have `PERMISSIONS_READ` permission.\n", "security": [ { "CLIENT_ACCESS_TOKEN": [] } ], "tags": [ "Permissions" ] }, "parameters": [ { "schema": { "type": "string" }, "name": "clientId", "in": "path", "required": true, "description": "ID of the client" } ], "put": { "summary": "Update permissions for a client", "operationId": "put-permissions-clientId", "responses": { "204": { "description": "Permissions Updated. No Content" }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not found. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/client-not-found\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Update the organizer permissions of the given client ID.\n\nThe caller of this request must have `PERMISSIONS_WRITE` permission.", "security": [ { "CLIENT_ACCESS_TOKEN": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizerPermissions" } }, "examples": { "Example": { "value": [ { "organizer": { "id": "c097fa2e-d9be-42e6-b41a-ec3d4d4cbad1" }, "permissionDetails": [ { "id": "TARIFFS_READ" }, { "id": "TICKETSALES_SEARCH" } ] }, { "organizer": { "id": "fd7e6177-4add-4fa8-a7fe-6e60127bfb35" }, "permissionDetails": [ { "id": "ORGANIZERS_SEARCH" } ] } ] } } } }, "description": "Full set of organizer permissions for the client" }, "tags": [ "Permissions" ] } }, "/events/{eventId}/settings": { "parameters": [ { "schema": { "type": "string" }, "name": "eventId", "in": "path", "required": true, "description": "The id of the event" } ], "put": { "summary": "Update event settings", "operationId": "put-events-settings", "responses": { "204": { "description": "EventCardSytems updated. No content." }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/event-not-found\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventSettings" }, "examples": { "Example": { "value": { "checkinPoints": 1, "id": "188dbbde-5ab1-497a-9083-8e56b5a33a1b", "passholderTicketLimit": { "volume": 1, "periodType": "ABSOLUTE" }, "checkinLimit": { "volume": 1, "periodType": "WEEK" } } } } } }, "description": "Complete settings object of the given event. " }, "description": "Update the event settings of the given event.\n\nMake sure to perform a `GET events/{eventId}/settings` first, apply your changes and PUT the complete object using this request.\n\nThe caller of this request must have `EVENT_SETTINGS_UPDATE` permission for the organizer of this event.\n", "security": [ { "USER_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] }, { "CLIENT_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] } ], "tags": [ "Events" ] }, "get": { "summary": "Get event settings", "operationId": "get-events-settings", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventSettings" }, "examples": { "Example with both limits": { "value": { "id": "188dbbde-5ab1-497a-9083-8e56b5a33a1b", "checkinPoints": 1, "passholderTicketLimit": { "volume": 1, "periodType": "ABSOLUTE" }, "checkinLimit": { "volume": 1, "periodType": "WEEK" } } }, "Example without limits": { "value": { "id": "188dbbde-5ab1-497a-9083-8e56b5a33a1b", "checkinPoints": 1 } }, "Example with checkin limits": { "value": { "id": "188dbbde-5ab1-497a-9083-8e56b5a33a1b", "checkinPoints": 1, "checkinLimit": { "volume": 1, "periodType": "MONTH" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/event-not-found\n\nThe detail property might include more information for the client developer.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Get event settings of the given event.\n\nThe caller of this request must have `EVENT_SETTINGS_READ` permission for the organizer of this event.\n", "security": [ { "USER_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] }, { "CLIENT_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] } ], "tags": [ "Events" ] } }, "/events/{eventId}/qr-checkincodes/download-link": { "parameters": [ { "schema": { "type": "string" }, "name": "eventId", "in": "path", "required": true, "description": "The id of the event" } ], "get": { "summary": "Get event QR checkin code as download link", "operationId": "get-events-qr-checkincodes-downloadlink", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadLinkResponse" }, "examples": { "Example": { "value": { "downloadLink": "https://api-test.uitpas.be/some/path/to/qr.zip?ts=202310231357&hash=1b5413636b41e9f774d416358060e613398b3ab017da13f3815c771a988b2d84" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/event-not-found\n\nThe detail property might include more information for the client developer.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Get a temporary download link to the QR checkin code of the given event.\n\nThis endpoint allows you to obtain a short-lived, hassle-free download link for your QR checkin code. After generation, this link remains active for a limited time, enabling direct QR downloads without the need for additional authentication. This is in particular convenient for applications that need to offer this link to users to start the download.\n \nThe caller of this request must have `EVENTS_QR_CHECKINCODE` permission for the organizer of this event.\n", "security": [ { "USER_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] }, { "CLIENT_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] } ], "tags": [ "Events" ], "parameters": [ { "schema": { "type": "string", "enum": [ "pdf", "zip" ], "default": "pdf" }, "in": "query", "name": "format", "description": "format of the result file." } ] } }, "/organizers": { "get": { "summary": "Get organizers", "tags": [ "Organizers" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizersPaginatedResponse" }, "examples": {} } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/group-not-found\n* https://api.publiq.be/probs/uitpas/cardsystem-not-found\n* https://api.publiq.be/probs/url/query-limit-exceeded\n\nThe detail property might include more information for the client developer.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "get-organizers", "description": "Retrieve organizers based on search parameters.\n\nThe caller of this request must have `ORGANIZERS_SEARCH` permission for the given organizer.", "security": [ { "USER_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] }, { "CLIENT_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] } ], "parameters": [ { "schema": { "type": "integer" }, "in": "query", "name": "groupId", "description": "Include only organizers in this group" }, { "schema": { "type": "string" }, "in": "query", "name": "name", "description": "Include only organizers with this name (* wildcard allowed)" }, { "schema": { "type": "integer" }, "in": "query", "name": "cardSystemId", "description": "Include only organizers linked to this card system" }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "sort[name]", "description": "Sorts the organizers by their name in ascending or descending order." } ] } }, "/organizers/{organizerId}/admins": { "get": { "summary": "Retrieve admin users for organizer", "tags": [ "Organizers" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizerAdminsPaginatedCollection" }, "examples": { "Example": { "value": { "totalItems": 1, "member": [ { "userId": "d50e6c3c-8aff-430a-86ce-b125fdc3b998", "email": "admin1@example.com", "type": "ADMIN" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get-organizers-organizerId-admins", "description": "Retrieve all admin users of the given organizer.\n\nThe caller of this request must have `ORGANIZERS_ADMINS_READ` permission for the given organizer or the caller must be an organizer admin user (any type) of the given organizer.", "security": [ { "USER_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] }, { "CLIENT_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] } ], "parameters": [ { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" } ] }, "parameters": [ { "schema": { "type": "string" }, "name": "organizerId", "in": "path", "required": true, "description": "The ID of the organizer." } ], "post": { "summary": "Add admin user for organizer", "operationId": "post-organizers-organizerId-admins", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizerAdmin" }, "examples": { "Example": { "value": { "id": "9306c939-04c9-4585-ad71-000fa01ded6f", "userId": "d50e6c3c-8aff-430a-86ce-b125fdc3b998", "email": "newadmin@example.com", "type": "ADMIN" } } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": {} }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": {} } }, "tags": [ "Organizers" ], "description": "Add a new admin user for the given organizer.\n\nThe caller of this request must have `ORGANIZERS_ADMINS_WRITE` permission for the given organizer or the caller must be an organizer admin user of type `ADMIN` of the given organizer.", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizerAdmin" }, "examples": { "Example": { "value": { "email": "newadmin@example.com", "type": "ADMIN" } } } } }, "description": "Request body with the email of the new organizer admin." } } }, "/organizers/{organizerId}/admins/{adminUserId}": { "parameters": [ { "schema": { "type": "string" }, "name": "organizerId", "in": "path", "required": true, "description": "The ID of the organizer." }, { "schema": { "type": "string" }, "name": "adminUserId", "in": "path", "required": true, "description": "The ID of the organizer admin user." } ], "delete": { "summary": "Remove admin user from organizer", "operationId": "delete-organizers-organizerId-admins-adminId", "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "headers": {}, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Organizers" ], "description": "Remove an existing admin user from the given organizer.\n\nThe caller of this request must have `ORGANIZERS_ADMINS_WRITE` permission for the given organizer or the caller must be an organizer admin user of type `ADMIN` of the given organizer.", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ] } }, "/associations": { "get": { "summary": "Get associations", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssociationsPaginatedResponse" }, "examples": { "Example": { "value": { "totalItems": 1, "member": [ { "id": "e8386a24-2218-4269-8b65-4de46be07991", "name": "Ledenkaart sport" } ] } } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/url/query-limit-exceeded\n\nThe detail property might include more information for the client developer.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "get-associations", "description": "Retrieve associations based on organizer and its permission on the specific association.\n\nPassholders can have memberships for zero or more associations. However, only selected organizers can see (read permission) or register (write permission) these memberships. Using this endpoint, clients can retrieve which memberships they can [see](/reference/uitpas.json/paths/~1passholders~1passholderId~1association-memberships/get) or register.\n\nThe caller of this request must have `ASSOCIATIONS` permission for the given organizer.", "security": [ { "USER_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] }, { "CLIENT_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] } ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "organizerId", "description": "ID of the organizer", "required": true }, { "schema": { "type": "string", "enum": [ "READ", "WRITE" ] }, "in": "query", "name": "permission", "required": true, "description": "Type of association permission" } ], "tags": [ "Associations" ] }, "parameters": [] }, "/passholders": { "get": { "summary": "Search passholders", "tags": [ "Passholders" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassholdersPaginatedResponse" }, "examples": { "Example": { "value": { "totalItems": 1, "member": [ { "id": "1be0fb53-0695-405b-ac09-deafead650af", "name": "Peeters", "firstName": "Marc", "inszNumber": "00000009007", "dateOfBirth": "2000-01-01", "postalCode": "9300", "address": { "postalCode": "9300", "city": "Aalst" }, "creationDate": "2012-08-24T14:15:22+00:00", "registrationOrganizer": { "id": "1234", "name": "Example UiTPAS Organizer" }, "points": 10, "uitidStatus": "UNREGISTERED", "uitpasNumber": "0930012345615", "cardSystemMemberships": [ { "cardSystem": { "id": 12, "name": "UiTPAS Oostende", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "8400", "name": "Oostende" } ], "permanent": true }, "uitpasNumber": "0930012345615", "currentCard": { "uitpasNumber": "0930012345615", "status": "ACTIVE" }, "status": "ACTIVE", "socialTariff": { "status": "ACTIVE", "endDate": "2022-08-24T14:15:22+00:00", "inGracePeriod": false, "expired": false } } ] } ] } } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/organizer-not-found\n* https://api.publiq.be/probs/uitpas/invalid-uitpas-number\n* https://api.publiq.be/probs/uitpas/invalid-insz-number\n* https://api.publiq.be/probs/uitpas/school-not-found\n* https://api.publiq.be/probs/url/query-limit-exceeded\n* https://api.publiq.be/probs/uitpas/association-not-found\n\nThe detail property might include more information for the client developer.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "get-passholders", "description": "Retrieve passholders based on search parameters.\n\nNote: by default passholders in the response are alphabetically sorted by name.\n\nThe caller of this request must have `PASSHOLDERS_SEARCH` or `PASSHOLDERS_SEARCH_BY_ID` or `PASSHOLDERS_SEARCH_ALL` permission. \n\nIn case of `PASSHOLDERS_SEARCH` permission, passholder results are filtered based on the allowed card systems of the caller, unless searched by one of the ID fields:\n* `uitpasNumber`\n* `chipNumber`\n* `inszNumber`\n* `uitidId`\n\nIn case of `PASSHOLDERS_SEARCH_BY_ID` permission, the caller can only make use of those ID fields.", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "inszNumber", "description": "Unique national (Belgian) INSZ number of an individual passholder to look up." }, { "schema": { "type": "string" }, "in": "query", "name": "uitpasNumber", "description": "Unique UiTPAS number of an individual passholder to look up." }, { "schema": { "type": "string" }, "in": "query", "name": "chipNumber", "description": "Hexadecimal notation of the chip number of an individual UiTPAS card." }, { "schema": { "type": "string" }, "in": "query", "name": "name", "description": "Complete or partial last name of a passholder to look up." }, { "schema": { "type": "string" }, "in": "query", "name": "firstName", "description": "Complete or partial first name of a passholder to look up." }, { "schema": { "type": "string" }, "in": "query", "name": "email", "description": "Email of a passholder to look up. Wildcards * allowed." }, { "schema": { "type": "string" }, "in": "query", "name": "address.street", "description": "Street address of a passholder to look up. Wildcards * allowed." }, { "schema": { "type": "string" }, "in": "query", "name": "address.city", "description": "City of a passholder to look up. Wildcards * allowed." }, { "schema": { "type": "string" }, "in": "query", "name": "schoolId", "description": "Organizer ID of a school, to only return passholders linked to a specific school. Use `*` to return passholders that are linked to any school. Note: Only used in very specific cases for educational integrations." }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "sort[name]", "description": "Sorts the passholders by their last name in ascending or descending order. By default passholders are sorted by name, ascending order." }, { "schema": { "type": "string" }, "in": "query", "name": "organizerId", "description": "A specific organizer ID to only return passholders that are linked to a card system related to this organizer. If omitted, the results will return passholders linked to the organizers you have permission to access." }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "dateOfBirthFrom", "description": "Returns only passholders with a date of birth of this value (including) or more recent. Format `yyyy-mm-dd`, e.g. `2003-01-01`" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "dateOfBirthTo", "description": "Returns only passholders with a date of birth of this value (including) or older. Format `yyyy-mm-dd`, e.g. `2003-01-01`" }, { "schema": { "type": "string" }, "in": "query", "name": "uitidId", "description": "Unique ID of the UiTiD user linked to an individual passholder to look up." }, { "schema": { "type": "string" }, "in": "query", "name": "associationId", "description": "Filters results to passholders with a membership in the specified association. Defaults to active memberships only; use associationMembershipStatus to change this behavior. Requires association READ permission on the specified association for the provided organizerId (or for any of the caller's organizer IDs if omitted)" }, { "schema": { "type": "string", "enum": [ "ACTIVE", "EXPIRED", "ALL" ] }, "in": "query", "name": "associationMembershipStatus", "description": "Filters passholders by their association membership status. Requires associationId to be specified. Defaults to ACTIVE." } ] }, "parameters": [], "post": { "summary": "Register a new passholder", "operationId": "post-passholders", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Passholder" }, "examples": { "Example": { "value": { "id": "1be0fb53-0695-405b-ac09-deafead650afx", "name": "Peeters", "firstName": "Marc", "inszNumber": "00000009007", "dateOfBirth": "2000-01-01", "postalCode": "9300", "address": { "postalCode": "9300", "city": "Aalst" }, "creationDate": "2012-08-24T14:15:22+00:00", "registrationOrganizer": { "id": "1234", "name": "Example UiTPAS Organizer" }, "points": 10, "uitidStatus": "UNREGISTERED", "uitpasNumber": "0930012345615", "cardSystemMemberships": [ { "cardSystem": { "id": 12, "name": "UiTPAS Oostende", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "8400", "name": "Oostende" } ], "permanent": true }, "uitpasNumber": "0930012345615", "currentCard": { "uitpasNumber": "0930012345615", "status": "ACTIVE" }, "status": "ACTIVE", "socialTariff": { "status": "ACTIVE", "endDate": "2022-08-24T14:15:22+00:00", "inGracePeriod": false, "expired": false } } ] } } } } } }, "400": { "description": "Bad request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data\n* https://api.publiq.be/probs/uitpas/organizer-not-found\n* https://api.publiq.be/probs/uitpas/cardsystem-not-found\n* https://api.publiq.be/probs/uitpas/invalid-city\n* https://api.publiq.be/probs/uitpas/invalid-insz-number\n* https://api.publiq.be/probs/uitpas/invalid-uitpas-number\n* https://api.publiq.be/probs/uitpas/invalid-card\n* https://api.publiq.be/probs/uitpas/invalid-card-status\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Register a passholder\n\n\n\n> IMPORTANT\n>\n> Make sure to set `registrationCardType` to either `DIGITAL` or `NFC_CARD`. In case of `NFC_CARD` the field `registrationUitpasNumber` is required and has to be a card in status `LOCAL_STOCK`.\n\nThe caller must have the `PASSHOLDERS_WRITE` permission for the `registrationOrganizer`. Registering a passholder with a social tariff additionally requires `PASSHOLDERS_WRITE_SOCIAL_TARIFF`, and doing so in a city other than the `registrationOrganizer` additionally requires `PASSHOLDERS_WRITE_SOCIALTARIFF_FULL_CARDSYSTEM`. These permissions are cumulative.\n\n`PASSHOLDERS_WRITE_FOREIGN_COUNTRY` permission is needed when registering any passholder with a country other than `be`.", "security": [ { "CLIENT_ACCESS_TOKEN": [] }, { "USER_ACCESS_TOKEN": [] } ], "requestBody": { "description": "Details of the new passholder to register.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Passholder" }, "examples": { "Example": { "value": { "name": "Peeters", "firstName": "Marc", "inszNumber": "00000009007", "email": "marc.peeters@example.com", "dateOfBirth": "2000-01-01", "registrationOrganizer": { "id": "abc12345" }, "address": { "street": "Grote markt 12", "postalCode": "9300", "city": "Aalst", "country": "be" }, "optInPreferences": { "serviceMails": true, "infoMails": true, "milestoneMails": true, "sms": false, "post": true }, "nationality": "Belg", "legalTermsPaper": false, "legalTermsDigital": true, "parentalConsent": false, "registrationCardSystemId": 1, "registrationCardType": "DIGITAL" } } } } } }, "tags": [ "Passholders" ] } }, "/grouppasses": { "get": { "summary": "Search grouppasses", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrouppassesPaginatedResponse" }, "examples": { "Example": { "value": { "totalItems": 1, "member": [ { "id": "b5a5bb75-6cae-452b-b029-d12d3b425b1b", "name": "Test groep", "uitpasNumber": "0900000045410", "cardStatus": "ACTIVE", "email": "testgrouppass@example.com", "creationDate": "2019-08-24T14:15:22+00:00", "socialTariff": { "status": "ACTIVE", "endDate": "2024-12-31T01:00:00+00:00", "totalTicketsPerYear": 20, "availableTickets": 9 }, "cardSystem": { "id": 1, "name": "UiTPAS Dender", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "9300", "name": "Aalst" }, { "postalCode": "9400", "name": "Ninove" } ], "permanent": true }, "address": { "postalCode": "9300", "city": "Aalst", "country": "be" }, "telephone": "012/456789" } ] } } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/invalid-uitpas-number\n* https://api.publiq.be/probs/url/query-limit-exceeded\n\nThe detail property might include more information for the client developer.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "get-grouppasses", "description": "Retrieve grouppasses based on search parameters.\n\n**Note**: For now this endpoint requires either `uitpasNumber` or `chipNumber`, so this endpoint currently cannot be used to search _all_ grouppasses.\n\n\n\n> **Important:** This endpoint might return `grouppass` entities for `BLOCKED` or `DELETED` cards. Clients using this endpoint MUST check `cardStatus` for `ACTIVE` cards before proceeding regular operations with this `grouppass`.\n\nThe caller of this request must have `EVENTS_READ` permission for the organizer of this event.\n\nThe caller of this request must have `GROUPPASSES_SEARCH` permission.", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "uitpasNumber", "description": "Unique UiTPAS number of the grouppass to look up. Required unless `chipNumber` is used." }, { "schema": { "type": "string" }, "in": "query", "name": "chipNumber", "description": "Hexadecimal notation of the chip number of a grouppass UiTPAS card. Required unless`uitpasNumber` is used." }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "sort[name]", "description": "Sorts the grouppasses by ti name in ascending or descending order. By default passholders are sorted by name, ascending order." } ], "tags": [ "Grouppasses" ] }, "parameters": [] }, "/grouppasses/{passholderId}": { "get": { "summary": "Retrieve grouppass by ID", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Grouppass" }, "examples": { "Example": { "value": { "id": "b5a5bb75-6cae-452b-b029-d12d3b425b1b", "name": "Test groep", "uitpasNumber": "0900000045410", "cardStatus": "ACTIVE", "email": "testgrouppass@example.com", "creationDate": "2019-08-24T14:15:22+00:00", "socialTariff": { "status": "ACTIVE", "endDate": "2024-12-31T01:00:00+00:00", "totalTicketsPerYear": 20, "availableTickets": 9 }, "cardSystem": { "id": 1, "name": "UiTPAS Dender", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "9300", "name": "Aalst" }, { "postalCode": "9400", "name": "Ninove" } ], "permanent": true }, "address": { "postalCode": "9300", "city": "Aalst", "country": "be" }, "telephone": "012/456789" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get-grouppasses-passholderId", "description": "Retrieve a grouppass by ID.\n\nThe caller of this request must have `GROUPPASSES_SEARCH` permission.\n", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "parameters": [], "tags": [ "Grouppasses" ] }, "parameters": [ { "schema": { "type": "string" }, "name": "passholderId", "in": "path", "required": true, "description": "ID of the Grouppass" } ] }, "/grouppasses/{passholderId}/coupons": { "parameters": [ { "schema": { "type": "string" }, "name": "passholderId", "in": "path", "description": "Unique ID of an grouppass.", "required": true } ], "get": { "summary": "Get coupons of grouppass", "operationId": "get-grouppasses-passholderId-coupons", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GrantedCoupon" } }, "examples": { "Example": { "value": [ { "id": 21343, "coupon": { "id": "COUPON_13", "name": "Gratis naar de film in groep", "description": "Gratis naar de film omschrijving" }, "validityPeriod": { "begin": "2026-01-31T23:00:00+00:00", "end": "2026-06-30T22:00:00+00:00" }, "status": "ACTIVE", "remaining": { "volume": 100, "period": "ABSOLUTE" } } ] } } } } }, "400": { "description": "Bad request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/passholder-no-active-cardsystems\n* https://api.publiq.be/probs/uitpas/organizer-not-found\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Retrieve coupons of given grouppass.\n\nThe caller of this method must have `GROUPPASS_COUPONS_READ` permission.", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "tags": [ "Grouppasses" ], "parameters": [ { "schema": { "type": "string", "enum": [ "ACTIVE", "EXPIRED", "ALL" ], "default": "ACTIVE" }, "in": "query", "name": "status", "description": "Status of the granted coupon" }, { "schema": { "type": "string" }, "in": "query", "name": "organizerId", "description": "Filter coupons that are applicable in card systems of this organizer" } ] } }, "/passholders/{passholderId}": { "parameters": [ { "$ref": "#/components/parameters/passholderId" } ], "get": { "summary": "Retrieve passholder by ID", "operationId": "get-passholders-passholderId", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Passholder" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Retrieve a passholder by ID.\n\nThe caller of this request must have `PASSHOLDERS_SEARCH` or `PASSHOLDERS_SEARCH_BY_ID` or `PASSHOLDERS_SEARCH_ALL` permission.", "tags": [ "Passholders" ], "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ] }, "delete": { "summary": "Remove passholder", "operationId": "delete-passholders-passholderId", "tags": [ "Passholders" ], "description": "Remove this passholder.\n\nThe caller of this request must have `PASSHOLDERS_DELETE` permission.", "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ] }, "put": { "summary": "Update a passholder", "operationId": "put-passholders-passholderId", "responses": { "204": { "description": "Passholder updated. No Content" }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Passholders" ], "description": "Update a passholder.\n\nOnly specific fields can be modified; please refer to the individual field descriptions to identify which fields are ignored during an update.\n\nPlease note that this is a PUT endpoint, which performs a full replacement of the resource. You must include the complete resource payload in the request body, including all unchanged fields. Omitting optional fields may clear their existing values or cause validation errors.\n\n\n\n> The following additional rules apply:\n> * Social Tariff Permissions: Updating the `registrationSocialTariffEndDate` field requires the additional `PASSHOLDERS_WRITE_SOCIAL_TARIFF` permission.\n> * Regional Restrictions: If the passholder has a valid social tariff, the `postalCode` and `city` cannot be changed to a location outside the region of the current card system.\n> * Updating a passholder to a city outside Belgium requires the additional `PASSHOLDERS_WRITE_FOREIGN_COUNTRY` permission.\n\nThe caller of this request must have `PASSHOLDERS_WRITE` permission.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Passholder" }, "examples": { "Example 1": { "value": { "name": "Peeters", "firstName": "Marc", "inszNumber": "00000009007", "email": "marc.peeters@example.com", "dateOfBirth": "2000-01-01", "address": { "street": "Grote markt 12", "postalCode": "9300", "city": "Aalst" }, "optInPreferences": { "serviceMails": true, "infoMails": true, "milestoneMails": true, "sms": false, "post": true }, "nationality": "Belg", "legalTermsPaper": false, "legalTermsDigital": true, "parentalConsent": false, "registrationSocialTariffEndDate": "2027-04-30" } } } } }, "description": "Updated Passholder" }, "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ] } }, "/passholders/{passholderId}/picture": { "parameters": [ { "schema": { "type": "string" }, "name": "passholderId", "in": "path", "description": "Unique ID of an UiTPAS passholder.", "required": true } ], "get": { "summary": "Get picture of passholder", "operationId": "get-passholders-passholderId-picture", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassholderPicture" }, "examples": { "Example": { "value": { "pictureUrl": "https://api-test.uitpas.be/passholders/481f8595-97cb-45c5-8a04-7fe3df860e0b/picture.png?token=b0f08488-f1f2-4709-8748-c529de66fdc5" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Retrieve picture of the given passholder.\n\nThis endpoint allows you to obtain a short-lived link to the picture of the passholder. After generation, this link remains active for a limited time, enabling you to include it in HTML pages displayed to your users.\n\nThe caller of this method must have `PASSHOLDERS_PICTURE_READ` permission for the given passholder.", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "tags": [ "Passholders" ] }, "put": { "summary": "Update picture of passholder", "operationId": "put-passholders-passholderId-picture", "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data\n\nThe detail property might include more information for the client developer. ", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "description": "Update the picture of a passholder.\n\nThe caller of this method must have `PASSHOLDERS_PICTURE_WRITE` permission for the given passholder.", "tags": [ "Passholders" ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The picture to upload." } }, "required": [ "file" ] }, "examples": { "Example": { "value": { "file": "bytes" } } } } }, "description": "The picture of the passholder in a multipart request body." }, "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ] }, "delete": { "summary": "Delete picture of passholder", "operationId": "delete-passholders-passholderId-picture", "responses": { "204": { "description": "No Content", "content": {} }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Delete the picture of a passholder.\n\nThe caller of this method must have `PASSHOLDERS_PICTURE_WRITE` permission for the given passholder.\n", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "tags": [ "Passholders" ] } }, "/passholders/{passholderId}/memberships/{cardSystemId}": { "parameters": [ { "schema": { "type": "string" }, "name": "passholderId", "in": "path", "description": "Unique ID of an UiTPAS passholder.", "required": true }, { "schema": { "type": "integer" }, "name": "cardSystemId", "in": "path", "required": true, "description": "ID of the card system for the new membership" } ], "post": { "summary": "Create or replace card system membership of passholder", "operationId": "post-passholders-passholderId-memberships-cardSystemId", "responses": { "201": { "description": "Created" }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": {} } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Creates or replaces a membership for the given passholder in the specified card system.\n\nReasons to use this endpoint:\n* Create membership in a new card system for an existing passholder (with or without social tariff)\n* Replace membership in existing card system to grant social tariff\n* Replace membership in existing card system to revoke social tariff\n\nIf you want to extend the social tariff period of an existing passholder, use `PUT /passholders/{id}`\n\nCreating a membership might incur costs which can be checked with `/passholders/id/membership-prices/cardsystemid` \n\nThe caller must have the `PASSHOLDERS_WRITE`. Creating a membership with a social tariff additionally requires `PASSHOLDERS_WRITE_SOCIAL_TARIFF`, and doing so in a city other than the `organizer` (TODO) additionally requires `PASSHOLDERS_WRITE_SOCIALTARIFF_FULL_CARDSYSTEM`. These permissions are cumulative.", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipRequest" }, "examples": { "Example": { "value": { "cardType": "NFC_CARD", "uitpasNumber": "1234567890123", "socialTariff": { "socialTariffEndDate": "2027-04-30" }, "registrationOrganizer": { "id": "abc12345" } } } } } }, "description": "Association membership request" }, "parameters": [], "tags": [ "Passholders" ] }, "get": { "summary": "Preview a new membership", "operationId": "get-passholders-passholderId-memberships-cardSystemId", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "x-stoplight": { "id": "bsp7bwj4bbrqn" }, "enum": [ "NOT_POSSIBLE", "NEW_MEMBERSHIP", "REPLACE_MEMBERSHIP" ], "description": "Type of the new membership request" }, "socialTariffEndDate": { "type": "string", "x-stoplight": { "id": "tznxdyxr4jnjs" }, "format": "date", "description": "The system default social tariff end date (if this request is `socialTariff=true`." }, "addressChangeRequired": { "type": "boolean", "x-stoplight": { "id": "x8xlvhvvbq507" }, "description": "Whether a passholder address change is required when creating this new membership." }, "replacedMembership": { "$ref": "#/components/schemas/CardSystemMembership" } }, "required": [ "type", "addressChangeRequired" ] }, "examples": { "Example 1": { "value": { "type": "NOT_POSSIBLE", "addressChangeRequired": false } }, "Example 2": { "value": { "type": "NEW_MEMBERSHIP", "socialTariffEndDate": "2027-04-30", "addressChangeRequired": false } }, "Example 3": { "value": { "type": "REPLACE_MEMBERSHIP", "socialTariffEndDate": "2027-04-30", "addressChangeRequired": true, "replacedMembership": { "cardSystem": { "id": 1, "name": "UiTPAS Dender", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "9300", "name": "Aalst" }, { "postalCode": "9400", "name": "Ninove" } ], "permanent": true }, "uitpasNumber": "00000009007", "currentCard": { "uitpasNumber": "00000009007", "cardType": "NFC_CARD", "status": "ACTIVE" }, "status": "ACTIVE", "socialTariff": { "status": "ACTIVE", "endDate": "2019-08-24T14:15:22Z", "inGracePeriod": true, "suspendedUntilDate": "2019-08-24T14:15:22Z", "expired": true } } } } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/organizer-not-found\n* https://api.publiq.be/probs/uitpas/passholder-new-membership-error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Checks what would happen if a new membership were created for the given passholder in the specified card system.\n\nUse this endpoint before creating the membership with `POST /passholders/{passholderId}/memberships/{cardSystemId}`. It returns one of the following results:\n\n* `NOT_POSSIBLE`: The passholder already has an identical membership, so no new membership can be created.\n* `NEW_MEMBERSHIP`: The membership can be added without affecting any existing membership.\n* `REPLACE_MEMBERSHIP`: The membership can be added, but it will replace an existing one. The membership to be replaced is returned in `replacedMembership`.\n\nIf a social tariff is requested, the passholder's address may need to be changed to one of the cities in the card system. When this is the case, `addressChangeRequired` is `true`.\n\nThe caller must have the `PASSHOLDERS_WRITE` permission. Checking a membership with a social tariff additionally requires `PASSHOLDERS_WRITE_SOCIAL_TARIFF`.", "tags": [ "Passholders" ], "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "parameters": [ { "schema": { "type": "boolean" }, "in": "query", "name": "socialTariff", "description": "New membership with social tariff", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "organizerId", "description": "Organizer that would perform the create membership", "required": true } ] } }, "/passholders/{passholderId}/association-memberships": { "parameters": [ { "schema": { "type": "string" }, "name": "passholderId", "in": "path", "description": "Unique ID of an UiTPAS passholder.", "required": true } ], "get": { "summary": "Get association memberships of passholder", "operationId": "get-passholders-passholderId-association-memberships", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AssociationMembership" } }, "examples": { "Example": { "value": [ { "association": { "id": "e8386a24-2218-4269-8b65-4de46be07991", "name": "Ledenkaart sport" }, "status": "ACTIVE", "endDate": "2026-08-24", "renewable": true }, { "association": { "id": "61746fed-63ba-45b7-805e-c78555007420", "name": "Medewerker ABC" }, "status": "NONE", "renewable": false }, { "association": { "id": "3e33c4ec-8f87-4eef-8101-0c27e79136ea", "name": "Medewerker XYZ" }, "status": "EXPIRED", "endDate": "2024-08-24", "renewable": true } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Retrieves existing and potential association memberships for a given passholder. Only memberships for associations visible to the specified organizer are returned. If the organizer has permission to register the passholder for a new association, a potential membership for that association is included in the response with the status `NONE`.\n\nMemberships with an `ACTIVE` or `EXPIRED` status are eligible for renewal if their `renewable` field is set to `true`.\n\nThe caller of this method must have `ASSOCIATIONS` permission for the given organizer.", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "tags": [ "Associations" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "organiserId", "description": "ID of the organizer. This parameter is deprecated. Use organizerId instead.", "deprecated": true }, { "schema": { "type": "string" }, "in": "query", "name": "organizerId", "description": "ID of the organizer. This parameter is mandatory." } ] }, "post": { "summary": "Create or renew association membership of passholder", "operationId": "post-passholders-passholderId-association-memberships", "responses": { "201": { "description": "Created" }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data\n* https://api.publiq.be/probs/uitpas/association-not-found\n* https://api.publiq.be/probs/uitpas/association-membership-renew-not-possible\n* https://api.publiq.be/probs/uitpas/association-passholder-cardsystem-mismatch", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": {} } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Creates a new membership or renews an existing one for the given passholder and association. Membership creation and renewal are restricted to associations visible and editable by the specified organizer.\n\nThe caller of this method must have `ASSOCIATIONS` permission for the given organizer.", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssociationMembership" }, "examples": { "Example": { "value": { "association": { "id": "e8386a24-2218-4269-8b65-4de46be07991" }, "endDate": "2026-08-24" } } } } }, "description": "Association membership request" }, "tags": [ "Associations" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "organizerId", "description": "ID of the organizer used to make this request", "required": true } ] } }, "/passholders/{passholderId}/association-memberships/{associationId}": { "parameters": [ { "schema": { "type": "string" }, "name": "passholderId", "in": "path", "description": "Unique ID of an UiTPAS passholder.", "required": true }, { "schema": { "type": "string" }, "name": "associationId", "in": "path", "required": true, "description": "ID of the association." } ], "delete": { "summary": "Delete association membership of passholder", "operationId": "delete-passholders-passholderId-association-memberships-associationId", "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Delete an existing membership of the passholder for the given association. Membership deletion is restricted to associations visible and editable by the specified organizer.\n\nThe caller of this method must have `ASSOCIATIONS` permission for the given organizer.", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "tags": [ "Associations" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "organizerId", "description": "ID of the organizer.", "required": true } ] } }, "/passholders/{passholderId}/coupons": { "parameters": [ { "schema": { "type": "string" }, "name": "passholderId", "in": "path", "description": "Unique ID of an UiTPAS passholder.", "required": true } ], "get": { "summary": "Get coupons of passholder", "operationId": "get-passholders-passholderId-coupons", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GrantedCoupon" } }, "examples": { "Example": { "value": [ { "id": 21343, "coupon": { "id": "COUPON_12", "name": "Gratis naar de film", "description": "Gratis naar de film omschrijving" }, "validityPeriod": { "begin": "2026-01-31T23:00:00+00:00", "end": "2026-06-30T22:00:00+00:00" }, "status": "ACTIVE", "remaining": { "volume": 1, "period": "ABSOLUTE" } } ] } } } } }, "400": { "description": "Bad request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/passholder-no-active-cardsystems\n* https://api.publiq.be/probs/uitpas/organizer-not-found\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Retrieve coupons of given passholder.\n\nThe caller of this method must have `PASSHOLDER_COUPONS_READ` permission.", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "tags": [ "Passholders" ], "parameters": [ { "schema": { "type": "string", "enum": [ "ACTIVE", "EXPIRED", "ALL" ], "default": "ACTIVE" }, "in": "query", "name": "status", "description": "Status of the granted coupon" }, { "schema": { "type": "string" }, "in": "query", "description": "Filter coupons that are applicable in card systems of this organizer", "name": "organizerId" } ] } }, "/passholders/me/uitid/registration-token": { "parameters": [], "get": { "summary": "Retrieve UiTiD registration token", "operationId": "get-uitid-passholder-registration-token", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "UiTPAS number of the validated passholder" } }, "required": [ "token" ], "readOnly": true }, "examples": { "Example": { "value": { "token": "4f5ac68b-e85a-4c38-ad8c-a07a253ed692" } } } } }, "description": "OK\n\nThe passholder can proceed UiTiD registration." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "description": "Too Many Requests\n\nPossible error types:\n\n* https://api.publiq.be/probs/uitpas/rate-limited\n\nThe detail property might include more information for the client developer.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Example": { "value": { "type": "https://api.publiq.be/probs/uitpas/rate-limited", "title": "Rate limited", "status": 429, "detail": "Rate limited" } } } } } } }, "description": "This is step 1 of the process to register an UiTPAS passholder in UiTiD using their UiTPAS number and date of birth. It is used to retrieve an UiTiD registration token for the passholder. If the passholder already has a token via an email they received to register in UiTiD, this step can be skipped.\n\nThis endpoint uses [HTTP Basic Authentication](https://datatracker.ietf.org/doc/html/rfc7617) using:\n* Username: uitpasNumber \n* Password: dateOfBirth in the form yyyy-mm-dd\n\nIn summary, this header should look like: \n\n```\nAuthorization: Basic base64(uitpasNumber:dateOfBirth)\n```\n\nThe response will contain a `token` property that can be used in step 2 of the process, [retrieving the UiTiD registration status](/reference/uitpas.json/paths/~1passholders~1me~1uitid~1status/get).\n\nThis caller of this method is identified with [client identification](https://docs.publiq.be/docs/authentication/ZG9jOjExODE5NDY5-client-identification) and does not require any permissions, but please note this endpoint is rate-limited on IP address to prevent abuse.", "parameters": [ { "schema": { "type": "string" }, "in": "header", "required": true, "name": "authorization", "description": "HTTP Basic auth using uitpasNumber as the username and dateOfBirth as password" }, { "schema": { "type": "string" }, "in": "header", "name": "x-client-id", "description": "API key identifying the calling client", "required": true } ], "tags": [ "Current Passholder" ] } }, "/passholders/me/uitid/status": { "parameters": [], "get": { "summary": "Retrieve UiTiD registration status", "operationId": "get-uitid-passholder-status", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "uitpasNumber": { "type": "string", "description": "UiTPAS number of the validated passholder" }, "email": { "type": "string", "description": "Optionally email address of the validated passholder" }, "state": { "type": "string", "enum": [ "REGISTERED", "UNREGISTERED" ], "description": "State of the passholder" } }, "required": [ "uitpasNumber", "state" ], "readOnly": true }, "examples": { "Unregistered passholder without email": { "value": { "state": "UNREGISTERED", "uitpasNumber": "0900000008301" } }, "Unregistered passholder including email": { "value": { "state": "UNREGISTERED", "uitpasNumber": "0900000008301", "email": "john@example.org" } }, "Registered passholder": { "value": { "state": "REGISTERED", "uitpasNumber": "0900000008301", "email": "john@example.org" } } } } }, "description": "OK\n\nThe passholder can proceed UiTiD registration." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "description": "Too Many Requests\n\nPossible error types:\n\n* https://api.publiq.be/probs/uitpas/rate-limited\n\nThe detail property might include more information for the client developer.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Example": { "value": { "type": "https://api.publiq.be/probs/uitpas/rate-limited", "title": "Rate limited", "status": 429, "detail": "Rate limited" } } } } } } }, "description": "Retrieves the UiTiD registration status of a passholder. This is step 2 in the process of registering an UiTPAS passholder in UiTiD.\n\nThis endpoint requires a registation token in the `x-registration-token` header. A client can obtain such a token using [`GET /passholders/me/uitid/registration-token`](/reference/uitpas.json/paths/~1passholders~1me~1uitid~1registration-token/get). Alternatively, a token may already be available to the client because the user may have received an email link including it.\n\nBased on the state value, the client can proceed in 2 ways:\n\n- If state is `UNREGISTERED`\n\nThe passholder can proceed to step 3, [retrieving the UiTiD email address status](/reference/uitpas.json/paths/~1uitid~1emails~1{email}/get).\n\nThe response can include the linked `email` address of the passholder if one is known. This can be used in the next step of the registration process ([`GET /uitid/emails/{email}`](/reference/uitpas.json/paths/~1uitid~1emails~1{email}/get)). If no email address is included, the client should prompt the user to enter their email address first before proceeding to step 3.\n\n- If state is `REGISTERED` \n\nThe passholder is already `REGISTERED` so the user must continue by authenticating instead. The `email` address field contains the email address of the linked UiTiD account that should be used to authenticate.\n\n\nThis caller of this method, identified with [client identification](https://docs.publiq.be/docs/authentication/ZG9jOjExODE5NDY5-client-identification) does not require any permissions.", "parameters": [ { "schema": { "type": "string" }, "in": "header", "required": true, "name": "x-registration-token", "description": "the registration token of this passholder" }, { "schema": { "type": "string" }, "in": "header", "name": "x-client-id", "description": "API key identifying the calling client", "required": true } ], "tags": [ "Current Passholder" ] } }, "/uitid/emails/{email}": { "parameters": [ { "schema": { "type": "string" }, "name": "email", "in": "path", "required": true, "description": "Email address the passholder wants to use to register" } ], "get": { "summary": "Retrieve UiTiD email address status", "operationId": "get-uitid-email", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "UITID_UNREGISTERED", "UITID_REGISTERED", "UITPAS_ALREADY_LINKED" ], "description": "* `UITPAS_ALREADY_LINKED` : the user cannot use this email address to register another UiTPAS\n* `UITID_UNREGISTERED` : the user can use this email address to register their UiTPAS but must register on UiTiD first\n* `UITID_REGISTERED` : the user can use this email address to register their UiTPAS but must login on UiTiD first" } }, "required": [ "state" ], "readOnly": true }, "examples": { "Example": { "value": { "state": "UITID_UNREGISTERED" } } } } }, "description": "OK\n\nThe email address can be used to register the passholder." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "description": "Too Many Requests\n\nPossible error types:\n\n* https://api.publiq.be/probs/uitpas/rate-limited\n\nThe detail property might include more information for the client developer.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Example": { "value": { "type": "https://api.publiq.be/probs/uitpas/rate-limited", "title": "Rate limited", "status": 429, "detail": "Rate limited" } } } } } } }, "description": "Retrieves the email address status in UiTPAS and UiTiD for a given email address. This is step 3 in the process of registering an UiTPAS passholder in UiTiD.\n\nThe response contains a `state` property which can be one of the following values:\n\n* `UITPAS_ALREADY_LINKED` : the user cannot use this email address to register another UiTPAS\n* `UITID_UNREGISTERED` : the user can use this email address to register their UiTPAS but must register on UiTiD first\n* `UITID_REGISTERED` : the user can use this email address to register their UiTPAS but must login on UiTiD first\n\nAfter [UiTiD authentication](https://docs.publiq.be/docs/authentication/ZG9jOjExODE5NTM5-user-access-token) the client should proceed to step 4 of the process, [registering UiTiD for the passholder](/reference/uitpas.json/paths/~1passholders~1me~1uitid/put).\n\nThis caller of this method, identified with [client identification](https://docs.publiq.be/docs/authentication/ZG9jOjExODE5NDY5-client-identification), does not require any permissions but please note this endpoint is rate-limited on IP address to prevent abuse.", "tags": [ "UiTiD" ], "parameters": [], "security": [ { "CLIENT_IDENTIFICATION": [] }, { "CLIENT_ACCESS_TOKEN": [] }, { "USER_ACCESS_TOKEN": [] } ] } }, "/passholders/membership-prices/{cardSystemId}": { "get": { "summary": "Retrieve new membership price", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipPrice" }, "examples": { "Example": { "value": { "price": 5, "label": "UiTPAS +18 jaar", "description": "Volwassenen die binnen de regio wonen, betalen 5 euro voor hun UiTPAS" } } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/invalid-postal-code\n* https://api.publiq.be/probs/uitpas/invalid-voucher-code\n\nThe detail property might include more information for the client developer.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": {} } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not found. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/cardsystem-not-found\n* https://api.publiq.be/probs/uitpas/passholder-not-found\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get-passholders-membership-prices-cardSystemId", "description": "Retrieve the exact membership price for a new passholder. `cardType`, `postalCode` and `dateOfBirth` are mandatory to determine the correct price. `socialTariff` and `voucher` are optional.\n\nTo retrieve a list of prices for a card system if not all details are known yet, you can use [GET /card-systems/{cardSystemId}/membership-prices](/reference/uitpas.json/paths/~1card-systems~1{cardSystemId}~1membership-prices/get).\n\nThe caller of this request must have `MEMBERSHIP_PRICES_READ` permission.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "postalCode", "description": "postal code of the residence of the user. Must be a valid Belgian postal code or `0000` for foreign places.", "required": true }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "dateOfBirth", "description": "date of birth of the user used to determine the correct price.", "required": true }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "socialTariff", "description": "whether or not the user is entitled to a social tariff" }, { "schema": { "type": "string" }, "in": "query", "name": "voucher", "description": "optional voucher that might reduce the membership price" }, { "schema": { "type": "string", "enum": [ "NFC_CARD", "DIGITAL" ] }, "in": "query", "name": "cardType", "description": "type of the card", "required": true } ], "tags": [ "Passholders" ], "security": [ { "CLIENT_ACCESS_TOKEN": [] }, { "USER_ACCESS_TOKEN": [] }, { "CLIENT_IDENTIFICATION": [] } ] }, "parameters": [ { "schema": { "type": "integer" }, "name": "cardSystemId", "in": "path", "required": true, "description": "The ID of the card system." } ] }, "/passholders/{passholderId}/membership-prices/{cardSystemId}": { "get": { "summary": "Retrieve upgrade membership price", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipPrice" }, "examples": { "Example": { "value": { "price": 5, "label": "UiTPAS +18 jaar", "description": "Volwassenen die binnen de regio wonen, betalen 5 euro voor hun UiTPAS" } } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/invalid-voucher-code\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not found. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/cardsystem-not-found\n* https://api.publiq.be/probs/uitpas/passholder-not-found\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get-passholders-passholderId-membership-prices-cardSystemId", "description": "Retrieve the exact membership price for an existing passholder in a new card system. `cardType` is mandatory to determine the correct price. `socialTariff` and `voucher` are optional.\n\nTo retrieve the price for a *new* passholder, use [GET /passholders/membership-prices/{cardSystemId}](/reference/uitpas.json/paths/~1passholders~1membership-prices~1{cardSystemId}/get).\n\nTo retrieve a list of prices for a card system if not all details are known yet, you can use [GET /card-systems/{cardSystemId}/membership-prices](/reference/uitpas.json/paths/~1card-systems~1{cardSystemId}~1membership-prices/get).\n\nThe caller of this request must have `PASSHOLDERS_SEARCH` and `MEMBERSHIP_PRICES_READ` permission.", "parameters": [ { "schema": { "type": "boolean" }, "in": "query", "name": "socialTariff", "description": "whether or not the user is entitled to a social tariff" }, { "schema": { "type": "string" }, "in": "query", "name": "voucher", "description": "optional voucher that might reduce the membership price" }, { "schema": { "type": "string", "enum": [ "NFC_CARD", "DIGITAL" ] }, "in": "query", "name": "cardType", "description": "type of the card", "required": true } ], "tags": [ "Passholders" ], "security": [ { "CLIENT_ACCESS_TOKEN": [] }, { "USER_ACCESS_TOKEN": [] } ] }, "parameters": [ { "schema": { "type": "string" }, "name": "passholderId", "in": "path", "description": "Unique ID of an UiTPAS passholder.", "required": true }, { "schema": { "type": "integer" }, "name": "cardSystemId", "in": "path", "required": true, "description": "The ID of the card system." } ] }, "/passholders/me/uitid": { "parameters": [], "put": { "summary": "Register UiTiD for passholder", "operationId": "register-uitid-passholder", "responses": { "201": { "description": "Created. No Content." }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/passholder-already-registered\n* https://api.publiq.be/probs/uitpas/uitid-already-registered\n\nThe detail property might include more information for the client developer.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "description": "Registers the UiTiD for this passholder. This is step 4, and the final step, in the process of registering an UiTPAS passholder in UiTiD.\n\nThis request requires an `Authorization` header with the [user access token](https://docs.publiq.be/docs/authentication/ZG9jOjExODE5NTM5-user-access-token) of an authenticated UiTiD *and* it requires a `x-registration-token` header containing a valid registration token of the passholder.\n\nA user access token of a client with `PASSHOLDERS_REGISTER_UITID` permission is mandatory.", "security": [ { "USER_ACCESS_TOKEN": [] } ], "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "x-registration-token", "description": "the registration token of this passholder", "required": true } ], "tags": [ "Current Passholder" ] } }, "/passholders/me": { "get": { "summary": "Retrieve passholder for the current user", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Passholder" }, "examples": { "Example": { "value": { "id": "1be0fb53-0695-405b-ac09-deafead650af", "name": "Peeters", "firstName": "Marc", "inszNumber": "00000009007", "dateOfBirth": "2000-01-01", "postalCode": "9300", "address": { "postalCode": "9300", "city": "Aalst" }, "creationDate": "2012-08-24T14:15:22+00:00", "registrationOrganizer": { "id": "1234", "name": "Example UiTPAS Organizer" }, "points": 10, "uitidStatus": "UNREGISTERED", "uitpasNumber": "0930012345615", "cardSystemMemberships": [ { "cardSystem": { "id": 1, "name": "UiTPAS Dender", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "9300", "name": "Aalst" }, { "postalCode": "9400", "name": "Ninove" } ], "permanent": true }, "uitpasNumber": "0930012345615", "currentCard": { "uitpasNumber": "0930012345615", "status": "ACTIVE" }, "status": "ACTIVE", "socialTariff": { "status": "ACTIVE", "endDate": "2022-08-24T14:15:22+00:00", "inGracePeriod": false, "expired": false } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found\n\nIf the user does not have a passholder. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/passholder-not-found\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get-passholders-me", "description": "Allows users to retrieve their passholder using a user access token.\n\nA user access token of a client with `PASSHOLDERS_SELF_READ` permission is mandatory. The passholder is retrieved by `inszNumber` if the access token contains the custom claim `https://publiq.be/rrn` (i.e. user has logged in using connection ACM), or by linked UiTiD user (`sub` or `https://publiq.be/uitidv1id` claim of the user access token).", "security": [ { "USER_ACCESS_TOKEN": [] } ], "parameters": [], "tags": [ "Current Passholder" ] }, "post": { "summary": "Register passholder for the current user", "operationId": "post-passholders-me", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Passholder" }, "examples": { "Example": { "value": { "id": "a1e0a6d9-7272-4214-b3bc-17d43f965b43", "name": "Lastname", "firstName": "Firstname", "inszNumber": "19800101003", "uitpasNumber": "0999100000002", "cardSystemMemberships": [ { "cardSystem": { "id": 27, "name": "UiTPAS Dender", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "9300", "name": "Aalst" }, { "postalCode": "9400", "name": "Ninove" } ], "permanent": true }, "uitpasNumber": "0999100000002", "currentCard": { "uitpasNumber": "0999100000002", "status": "ACTIVE" }, "status": "ACTIVE" } ], "postalCode": "9000", "city": "Gent", "uitidStatus": "UNREGISTERED", "address": { "postalCode": "9000", "city": "Gent" }, "email": "firstname.lastname@example.com", "creationDate": "2021-10-15T09:50:51+00:00", "dateOfBirth": "2000-08-24", "registrationOrganizer": { "id": "d2f898b1-455e-44ee-b08a-c4c05b1ab900", "name": "UiTPAS Example organizer" }, "points": 3 } } } } } }, "400": { "description": "Bad request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data\n* https://api.publiq.be/probs/uitpas/insz-in-token-required\n* https://api.publiq.be/probs/uitpas/organizer-not-found\n* https://api.publiq.be/probs/uitpas/cardsystem-not-found\n* https://api.publiq.be/probs/uitpas/forbidden-underaged\n* https://api.publiq.be/probs/uitpas/invalid-city\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "description": "\n\n> WARNING\n>\n> Experimental API. Breaking changes might be introduced in future updates.\n\nAllows users to self-register a passholder using a user access token.\n\nA user access token of a client with `PASSHOLDERS_SELF_REGISTRATION` permission for the `registrationOrganizer` is mandatory. Furthermore, the user access token must contain the custom claim `https://publiq.be/rrn` (i.e. user has to login using connection ACM).\n\nPlease note a user can only self-register one passholder. Use `GET /passholders/me` to check if a passholder already exists for this user.", "requestBody": { "description": "Passholder details of the current user to register.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassholderSelfRegistration" }, "examples": { "Example": { "value": { "name": "Lastname", "firstName": "Firstname", "cardSystem": { "id": 27 }, "email": "firstname.lastname@example.com", "dateOfBirth": "1980-01-01", "postalCode": "9000", "city": "Gent", "registrationOrganizer": { "id": "d2f898b1-455e-44ee-b08a-c4c05b1ab900" } } } } } } }, "security": [ { "USER_ACCESS_TOKEN": [] } ], "tags": [ "Current Passholder" ] }, "parameters": [] }, "/passholders/{passholderId}/checkins": { "post": { "summary": "Check-in passholder using a check-in code", "operationId": "post-passholders-passholderId-checkin", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "addedPoints": { "type": "integer", "description": "Newly added points as a result of this check-in" }, "totalPoints": { "description": "Total points of the passholder after this check-in", "type": "integer" } }, "required": [ "addedPoints", "totalPoints" ] }, "examples": { "Example": { "value": { "addedPoints": 1, "totalPoints": 26 } } } } } }, "400": { "description": "Bad request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data\n* https://api.publiq.be/probs/uitpas/checkin-code-expired\n* https://api.publiq.be/probs/uitpas/checkin-code-invalid\n* https://api.publiq.be/probs/uitpas/passholder-not-found\n* https://api.publiq.be/probs/uitpas/passholder-no-active-cardsystems\n* https://api.publiq.be/probs/uitpas/checkin-not-allowed\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": {} } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "description": "Too Many Requests\n\nPossible error types:\n\n* https://api.publiq.be/probs/uitpas/rate-limited\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Allow passholders to self check-in at an event using a check-in code (typically a QR code the passholder can scan). If you want to check-in a passholder based on an event id, use [POST /checkins](/reference/uitpas.json/paths/~1checkins/post) instead. \n\nIf a user access token of a passholder is used, you can specify the path parameter `passholderId` as:\n- the id of the passsholder of the access token (you can retrieve the id using `/passholders/me`)\n- `me` as a short form for the passholder of the access token\n- a passholder id of one of the passholder's family members\n\nIf a user access token of an admin, or a client access token is used, `me` cannot be used as a passholder id.\n\nThe caller of this method must have `PASSHOLDERS_SELF_CHECKIN` permission for the given passholder.", "requestBody": { "description": "The check-in code of an event is typically presented to the user as a printed QR code or as a QR code displayed on a check-in device.", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkinCode": { "type": "string", "description": "Check-in code of the event." } }, "required": [ "checkinCode" ] }, "examples": { "Example": { "value": { "checkinCode": "abcde123546" } } } } } }, "security": [ { "USER_ACCESS_TOKEN": [] } ], "tags": [ "Passholders" ] }, "parameters": [ { "schema": { "type": "string" }, "name": "passholderId", "in": "path", "required": true, "description": "Passholder ID or `me`" } ] }, "/passholders/{passholderId}/transactions": { "parameters": [ { "schema": { "type": "string" }, "name": "passholderId", "in": "path", "required": true, "description": "Passholder ID or `me`" } ], "get": { "summary": "Retrieve transaction history of a passholder", "operationId": "get-passholders-passholderId-transactions", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionsPaginatedCollection" }, "examples": { "Example": { "value": { "totalItems": 3, "member": [ { "title": "Gratis koffie", "location": "Bibliotheek Oostende", "creationDate": "2019-08-24T15:11:00+00:00", "points": -4 }, { "title": "Bezoek aan de bib", "location": "Bibliotheek Oostende", "creationDate": "2019-08-24T14:17:00+00:00", "points": 1 }, { "title": "Welkom bij UiTPAS", "location": "Bibliotheek Oostende", "creationDate": "2019-08-24T14:15:00+00:00", "points": 3 } ] } } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/invalid-uitpas-number\n* https://api.publiq.be/probs/url/query-limit-exceeded\n\nThe detail property might include more information for the client developer.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "description": "Retrieve the transaction history of the passholder.\n\nIf a user access token of a passholder is used, you can specify the path parameter `passholderId` as:\n- the id of the passsholder of the access token (you can retrieve the id using `/passholders/me`)\n- `me` as a short form for the passholder of the access token\n- a passholder id of one of the passholder's family members\n\nIf a user access token of an admin, or a client access token is used, `me` cannot be used as a passholder id.\n\nThe caller of this method must have `PASSHOLDERS_SELF_CHECKIN` permission for the given passholder.", "security": [ { "USER_ACCESS_TOKEN": [] } ], "parameters": [ { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "in": "query", "name": "sort[creationDate]", "description": "Sorts the transactions by creationDate in ascending or descending order." } ], "tags": [ "Passholders" ] } }, "/passholders/{passholderId}/family-members": { "get": { "summary": "Retrieve family members of the current passholder", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FamilyMember" } }, "examples": { "Multiple family members": { "value": [ { "passholder": { "id": "1be0fb53-0695-405b-ac09-deafead650af", "name": "Peeters", "firstName": "Marc", "inszNumber": "00000009007", "dateOfBirth": "2000-01-01", "postalCode": "9300", "address": { "postalCode": "9300", "city": "Aalst" }, "creationDate": "2012-08-24T14:15:22+00:00", "registrationOrganizer": { "id": "1234", "name": "Example UiTPAS Organizer" }, "points": 10, "uitidStatus": "UNREGISTERED", "uitpasNumber": "0930012345615", "cardSystemMemberships": [ { "cardSystem": { "id": 1, "name": "UiTPAS Dender", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "9300", "name": "Aalst" }, { "postalCode": "9400", "name": "Ninove" } ], "permanent": true }, "uitpasNumber": "0930012345615", "currentCard": { "uitpasNumber": "0930012345615", "status": "ACTIVE" }, "status": "ACTIVE", "socialTariff": { "status": "ACTIVE", "endDate": "2022-08-24T14:15:22+00:00", "inGracePeriod": false, "expired": false } } ] }, "creationDate": "2019-08-24T14:15:22+00:00", "icon": "https://www.uitpas.be/_nuxt/img/icon1.png", "mainFamilyMember": true }, { "uitpasNumber": "0900000067513", "creationDate": "2023-08-24T14:15:22+00:00", "passholder": { "id": "2be0fb53-0695-405b-ac09-deafead650af", "name": "Peeters", "firstName": "Clara", "inszNumber": "00000009008", "dateOfBirth": "2000-01-01", "postalCode": "9300", "address": { "postalCode": "9300", "city": "Aalst" }, "creationDate": "2012-08-24T14:15:22+00:00", "registrationOrganizer": { "id": "1234", "name": "Example UiTPAS Organizer" }, "points": 5, "uitidStatus": "UNREGISTERED", "uitpasNumber": "0900000067513", "cardSystemMemberships": [ { "cardSystem": { "id": 1, "name": "UiTPAS Dender", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "9300", "name": "Aalst" }, { "postalCode": "9400", "name": "Ninove" } ], "permanent": true }, "uitpasNumber": "0900000067513", "currentCard": { "uitpasNumber": "0900000067513", "status": "ACTIVE" }, "status": "ACTIVE", "socialTariff": { "status": "ACTIVE", "endDate": "2022-08-24T14:15:22+00:00", "inGracePeriod": false, "expired": false } } ] }, "icon": "https://www.uitpas.be/_nuxt/img/icon2.png", "mainFamilyMember": false }, { "uitpasNumber": "0900000036112", "creationDate": "2023-08-24T14:18:22+00:00", "passholder": { "id": "3be0fb53-0695-405b-ac09-deafead650af", "name": "Peeters", "firstName": "Loius", "inszNumber": "00000009009", "dateOfBirth": "2000-01-01", "postalCode": "9300", "address": { "postalCode": "9300", "city": "Aalst" }, "creationDate": "2012-08-24T14:15:22+00:00", "registrationOrganizer": { "id": "1234", "name": "Example UiTPAS Organizer" }, "points": 1, "uitidStatus": "UNREGISTERED", "uitpasNumber": "0900000036112", "cardSystemMemberships": [ { "cardSystem": { "id": 1, "name": "UiTPAS Dender", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "9300", "name": "Aalst" }, { "postalCode": "9400", "name": "Ninove" } ], "permanent": true }, "uitpasNumber": "0900000036112", "currentCard": { "uitpasNumber": "0900000036112", "status": "ACTIVE" }, "status": "ACTIVE", "socialTariff": { "status": "ACTIVE", "endDate": "2022-08-24T14:15:22+00:00", "inGracePeriod": false, "expired": false } } ] }, "firstName": "Louis", "name": "Peeters", "points": 2, "icon": "https://www.uitpas.be/_nuxt/img/icon3.png", "mainFamilyMember": false } ] }, "No other family members": { "value": [ { "passholder": { "id": "1be0fb53-0695-405b-ac09-deafead650af", "name": "Peeters", "firstName": "Marc", "inszNumber": "00000009007", "dateOfBirth": "2000-01-01", "postalCode": "9300", "address": { "postalCode": "9300", "city": "Aalst" }, "creationDate": "2012-08-24T14:15:22+00:00", "registrationOrganizer": { "id": "1234", "name": "Example UiTPAS Organizer" }, "points": 10, "uitidStatus": "UNREGISTERED", "uitpasNumber": "0930012345615", "cardSystemMemberships": [ { "cardSystem": { "id": 1, "name": "UiTPAS Dender", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "9300", "name": "Aalst" }, { "postalCode": "9400", "name": "Ninove" } ], "permanent": true }, "uitpasNumber": "0930012345615", "currentCard": { "uitpasNumber": "0930012345615", "status": "ACTIVE" }, "status": "ACTIVE", "socialTariff": { "status": "ACTIVE", "endDate": "2022-08-24T14:15:22+00:00", "inGracePeriod": false, "expired": false } } ] }, "creationDate": "2019-08-24T14:15:22+00:00", "icon": "https://www.uitpas.be/_nuxt/img/icon1.png", "mainFamilyMember": true } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get-passholders-passholderId-family-members", "description": "Retrieve family members of a given passholder.\n\nThe list of family members is specific to this passholder, the family relation is not mutual, \nthe total number of family members and the number of adults in a family is limited. \n\nThe passholder identified by `{passholderId}` is always part of this list and its boolean property `mainFamilyMember` will be `true`.\n\nThe caller of this method must have `PASSHOLDERS_FAMILY_MEMBERS` permission for the given passholder.", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "parameters": [], "tags": [ "Passholder Family" ] }, "post": { "summary": "Add family members to the current passholder's family", "operationId": "post-passholders-passholderId-family-members", "responses": { "201": { "description": "Created" }, "400": { "description": "Bad request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data\n* https://api.publiq.be/probs/uitpas/passholder-not-found\n* https://api.publiq.be/probs/uitpas/invalid-uitpas-number\n* https://api.publiq.be/probs/uitpas/family-member-already-added\n* https://api.publiq.be/probs/uitpas/too-many-family-members\n* https://api.publiq.be/probs/uitpas/too-many-adults-in-family\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Add another passholder as a family member of the given passholder.\n\nSpecify the `uitpasNumber` and optionally an `icon` for the new family member.\n\nThe caller of this method must have `PASSHOLDERS_FAMILY_MEMBERS` permission for the given passholder.\n\nIf a user access token of a passholder is used (e.g. in an end-user application), an extra `x-registration-header` header is required containing the registration token of the new family member. Use [GET /passholders/me/uitid/registration-token](/reference/uitpas.json/paths/~1passholders~1me~1uitid~1registration-token/get) to retrieve a registration token.\n\nIf an admin user token or client access token with the appropriate permissions is used, the `x-registration-token` header can be ommitted.", "requestBody": { "description": "New family member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyMember" }, "examples": { "Example with icon": { "value": { "uitpasNumber": "1000000520006", "icon": "https://www.uitpas.be/_nuxt/img/icon1.png" } }, "Example without icon": { "value": { "uitpasNumber": "1000000520006" } } } } } }, "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "x-registration-token", "description": "the registration token of the passholder to add as family member. This header is required when using an end-user token. It can be omitted when using an admin or client access token with the appropriate permissions." } ], "tags": [ "Passholder Family" ] }, "parameters": [ { "schema": { "type": "string" }, "name": "passholderId", "in": "path", "required": true, "description": "Passholder ID of the main family member" } ] }, "/passholders/{passholderId}/family-members/{familyMemberId}": { "parameters": [ { "schema": { "type": "string" }, "name": "passholderId", "in": "path", "required": true, "description": "Passholder ID of the main family member" }, { "schema": { "type": "string" }, "name": "familyMemberId", "in": "path", "required": true, "description": "Passholder ID of the family member to update or delete" } ], "put": { "summary": "Update a family member", "operationId": "put-passholders-passholderId-family-members-familyMemberId", "responses": { "202": { "description": "Accepted" }, "400": { "description": "Bad request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Update information of a family member of the given passholder.\n\nThe caller of this method must have `PASSHOLDERS_FAMILY_MEMBERS` permission for the given passholder\n", "parameters": [], "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyMember" }, "examples": { "Example": { "value": { "icon": "https://www.uitpas.be/_nuxt/img/icon1.png" } } } } }, "description": "Updated information of the family member." }, "tags": [ "Passholder Family" ] }, "delete": { "summary": "Delete a family member", "operationId": "delete-passholders-passholderId-family-members-familyMemberId", "responses": { "202": { "description": "Accepted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Delete a family member of a given passholder.\n\nThe main family member is always a member of their family (boolean `mainFamilyMember` is `true`) and cannot be deleted.\n\nThe caller of this method must have `PASSHOLDERS_FAMILY_MEMBERS` permission for the *main family member* or for the *to be deleted family member*, except for custom token authentication.\n\n\n\n\n> Custom tokens\n>\n> Next to regular client and user access tokens, this endpoint also supports 'custom tokens'. In this scenario, the custom token is sent out in an email to the passholder, who is added as a family member. This allows for the reversal of the add operation directly from that email, without further authentication. Unless your client is implementing this flow, you can ignore custom tokens.", "security": [ { "CLIENT_ACCESS_TOKEN": [] }, { "USER_ACCESS_TOKEN": [] }, { "CUSTOM_TOKEN": [] } ], "tags": [ "Passholder Family" ] } }, "/passholders/{passholderId}/families": { "get": { "summary": "Retrieve families of the current passholder", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "description": "List of families", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the main family member", "readOnly": true }, "firstName": { "type": "string", "description": "The firstname of the main family member", "readOnly": true }, "passholderId": { "type": "string", "description": "The passholder ID of the main family member", "readOnly": true }, "email": { "type": "string", "description": "The email address of the main family member", "readOnly": true }, "memberSince": { "type": "string", "format": "date-time", "description": "The creationdate of the current passholder in this family", "readOnly": true } }, "required": [ "name", "firstName", "passholderId", "memberSince" ] } }, "examples": { "Example": { "value": [ { "name": "Peeters", "firstName": "Marc", "passholderId": "55a96a3f-a570-4d4f-8580-fe00caeafcf0", "email": "marc.peeters@uitpas.be", "memberSince": "2023-08-24T14:15:22+00:00" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get-passholders-passholderId-families", "description": "Retrieve the other families to which the given passholder was added. This explicitly excludes the passholder's own family.\n\nThe caller of this method must have `PASSHOLDERS_FAMILY_MEMBERS` permission for the given passholder.", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "parameters": [], "tags": [ "Passholder Family" ] }, "parameters": [ { "schema": { "type": "string" }, "name": "passholderId", "in": "path", "required": true, "description": "Passholder ID" } ] }, "/passholders/{passholderId}/school": { "parameters": [ { "$ref": "#/components/parameters/passholderId" } ], "get": { "summary": "Get passholder school", "operationId": "get-passholders-school", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organizer" }, "examples": { "Example": { "value": { "id": "9c47936c-bdee-11eb-8529-0242ac130003" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not found. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/passholder-not-found\n* https://api.publiq.be/probs/uitpas/school-not-found\n\nThe detail property might include more information for the client developer.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Retrieve the passholder's school.\n\nThe caller of this request must have `PASSHOLDERS_SEARCH` permission.\n\n\n\n> Passholder schools are used to manage passholders in a very specific case. If you are not explicitly working with UiTPAS schools, you will probably **NOT** need this API. \n\nUsing [GET](/reference/uitpas.json/paths/~1passholders~1{passholderId}~1school/get), [PUT](/reference/uitpas.json/paths/~1passholders~1{passholderId}~1school/put) and [DELETE](/reference/uitpas.json/paths/~1passholders~1{passholderId}~1school/delete) on this endpoint, the school of a passholder can be retrieved, updated and deleted. All schools are organizers.", "security": [ { "USER_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] }, { "CLIENT_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] } ], "tags": [ "Schools" ] }, "put": { "summary": "Update passholder school", "operationId": "put-passholders-school", "responses": { "204": { "description": "No Content. Update succeeded." }, "400": { "description": "Bad request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data\n* https://api.publiq.be/probs/uitpas/school-not-found\n\nThe detail property might include more information for the client developer.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not found. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/passholder-not-found\n\nThe detail property might include more information for the client developer.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Update the passholder's school relation.\n\nThe caller of this request must have `PASSHOLDERS_UPDATE` permission.\n\n\n\n> Passholder schools are used to manage passholders in a very specific case. If you are not explicitly working with UiTPAS schools, you will probably **NOT** need this API. \n\nUsing [GET](/reference/uitpas.json/paths/~1passholders~1{passholderId}~1school/get), [PUT](/reference/uitpas.json/paths/~1passholders~1{passholderId}~1school/put) and [DELETE](/reference/uitpas.json/paths/~1passholders~1{passholderId}~1school/delete) on this endpoint, the school of a passholder can be retrieved, updated and deleted. All schools are organizers.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organizer" } } }, "description": "The Organizer object representing the school, with at least the id present. Name will be ignored." }, "security": [ { "USER_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] }, { "CLIENT_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] } ], "tags": [ "Schools" ] }, "delete": { "summary": "Delete passholder school", "operationId": "delete-passholders-school", "responses": { "204": { "description": "No Content. Delete succeeded." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not found. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/passholder-not-found\n\nThe detail property might include more information for the client developer.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Delete the passholder's school relation.\n\nThe user or client performing this request must have `PASSHOLDERS_UPDATE` permission.\n\n\n\n> Passholder schools are used to manage passholders in a very specific case. If you are not explicitly working with UiTPAS schools, you will probably **NOT** need this API. \n\nUsing [GET](/reference/uitpas.json/paths/~1passholders~1{passholderId}~1school/get), [PUT](/reference/uitpas.json/paths/~1passholders~1{passholderId}~1school/put) and [DELETE](/reference/uitpas.json/paths/~1passholders~1{passholderId}~1school/delete) on this endpoint, the school of a passholder can be retrieved, updated and deleted. All schools are organizers.", "security": [ { "USER_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] }, { "CLIENT_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] } ], "tags": [ "Schools" ] } }, "/organizers/{organizerId}/financial-reports/periods": { "parameters": [ { "$ref": "#/components/parameters/organizerId" } ], "get": { "summary": "Get suggested financial report periods", "tags": [ "Financial reports" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ReportPeriod" } }, "examples": { "example-1": { "value": [ { "startDate": "2019-08-24", "endDate": "2019-08-24" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/organizer-not-found\n\nThe detail property might include more information for the client developer.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get-organizers-financial-reports-periods", "security": [ { "USER_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] }, { "CLIENT_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] } ], "description": "Retrieve suggested report periods for an organizer.\n\nThe caller of this request must have `ORGANIZERS_REPORTS` permission for the given organizer.\n" } }, "/organizers/{organizerId}/financial-reports": { "parameters": [ { "$ref": "#/components/parameters/organizerId" } ], "post": { "summary": "Start an export of a financial report", "operationId": "post-organizers-financial-reports", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" }, "examples": { "Example of started export": { "value": { "status": "STARTED", "id": 232432, "creationDate": "2022-06-10T12:26:30+02:00" } } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/organizer-not-found\n\nThe detail property might include more information for the client developer.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Financial reports" ], "description": "Starts a financial report export. The result of this request is a `reportId` that can be used to request the status of the report export and the download.\n\nThe caller of this request must have `ORGANIZERS_REPORTS` permission for the given organizer.\n", "security": [ { "USER_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] }, { "CLIENT_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] } ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportPeriod" }, "examples": { "Example": { "value": { "startDate": "2019-07-01", "endDate": "2019-09-30" } } } } }, "description": "The period for which to generate the financial report. \nThe `ReportPeriod` object can be retrieved using `GET /organizers/{organizerId}/financial-reports/periods` or the `startDate` and `endDate` can be customized." } }, "get": { "summary": "Get financial report exports", "operationId": "get-organizers-financial-reports", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Report" } }, "examples": { "Example": { "value": [ { "status": "AVAILABLE", "id": 123456, "period": { "startDate": "2019-08-24", "endDate": "2019-08-24" }, "creationDate": "2022-06-07T10:01:32+00:00" }, { "status": "FAILED", "id": 345681, "period": { "startDate": "2000-01-01", "endDate": "2020-06-07" }, "creationDate": "2022-06-07T10:02:33+00:00", "message": "Geen financieel overzicht beschikbaar voor periode 2000/01/01 - 2000/06/07" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/organizer-not-found\n\nThe detail property might include more information for the client developer.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Get previously exported financial reports. \n\n> Note: Reports will only be available for a limited amount of time. When they become unavailable, a new export can be requested using `POST /organizers/{organizerId}/financial-reports` \n\n\nThe caller of this request must have `ORGANIZERS_REPORTS` permission for the given organizer.\n", "security": [ { "USER_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] }, { "CLIENT_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] } ], "tags": [ "Financial reports" ] } }, "/organizers/{organizerId}/financial-reports/{reportId}": { "parameters": [ { "$ref": "#/components/parameters/organizerId" }, { "$ref": "#/components/parameters/reportId" } ], "get": { "summary": "Get financial report status", "tags": [ "Financial reports" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" }, "examples": { "Example of a started report": { "value": { "id": 23243, "status": "STARTED", "creationDate": "2022-06-07T10:01:32+00:00" } }, "Example of an available report": { "value": { "id": 23244, "status": "AVAILABLE", "creationDate": "2022-06-07T10:01:32+00:00" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/organizer-not-found\n* https://api.publiq.be/probs/uitpas/report-not-found\n\nThe detail property might include more information for the client developer.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get-organizers-financial-reports-reportId", "description": "Retrieve the status of a previously started report export.\n\nThe caller of this request must have `ORGANIZERS_REPORTS` permission for the given organizer.\n", "security": [ { "USER_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] }, { "CLIENT_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] } ] } }, "/organizers/{organizerId}/financial-reports/{reportId}/download-link": { "parameters": [ { "schema": { "type": "string" }, "name": "organizerId", "in": "path", "required": true, "description": "Unique ID of an UiTPAS organizer. (Same as its ID in UiTdatabank)" }, { "schema": { "type": "integer" }, "name": "reportId", "in": "path", "required": true, "description": "Unique ID of the generated financial report." } ], "get": { "summary": "Get financial report temporary download link", "tags": [ "Financial reports" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "downloadLink": { "type": "string", "description": "Download link of the report" } }, "required": [ "downloadLink" ] }, "examples": { "Example": { "value": { "downloadLink": "https://api-test.uitpas.be/some/path/to/report.zip?ts=202310231357&hash=1b5413636b41e9f774d416358060e613398b3ab017da13f3815c771a988b2d84" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/organizer-not-found\n* https://api.publiq.be/probs/uitpas/report-not-found\n\nThe detail property might include more information for the client developer.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get-organizers-financial-reports-reportId-downloadLink", "description": "Retrieve a temporary download link of an `available` report.\n\nThis endpoint allows you to obtain a short-lived, hassle-free download link for your reports. After generation, this link remains active for a limited time, enabling direct report downloads without the need for additional authentication. This is in particular convenient for applications that need to offer this link to users to start the download. If you wish to download the actual report in your client application, you can use [Download financial report](/reference/uitpas.json/paths/~1organizers~1{organizerId}~1financial-reports~1{reportId}.zip/get).\n\nThe caller of this request must have `ORGANIZERS_REPORTS` permission for the given organizer.\n", "security": [ { "USER_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] }, { "CLIENT_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] } ] } }, "/organizers/{organizerId}/financial-reports/{reportId}.zip": { "parameters": [ { "$ref": "#/components/parameters/organizerId" }, { "$ref": "#/components/parameters/reportId" } ], "get": { "summary": "Download financial report", "responses": { "200": { "description": "OK", "content": { "application/x-zip-compressed": { "schema": { "type": "string", "format": "binary" }, "examples": {} } }, "headers": { "content-disposition": { "schema": { "type": "string", "example": "attachment; filename=\"financialOverview_organizerX_20210526_1512.zip\"" }, "description": "Header indicating that this response should be handled as a separate file download" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/organizer-not-found\n* https://api.publiq.be/probs/uitpas/report-not-found\n\nThe detail property might include more information for the client developer.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": {} } } } }, "operationId": "get-organizers-financial-reports-reportId-zip", "description": "Retrieve the actual report zip file of an `available` report.\n\nIf you need a download link for your users, you can use [Get financial report temporary download link](/reference/uitpas.json/paths/~1organizers~1{organizerId}~1financial-reports~1{reportId}~1download-link/get) instead.\n\nThe caller of this request must have `ORGANIZERS_REPORTS` permission for the given organizer.\n", "tags": [ "Financial reports" ], "security": [ { "USER_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] }, { "CLIENT_ACCESS_TOKEN": [ "https://api.publiq.be/auth/uitpas" ] } ] } }, "/passes": { "parameters": [], "get": { "summary": "Retrieve pass by identifier", "tags": [ "Passholders" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pass" }, "examples": { "Example with expired social tariff and warning message": { "value": { "passholderId": "b34c19fc-bcf9-4d10-aeb2-6bc9efd38b68", "passType": "INDIVIDUAL", "uitpasNumber": "0560002524314", "firstName": "Jan", "points": 12, "postalCode": "1000", "socialTariff": { "status": "EXPIRED", "endDate": "2024-04-30T21:59:00" }, "messages": [ { "level": "WARN", "text": "Je sociaal tarief is verlopen. Contacteer je UiTPAS balie." } ] } }, "Example without social tariff or messages": { "value": { "passholderId": "b34c19fc-bcf9-4d10-aeb2-6bc9efd38b68", "passType": "INDIVIDUAL", "uitpasNumber": "0560002524314", "firstName": "Jan", "points": 12, "postalCode": "1000", "socialTariff": { "status": "NONE" } } }, "Example with social tariff": { "value": { "passholderId": "b34c19fc-bcf9-4d10-aeb2-6bc9efd38b68", "passType": "INDIVIDUAL", "uitpasNumber": "0560002524314", "firstName": "Jan", "points": 12, "postalCode": "1000", "socialTariff": { "status": "ACTIVE", "endDate": "2024-04-30T21:59:00" } } }, "Example with group pass": { "value": { "passholderId": "b34c19fc-bcf9-4d10-aeb2-6bc9efd38b68", "uitpasNumber": "0560002524314", "passType": "GROUP", "firstName": "Groep 1", "points": 0, "postalCode": "9300", "socialTariff": { "status": "NONE" } } } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/passholder-blocked\n* https://api.publiq.be/probs/uitpas/invalid-card-status\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A URI reference that identifies the problem type. Can be used to recognize specific errors in your application code by comparing the complete URI." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem type (for developers)." }, "status": { "type": "integer", "description": "The HTTP status code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem (for developers). " }, "endUserMessage": { "type": "object", "description": "A human-readable explanation of the problem, specifically for end-users, in one or more languages. Typically available for domain errors, but not for errors caused by a technical issue in the integration (for example invalid JSON syntax in a request body). An `nl` value is always provided, other languages may be provided depending on the API and its intended audience. When this property is included, it is strongly encouraged to show this to the end-user.", "properties": { "nl": { "type": "string", "description": "A human-readable explanation of the problem, specifically for end-users, localized in Dutch." }, "fr": { "type": "string", "description": "A human-readable explanation of the problem, specifically for end-users, localized in French." }, "de": { "type": "string", "description": "A human-readable explanation of the problem, specifically for end-users, localized in German." }, "en": { "type": "string", "description": "A human-readable explanation of the problem, specifically for end-users, localized in English." } }, "required": [ "nl" ] }, "schemaErrors": { "type": "array", "description": "A list of one or more schema validation errors (usually used for error type https://api.publiq.be/probs/body/invalid-data).", "items": { "type": "object", "properties": { "jsonPointer": { "type": "string", "format": "json-pointer", "description": "RFC6901 compliant pointer that indicates what property/value was invalid." }, "error": { "type": "string", "description": "A human-readable (but often technical) reason why the property was invalid." } }, "required": [ "jsonPointer", "error" ] } }, "cardStatus": { "type": "string", "description": "If type is `invalid-card-status` this property contains the actual status of the card.", "x-stoplight": { "id": "1fsyhte36c7q9" } }, "passholderId": { "type": "string", "description": "If `cardStatus` is `BLOCKED` or `DELETED`, this property cosntain the passholderId of this pass." }, "passType": { "type": "string", "description": "Indicates whether this pass belongs to an individual passholder or a group (Grouppas)", "x-stoplight": { "id": "jaco6ci93gonj" }, "enum": [ "INDIVIDUAL", "GROUP" ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/pass-not-found\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get-passes", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "description": "Retrieve pass information by one of its identifiers: UiTPAS number, INSZ number, INSZ barcode, or card chip number.\n\nIf the response contains `messages`, they MUST be displayed to the end-user.\n\n\n \n> ##### Important\n> If the queried `identifier` is a card that is not in ACTIVE state, an error is returned. Where applicable, however, the `Passholder` or `Grouppass` may still be retrievable by ID, provided your client has the necessary permissions. For this reason, the cardStatus, passholderId and/or groupPass properties are included in the error response.\n\nThe caller of this request must have `PASSES_READ` permission.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "identifier", "description": "Find pass using identifier of type UiTPAS number, INSZ number, INSZ barcode or card chipnumber.", "required": true } ] } }, "/passes/{uitpasNumber}": { "parameters": [ { "$ref": "#/components/parameters/uitpasNumber" } ], "get": { "summary": "Retrieve pass by UiTPAS number", "tags": [ "Passholders" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pass" }, "examples": { "Example with expired social tariff and warning message": { "value": { "passholderId": "b34c19fc-bcf9-4d10-aeb2-6bc9efd38b68", "uitpasNumber": "0560002524314", "passType": "INDIVIDUAL", "firstName": "Jan", "points": 12, "postalCode": "1000", "socialTariff": { "status": "EXPIRED", "endDate": "2024-04-30T21:59:00" }, "messages": [ { "level": "WARN", "text": "Je sociaal tarief is verlopen. Contacteer je UiTPAS balie." } ] } }, "Example without social tariff or messages": { "value": { "passholderId": "b34c19fc-bcf9-4d10-aeb2-6bc9efd38b68", "uitpasNumber": "0560002524314", "passType": "INDIVIDUAL", "firstName": "Jan", "points": 12, "postalCode": "1000", "socialTariff": { "status": "NONE" } } }, "Example with social tariff": { "value": { "passholderId": "b34c19fc-bcf9-4d10-aeb2-6bc9efd38b68", "uitpasNumber": "0560002524314", "passType": "INDIVIDUAL", "firstName": "Jan", "points": 12, "postalCode": "1000", "socialTariff": { "status": "ACTIVE", "endDate": "2024-04-30T21:59:00" } } } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/passholder-blocked\n* https://api.publiq.be/probs/uitpas/card-blocked\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/pass-not-found\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get-passes-uitpasNumber", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "description": "Retrieve information related to a pass, searched by UiTPAS number.\n\nIf the response contains `messages`, they MUST be displayed to the end-user.\n\nThe caller of this request must have `PASSES_READ` permission.\n\n\n> **Deprecated:** use [GET /passes](/reference/uitpas.json/paths/~1passes/get) with `identification` query param instead.", "deprecated": true } }, "/insz-numbers/{inszNumber}": { "parameters": [ { "$ref": "#/components/parameters/inszNumber" } ], "get": { "summary": "Retrieve pass by INSZ number", "tags": [ "Passholders" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pass" }, "examples": { "Example with expired social tariff and warning message": { "value": { "passholderId": "b34c19fc-bcf9-4d10-aeb2-6bc9efd38b68", "uitpasNumber": "0560002524314", "passType": "INDIVIDUAL", "firstName": "Jan", "points": 12, "postalCode": "1000", "socialTariff": { "status": "EXPIRED", "endDate": "2024-04-30T21:59:00" }, "messages": [ { "level": "WARN", "text": "Je sociaal tarief is verlopen. Contacteer je UiTPAS balie." } ] } }, "Example without social tariff or messages": { "value": { "passholderId": "b34c19fc-bcf9-4d10-aeb2-6bc9efd38b68", "uitpasNumber": "0560002524314", "passType": "INDIVIDUAL", "firstName": "Jan", "points": 12, "postalCode": "1000", "socialTariff": { "status": "NONE" } } }, "Example with social tariff": { "value": { "passholderId": "b34c19fc-bcf9-4d10-aeb2-6bc9efd38b68", "uitpasNumber": "0560002524314", "passType": "INDIVIDUAL", "firstName": "Jan", "points": 12, "postalCode": "1000", "socialTariff": { "status": "ACTIVE", "endDate": "2024-04-30T21:59:00" } } } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/passholder-blocked\n* https://api.publiq.be/probs/uitpas/card-blocked\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/pass-not-found\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get-insz-numbers-inszNumber", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "description": "Retrieve information related to a pass, searched by INSZ number.\n\nIf the response contains `messages`, they MUST be displayed to the end-user.\n\nThe caller of this request must have `PASSES_INSZNUMBERS_READ` permission.\n\n\n> **Deprecated:** use [GET /passes](/reference/uitpas.json/paths/~1passes/get) with `identification` query param instead.", "deprecated": true } }, "/chip-numbers/{chipNumber}": { "parameters": [ { "$ref": "#/components/parameters/chipNumber" } ], "get": { "summary": "Retrieve pass by chip number", "tags": [ "Passholders" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pass" }, "examples": { "Example with expired social tariff and warning message": { "value": { "passholderId": "b34c19fc-bcf9-4d10-aeb2-6bc9efd38b68", "uitpasNumber": "0560002524314", "passType": "INDIVIDUAL", "firstName": "Jan", "points": 12, "postalCode": "1000", "socialTariff": { "status": "ACTIVE", "endDate": "2024-04-30T21:59:00" }, "messages": [ { "level": "WARN", "text": "Je sociaal tarief is verlopen. Contacteer je UiTPAS balie." } ] } }, "Example without social tariff or messages": { "value": { "passholderId": "b34c19fc-bcf9-4d10-aeb2-6bc9efd38b68", "uitpasNumber": "0560002524314", "passType": "INDIVIDUAL", "firstName": "Jan", "points": 12, "postalCode": "1000", "socialTariff": { "status": "NONE" } } }, "Example with social tariff": { "value": { "passholderId": "b34c19fc-bcf9-4d10-aeb2-6bc9efd38b68", "uitpasNumber": "0560002524314", "firstName": "Jan", "passType": "INDIVIDUAL", "points": 12, "postalCode": "1000", "socialTariff": { "status": "ACTIVE", "endDate": "2024-04-30T21:59:00" } } } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/passholder-blocked\n* https://api.publiq.be/probs/uitpas/card-blocked\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/pass-not-found\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get-chip-numbers-chipNumber", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "description": "Retrieve information related to a pass, searched by chip number.\n\nIf the response contains `messages`, they MUST be displayed to the end-user.\n\nThe caller of this request must have `PASSES_CHIPNUMBERS_READ` permission.\n\n\n> **Deprecated:** use [GET /passes](/reference/uitpas.json/paths/~1passes/get) with `identification` query param instead.", "deprecated": true } }, "/rewards": { "get": { "x-internal": false, "summary": "Search rewards", "operationId": "get-rewards", "responses": { "200": { "description": "Paginated collection of rewards.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardsPaginatedResponse" }, "examples": { "Example": { "value": { "totalItems": 1, "member": [ { "id": "1234", "title": "Free entrance for 10 points on 1 specific event", "type": "POINTS", "owningCardSystem": { "id": 1, "name": "UiTPAS Dender" }, "categories": [ "Doen" ], "allCardSystems": true, "status": "ACTIVE", "maxAvailableUnits": 0, "unitsTaken": 0, "promotionalDescription": "this is the mandatory description", "practicalInfo": "this is an optional extra description", "pictures": [ "https://www.uitpas.be/default-picture-for-ticketsale-rewards.png" ], "publicationPeriod": { "begin": "2021-08-24T14:15:22+00:00", "end": "2022-08-24T14:15:22+00:00" }, "redeemPeriod": { "begin": "2021-08-24T14:15:22+00:00", "end": "2022-08-24T14:15:22+00:00" }, "grantingPeriod": { "begin": "2021-08-24T14:15:22+00:00", "end": "2022-08-24T14:15:22+00:00" }, "moreInfoURL": "https://www.uitpas.be/reward/example-more-info", "inSpotlight": false, "points": 10, "forKids": false, "sport": false, "online": false, "featured": true } ], "facet": { "categories": { "Doen": { "name": { "nl": "Doen" }, "count": 402 }, "Gadget": { "name": { "nl": "Gadget" }, "count": 101 } }, "owningCardSystemId": { "1": { "name": { "nl": "UiTPAS Dender" }, "count": 124 }, "8": { "name": { "nl": "UiTPAS Gent" }, "count": 503 } }, "sport": { "true": { "name": { "nl": "Sportactiviteiten" }, "count": 45 }, "false": { "name": { "nl": "Geen sportactiviteiten" }, "count": 458 } }, "forKids": { "true": { "name": { "nl": "Speciaal voor kinderen" }, "count": 24 }, "false": { "name": { "nl": "Niet speciaal voor kinderen" }, "count": 479 } } } } } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/organizer-not-found\n* https://api.publiq.be/probs/uitpas/event-not-found\n* https://api.publiq.be/probs/uitpas/cardsystem-not-found\n* https://api.publiq.be/probs/url/query-limit-exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found. Error type:\n\nhttps://api.publiq.be/probs/url/not-found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Rewards" ], "description": "Search rewards.\n\nThe caller of this request does not need special permissions permission except `REWARDS_PASSHOLDERS_READ` to use the `isRedeemableByPassholderId` and `isInterestingForPassholderId` query parameters.\n\nThis endpoint allows authentication with [client identification](/docs/authentication/ZG9jOjExODE5NDY5-client-identification), [client access tokens](/docs/authentication/ZG9jOjExODE5NDY4-client-access-token), and [user access tokens](/docs/authentication/ZG9jOjExODE5NTM5-user-access-token).", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] }, { "CLIENT_IDENTIFICATION": [] } ], "parameters": [ { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "organizerId", "description": "Include only rewards applicable for this organizer. Can be included more than once to allow multiple values.", "style": "form", "explode": true }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "organizerPostalCode", "description": "Include only rewards applicable for organizers with this postal code. Can be included more than once to allow multiple values.", "style": "form", "explode": true }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "owningCardSystemId", "description": "Include only rewards of this card system. Can be included more than once to allow multiple values.", "style": "form", "explode": true }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "applicableCardSystemId", "description": "Include only rewards applicable to passholders of this card system. Can be included more than once to allow multiple values.", "style": "form", "explode": true }, { "schema": { "type": "string", "enum": [ "POINTS", "WELCOME", "ANY" ], "default": "POINTS" }, "in": "query", "name": "type", "description": "Include only rewards of this type. By default, this is set to `POINTS`. Use `ANY` to include rewards of any type.", "style": "form" }, { "schema": { "type": "string" }, "in": "query", "name": "text", "description": "Free text search in reward name, organizer or city.", "style": "form" }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "categories", "forKids", "sport", "online", "lastChance", "owningCardSystemId", "type" ] } }, "in": "query", "name": "facets", "description": "Request facets of the given field in the response. Can be included more than once to allow multiple values.", "style": "form", "explode": true }, { "schema": { "type": "string", "example": "-redeemCount,points" }, "in": "query", "name": "sort", "description": "Sorts the rewards in a specific order. Possible values are: `name`, `creationdate`, `redeemCount`, `featured`, `points`. Multiple values can be combined in a comma separated string so the rewards are first sorted by the first field, then the second and so on. By default the sort uses ascending order. Descending order can be specified by including a `-` sign before the field that needs to be ordered descending. e.g. use `-redeemCount,points` to sort descending on redeemCount, and next ascending on `points`.", "style": "form" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "sort[name]", "description": "Sorts the rewards by their name in ascending or descending order. This parameter is deprecated. Use the `sort` parameter for more advanced sorting options.", "style": "form", "deprecated": true }, { "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "sort[creationDate]", "description": "Sort on reward creation date. This parameter is deprecated. Use the `sort` parameter for more advanced sorting options.", "style": "form", "deprecated": true }, { "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "sort[redeemCount]", "description": "Sort on redeem count. This parameter is deprecated. Use the `sort` parameter for more advanced sorting options.", "style": "form", "deprecated": true }, { "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "sort[featured]", "description": "Sort on featured. This parameter is deprecated. Use the `sort` parameter for more advanced sorting options.", "style": "form", "deprecated": true }, { "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "sort[points]", "description": "Sort on reward points. This parameter is deprecated. Use the `sort` parameter for more advanced sorting options.", "style": "form", "deprecated": true }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "Goede doel", "Eten en drinken", "Doen", "Gadget of item" ] } }, "in": "query", "name": "categories", "description": "Include only rewards of this category. Can be included more than once to allow multiple values.", "style": "form", "explode": true }, { "schema": { "type": "integer" }, "in": "query", "name": "pointsFrom", "description": "Include only rewards with this value (including) or more points.", "style": "form" }, { "schema": { "type": "integer" }, "in": "query", "name": "pointsTo", "description": "Include only rewards with this value (including) or less points.", "style": "form" }, { "schema": { "type": "string", "default": "ENDUSERS", "enum": [ "ALL", "ENDUSERS", "REDEEMABLE", "REDEEMABLE-FUTURE", "ENDUSER-FUTURE" ] }, "in": "query", "name": "subset", "description": "Include only rewards of a specific subset. Defaults to `ENDUSERS`, which means all active rewards, that are currently published and in its redeem period and are part of a permanent cardsystem. `REDEEMABLE` is the same as `ENDUSER` except filtering on publication date. `ENDUSER-FUTURE` and `REDEEMABLE-FUTURE` is similar to their respective subset, but filters on a redeem date in the future. Set this field to `ALL` to include all rewards.", "style": "form" }, { "schema": { "type": "boolean" }, "in": "query", "name": "sport", "description": "Include only rewards with the sport property true or false. If omitted, rewards with any sport value are included." }, { "schema": { "type": "boolean" }, "in": "query", "name": "forKids", "description": "Include only rewards with the forKids property true or false. If omitted, rewards with any forKids value are included." }, { "schema": { "type": "boolean" }, "in": "query", "name": "featured", "description": "Include only rewards with the featured property true or false. If omitted, rewards with any featured value are included." }, { "schema": { "type": "boolean" }, "in": "query", "name": "online", "description": "Include only rewards with the online property true or false. If omitted, rewards with any online value are included." }, { "schema": { "type": "boolean" }, "in": "query", "name": "lastChance", "description": "Include only rewards with the lastChance property true or false. If omitted, rewards with any lastChance value are included." }, { "schema": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "DELETED" ] }, "in": "query", "name": "status", "description": "Include only rewards with this status. Also set `subset=ALL` to include non-ACTIVE rewards." }, { "schema": { "type": "string" }, "in": "query", "name": "isRedeemableByPassholderId", "description": "Include only rewards that are redeemable by this passholder ID. This means the reward itself is within its redeem period, and all redeem constraints for the passholder are met. A client using this parameter needs `REWARDS_PASSHOLDERS_READ` permission." }, { "schema": { "type": "string" }, "in": "query", "name": "isInterestingForPassholderId", "description": "Include a list of suggested rewards based on the recent activity of this passholder ID. A client using this parameter needs `REWARDS_PASSHOLDERS_READ` permission." } ] }, "post": { "x-internal": false, "summary": "Create new reward", "operationId": "post-rewards", "responses": { "200": { "description": "Reward created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reward" }, "examples": { "Points reward": { "value": { "id": "1234", "type": "POINTS", "title": "Gratis koffie", "owningCardSystem": { "id": 1, "name": "UiTPAS Dender" }, "allCardSystems": true, "status": "ACTIVE", "maxAvailableUnits": 100, "unitsTaken": 0, "promotionalDescription": "this is the mandatory description", "pictures": [ "https://www.uitpas.be/default-picture-for-points-rewards.png" ], "publicationPeriod": { "begin": "2021-08-24T14:15:22+00:00", "end": "2022-08-24T14:15:22+00:00" }, "redeemPeriod": { "begin": "2021-08-24T14:15:22+00:00", "end": "2022-08-24T14:15:22+00:00" }, "moreInfoURL": "https://example.org/more-info-about-this-reward", "inSpotlight": false, "points": 3, "categories": [ "Eten en drinken" ], "forKids": false, "sport": false, "online": true } }, "Welcome reward": { "value": { "id": "1234", "type": "WELCOME", "title": "Gratis zwemmen", "owningCardSystem": { "id": 1, "name": "UiTPAS Dender" }, "allCardSystems": true, "status": "ACTIVE", "maxAvailableUnits": 100, "unitsTaken": 0, "promotionalDescription": "this is the mandatory description", "pictures": [ "https://www.uitpas.be/default-picture-for-welcome-rewards.png" ], "publicationPeriod": { "begin": "2021-08-24T14:15:22+00:00", "end": "2022-08-24T14:15:22+00:00" }, "redeemPeriod": { "begin": "2021-08-24T14:15:22+00:00", "end": "2022-08-24T14:15:22+00:00" }, "grantingPeriod": { "begin": "2021-08-24T14:15:22+00:00", "end": "2022-08-24T14:15:22+00:00" }, "inSpotlight": false, "forKids": false, "sport": false, "online": false } } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data\n* https://api.publiq.be/probs/uitpas/invalid-card-system\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "description": "Create a new reward.\n\nThe caller of this request must have `REWARDS_WRITE` permission for the given organizer.", "tags": [ "Rewards" ], "requestBody": { "description": "Details of the new reward to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reward" }, "examples": { "Points Reward Example": { "value": { "title": "Free entrance for 10 points on 1 specific event", "type": "POINTS", "categories": [ "Doen" ], "promotionalDescription": "this is the mandatory description", "publicationPeriod": { "begin": "2021-08-24T14:15:22+00:00" }, "moreInfoURL": "https://example.org/more-info-about-this-reward", "points": 10 } }, "Welcome Reward Example": { "value": { "title": "Gratis tas koffie", "type": "WELCOME", "promotionalDescription": "this is the mandatory description", "publicationPeriod": { "begin": "2021-08-24T14:15:22+00:00" } } } } } } } } }, "/rewards/{rewardId}": { "get": { "x-internal": false, "summary": "Retrieve reward", "tags": [ "Rewards" ], "responses": { "200": { "description": "Details of the requested reward.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reward" }, "examples": { "Example": { "value": { "id": "1234", "type": "POINTS", "title": "Free entrance for 10 points on 1 specific event UPDATE", "owningCardSystem": { "id": 1, "name": "UiTPAS Dender" }, "allCardSystems": true, "status": "ACTIVE", "maxAvailableUnits": 0, "unitsTaken": 0, "promotionalDescription": "this is the mandatory description", "practicalInfo": "this is an optional extra description", "pictures": [ "https://www.uitpas.be/default-picture-for-ticketsale-rewards.png" ], "publicationPeriod": { "begin": "2021-08-24T14:15:22+00:00", "end": "2022-08-24T14:15:22+00:00" }, "redeemPeriod": { "begin": "2021-08-24T14:15:22+00:00", "end": "2022-08-24T14:15:22+00:00" }, "grantingPeriod": { "begin": "2021-08-24T14:15:22+00:00", "end": "2022-08-24T14:15:22+00:00" }, "moreInfoURL": "https://example.org/more-info-about-this-reward", "inSpotlight": false, "points": 10, "categories": [ "Eten en drinken" ], "forKids": false, "sport": false, "online": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/reward-not-found\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get-rewards-id", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "description": "Retrieve reward by ID.\n\nThe caller of this request must have `REWARDS_READ` permission for the given organizer." }, "parameters": [ { "schema": { "type": "string" }, "name": "rewardId", "in": "path", "required": true, "description": "Unique ID of a single reward." } ], "put": { "x-internal": false, "summary": "Update reward", "operationId": "put-rewards-id", "responses": { "200": { "description": "Updated info for the reward with the given ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reward" }, "examples": { "Example": { "value": { "id": "1234", "type": "POINTS", "title": "Gratis toegangsticket voor het Design Museum Brussel", "owningCardSystem": { "id": 1, "name": "UiTPAS Dender" }, "allCardSystems": true, "status": "ACTIVE", "maxAvailableUnits": 1000, "unitsTaken": 0, "promotionalDescription": "this is the mandatory description", "practicalInfo": "this is an optional extra description", "pictures": [ "https://www.uitpas.be/default-picture-for-ticketsale-rewards.png" ], "publicationPeriod": { "begin": "2021-08-24T14:15:22+00:00", "end": "2022-08-24T14:15:22+00:00" }, "redeemPeriod": { "begin": "2021-08-24T14:15:22+00:00", "end": "2022-08-24T14:15:22+00:00" }, "grantingPeriod": { "begin": "2021-08-24T14:15:22+00:00", "end": "2022-08-24T14:15:22+00:00" }, "moreInfoURL": "https://www.uitpas.be/reward/example-more-info", "inSpotlight": false, "points": 10, "categories": [ "Doen" ], "forKids": false, "sport": false, "online": false } } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data\n* https://api.publiq.be/probs/uitpas/invalid-card-system\n* https://api.publiq.be/probs/uitpas/reward-not-editable\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/reward-not-found\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "requestBody": { "description": "New details for the reward. Will overwrite the previous details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reward" }, "examples": { "Example": { "value": { "title": "Gratis toegangsticket voor het Design Museum Brussel", "type": "POINTS", "maxAvailableUnits": 1000, "categories": [ "Doen" ], "promotionalDescription": "this is the mandatory description", "practicalInfo": "this is an optional extra description", "publicationPeriod": { "begin": "2021-08-24T14:15:22+00:00", "end": "2022-08-24T14:15:22+00:00" }, "redeemPeriod": { "begin": "2021-08-24T14:15:22+00:00", "end": "2022-08-24T14:15:22+00:00" }, "grantingPeriod": { "begin": "2021-08-24T14:15:22+00:00", "end": "2022-08-24T14:15:22+00:00" }, "moreInfoURL": "https://example.org/more-info-about-this-reward", "points": 10 } } } } } }, "tags": [ "Rewards" ], "description": "Update reward.\nTo update a reward correctly, as a client you will typically `GET` the reward first, make the required changes in the reward json and use this `PUT` request to persist those changes in UiTPAS.\n\nDo note that the following fields are **not editable** after this reward is redeemed by (for POINTS rewards) or granted to (for WELCOME rewards) a passholder:\n* redeemPeriod.begin\n* grantingPeriod.begin\n* points\n\nAttempts to edit such rewards will result in an HTTP 400 error with type `https://api.publiq.be/probs/uitpas/reward-not-editable`\n\nThe caller of this request must have `REWARDS_WRITE` permission for the given organizer." } }, "/rewards/{rewardId}/redeem-status": { "parameters": [ { "schema": { "type": "string" }, "name": "rewardId", "in": "path", "required": true, "description": "Unique ID of a single reward." } ], "get": { "x-internal": false, "summary": "Check redeem status of a reward for a passholder", "operationId": "get-rewards-id-redeem-status", "responses": { "200": { "description": "Info that indicates if the reward with the given ID is redeemable or not by the passholder with the given UiTPAS number.", "content": { "application/json": { "schema": { "type": "object", "properties": { "redeemable": { "type": "boolean", "description": "Whether this reward can be redeemed by the given passholder.", "readOnly": true }, "reason": { "type": "string", "description": "If redeemable is false, this field contains the reason why:\n- `INVALID_CARD`: the given `uitpasNumber` is not valid.\n- `PASSHOLDER_VOLUME`: maximum number of times this reward can be redeemed per passholder has been reached.\n- `PASSHOLDER_POINTS`: passholder does not have enough points to redeem this reward.\n- `REWARD_PERIOD`: the current date is outside the redeemPeriod of this reward\n- `REWARD_VOLUME`: maximum number of times this reward can be redeemed (in general) has been reached.\n- `PASSHOLDER_APPLICABLE_CARDSYSTEMS`: the passholder is not a member of one of the applicable card systems of this reward.\n- `PASSHOLDER_NO_ACTIVE_CARDSYSTEMS`: the passholder is not active or has no active card system memberships\n", "enum": [ "INVALID_CARD", "PASSHOLDER_VOLUME", "PASSHOLDER_POINTS", "REWARD_PERIOD", "REWARD_VOLUME", "PASSHOLDER_APPLICABLE_CARDSYSTEMS", "PASSHOLDER_NO_ACTIVE_CARDSYSTEM" ] }, "message": { "type": "string", "description": "User readable message of the reason (only if redeemable if false)", "readOnly": true } }, "required": [ "redeemable" ] }, "examples": { "Example redeemable": { "value": { "redeemable": true } }, "Example not redeemable": { "value": { "redeemable": false, "reason": "PASSHOLDER_POINTS", "message": "Jammer, je hebt nog niet genoeg punten om dit voordeel om te ruilen." } } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/invalid-uitpas-number\n* https://api.publiq.be/probs/uitpas/passholder-not-found\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/reward-not-found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Check the reward redeem status for a passholder.\n\n\nThe caller of this request must have `REWARDS_REDEEM` permission for the given organizer.", "security": [ { "CLIENT_ACCESS_TOKEN": [] }, { "USER_ACCESS_TOKEN": [] } ], "tags": [ "Rewards" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "required": true, "name": "uitpasNumber", "description": "UiTPAS number identifying the passholder who wants to redeem this reward." } ] } }, "/rewards/redeemed": { "parameters": [], "post": { "x-internal": false, "summary": "Redeem reward", "operationId": "post-rewards-redeemed", "responses": { "201": { "description": "Info about the redeemed reward.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemedReward" }, "examples": { "Example": { "value": { "id": "7982c147-7cf6-4268-acdf-ffbd3d77a2ca", "reward": { "id": "374a166b-9170-4f9e-a797-48fb5bd6840d", "title": "A great reward", "type": "POINTS", "promotionalDescription": "This is a description", "publicationPeriod": { "begin": "2019-08-24T14:15:22+00:00", "end": "2019-08-24T14:15:22+00:00" }, "grantingPeriod": { "begin": "2019-08-24T14:15:22+00:00", "end": "2019-08-24T14:15:22+00:00" }, "points": 0, "moreInfoURL": "https://www.uitpas.be/reward/example-more-info", "owningCardSystem": { "id": 1, "name": "UiTPAS Dender" }, "allCardSystems": true, "organizers": [ { "id": "abc12345", "name": "UiTPAS Test Organizer" } ], "status": "ACTIVE", "maxAvailableUnits": 100, "unitsTaken": 0, "practicalInfo": "This is information on how to redeem the reward.", "pictures": [ "https://www.uitpas.be/default-picture-for-ticketsale-rewards.png" ], "redeemPeriod": { "begin": "2019-08-24T14:15:22+00:00", "end": "2019-08-24T14:15:22+00:00" }, "categories": [ "Eten en drinken" ], "forKids": true, "sport": true, "online": false }, "redeemDate": "2019-08-24T14:15:22+00:00", "redeemInfo": { "text": "Info on how to use the redeem code", "link": "https://example.com/redeem-your-reward-here", "label": "Claim your discount" }, "redeemCode": "abc123456789" } } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data\n* https://api.publiq.be/probs/uitpas/invalid-card\n* https://api.publiq.be/probs/uitpas/invalid-uitpas-number\n* https://api.publiq.be/probs/uitpas/passholder-not-found\n* https://api.publiq.be/probs/uitpas/reward-not-found\n* https://api.publiq.be/probs/uitpas/reward-period-constraint\n* https://api.publiq.be/probs/uitpas/reward-volume-constraint\n* https://api.publiq.be/probs/uitpas/reward-passholder-volume-constraint\n* https://api.publiq.be/probs/uitpas/reward-passholder-points-constraint\n* https://api.publiq.be/probs/uitpas/reward-passholder-no-applicable-cardsystems\n* https://api.publiq.be/probs/uitpas/passholder-no-active-cardsystems\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/reward-not-found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Redeem reward.\n\nThe caller of this request must have `REWARDS_REDEEM` permission for the given organizer.", "tags": [ "Rewards" ], "requestBody": { "description": "Reward (id) to mark as redeemed, and for which UiTPAS number specifically.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rewardId": { "type": "string", "description": "ID of reward to redeem" }, "uitpasNumber": { "type": "string", "description": "UiTPAS number of the passholder exchanging this reward." } }, "required": [ "rewardId", "uitpasNumber" ] }, "examples": { "Example": { "value": { "uitpasNumber": "0930012345615", "rewardId": "fce4bd2f-4dca-4a44-9912-6168f0ac7e5e" } } } } } }, "security": [ { "CLIENT_ACCESS_TOKEN": [] }, { "USER_ACCESS_TOKEN": [] } ] }, "get": { "x-internal": false, "summary": "Retrieve redeemed rewards", "operationId": "get-rewards-redeemed", "responses": { "200": { "description": "Paginated collection of redeemed rewards.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemedRewardsPaginatedResponse" }, "examples": { "Example": { "value": { "totalItems": 10, "member": [ { "id": "7982c147-7cf6-4268-acdf-ffbd3d77a2ca", "reward": { "id": "374a166b-9170-4f9e-a797-48fb5bd6840d", "title": "A great reward", "type": "POINTS", "promotionalDescription": "This is a description", "publicationPeriod": { "begin": "2019-08-24T14:15:22+00:00", "end": "2019-08-24T14:15:22+00:00" }, "grantingPeriod": { "begin": "2019-08-24T14:15:22+00:00", "end": "2019-08-24T14:15:22+00:00" }, "points": 0, "moreInfoURL": "https://www.uitpas.be/reward/example-more-info", "owningCardSystem": { "id": 1, "name": "UiTPAS Dender" }, "allCardSystems": true, "organizers": [ { "id": "abc12345", "name": "UiTPAS Test Organizer" } ], "status": "ACTIVE", "maxAvailableUnits": 100, "unitsTaken": 0, "practicalInfo": "This is information on how to redeem the reward.", "pictures": [ "https://www.uitpas.be/default-picture-for-ticketsale-rewards.png" ], "redeemPeriod": { "begin": "2019-08-24T14:15:22+00:00", "end": "2019-08-24T14:15:22+00:00" }, "categories": [ "Eten en drinken" ], "forKids": true, "sport": true, "online": true, "lastChance": true }, "redeemDate": "2019-08-24T14:15:22+00:00", "redeemInfo": { "text": "Info on how to use the redeem code", "link": "https://example.com/redeem-your-reward-here", "label": "Claim your discount" }, "redeemCode": "abc123456789" } ] } } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/invalid-uitpas-number\n* https://api.publiq.be/probs/url/query-limit-exceeded\n\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "description": "Retrieve redeemed rewards for a passholder.\n\nExactly one of query parameters `uitpasNumber` or `passholderId` is required. If both are specified an error is returned.\n\nThe caller of this request must have `REWARDS_READ` permission.", "security": [ { "CLIENT_ACCESS_TOKEN": [] }, { "USER_ACCESS_TOKEN": [] } ], "tags": [ "Rewards" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "uitpasNumber", "description": "UiTPAS number identifying the passholder. Cannot be used in combination with `passholderId`" }, { "schema": { "type": "string", "enum": [ "POINTS", "WELCOME" ] }, "in": "query", "name": "rewardType", "description": "Type of the redeemed reward." }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" }, { "schema": { "type": "string" }, "in": "query", "name": "passholderId", "description": "ID of the passholder. Cannot be used in combination with `uitpasNumber`. `organizerId` is required when using this filter." }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "organizerId", "description": "ID of the organizer where the reward was redeemed.", "explode": true }, { "schema": { "type": "string" }, "in": "query", "name": "rewardTitle", "description": "Filter redeemed rewards with this (partial) reward title." } ] } }, "/rewards/redeemed/{redeemedRewardId}": { "parameters": [ { "schema": { "type": "string" }, "name": "redeemedRewardId", "in": "path", "required": true, "description": "The ID of the redeemed reward" } ], "delete": { "summary": "Cancel a redeemed reward", "operationId": "delete-rewards-redeemed-redeemedRewardId", "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Rewards" ], "description": "Cancel a previously redeemed reward.\n\nThe caller of this request must have `REWARDS_REDEEM` permission for the organizer of the given reward.", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ] } }, "/card-systems": { "get": { "x-internal": false, "summary": "Search card systems", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardSystemsPaginatedCollection" }, "examples": { "Example": { "value": { "totalItems": 0, "member": [ { "id": 1, "name": "UiTPAS Dender", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "9300", "name": "Aalst" }, { "postalCode": "9400", "name": "Ninove" } ], "permanent": true, "cardlessRegistrationType": "ALL" } ] } } } } } }, "400": { "description": "Bad Request. Error type:\n\nhttps://api.publiq.be/probs/uitpas/postal-code-required\nhttps://api.publiq.be/probs/uitpas/invalid-postal-code\n* https://api.publiq.be/probs/url/query-limit-exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found. Error type:\n\nhttps://api.publiq.be/probs/url/not-found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get-card-systems", "description": "Search card systems.\n\nThis caller of this method, identified by client identification, client access token or user access token, does not require any permissions.", "parameters": [ { "schema": { "type": "boolean", "default": true }, "in": "query", "name": "permanent", "description": "Include only permanent (`true`) card systems or temporary (`false`) card systems." }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "city", "description": "Search card systems by city name. Can be included more than once to allow multiple values. Valid values can found in https://taxonomy.uitdatabank.be/api/city", "style": "form", "explode": true }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "postalCode", "description": "Search card systems by postal code. Can be included more than once to allow multiple values. Valid values can found in https://taxonomy.uitdatabank.be/api/city", "style": "form", "explode": true }, { "schema": { "type": "string" }, "in": "query", "name": "sort", "description": "Sorts the cardsystems in a specific order. Possible values are: `name`, `postalCode`. By default the sort uses ascending order. Descending order can be specified by including a `-` sign before the field that needs to be ordered descending. e.g. use `-name` to sort on name descending. `postalCode` sort will geographically sort based on the query param `postalCodeSort`." }, { "schema": { "type": "string" }, "in": "query", "name": "postalCodeSort", "description": "The postalCode that will be used by `sort=postalCode` as its geographic center. If `sort` is not `postalCode` this parameter is ignored. If `sort` is `postalCode`, this parameter is mandatory." } ], "tags": [ "Card Systems" ], "security": [ { "CLIENT_IDENTIFICATION": [] }, { "CLIENT_ACCESS_TOKEN": [] }, { "USER_ACCESS_TOKEN": [] } ] } }, "/card-systems/{cardSystemId}": { "get": { "x-internal": false, "summary": "Retrieve card system", "responses": { "200": { "description": "Details of the requested card system.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardSystem" }, "examples": { "Example": { "value": { "id": 1, "name": "UiTPAS Dender", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "9300", "name": "Aalst" }, { "postalCode": "9400", "name": "Ninove" } ], "permanent": true, "cardlessRegistrationType": "NONE" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/cardsystem-not-found\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get-cardsystems-cardsystemid", "security": [ { "CLIENT_IDENTIFICATION": [] }, { "CLIENT_ACCESS_TOKEN": [] }, { "USER_ACCESS_TOKEN": [] } ], "description": "Retrieve card system by ID.\n\nThis caller of this method, identified by client identification, client access token or user access token, does not require any permissions.", "tags": [ "Card Systems" ] }, "parameters": [ { "schema": { "type": "integer" }, "name": "cardSystemId", "in": "path", "required": true, "description": "The ID of the requested card system" } ] }, "/card-systems/{cardSystemId}/social-tariff-settings": { "get": { "x-internal": false, "summary": "Retrieve social tariff settings for card system", "responses": { "200": { "description": "Social tariff settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardSystemSocialTariffSettings" }, "examples": { "Example": { "value": { "postalCode": "9000", "allowsCardlessRegistration": true } } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/invalid-postal-code\n* https://api.publiq.be/probs/uitpas/postal-code-not-in-card-system", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/cardsystem-not-found\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get-cardsystems-cardsystemid-social-tariff-settings", "security": [ { "CLIENT_IDENTIFICATION": [] }, { "CLIENT_ACCESS_TOKEN": [] }, { "USER_ACCESS_TOKEN": [] } ], "description": "\n\n> **Deprecated:** use [GET /cardsystems/{cardSystemId}/city-settings](/reference/uitpas.json/paths/~1cardssytems~1{cardSystemId}~1city-settings/get) instead.\n\nRetrieve social tariff settings specific for this card system and the given postal code.\n\nThis caller of this method, identified by client identification, client access token or user access token, does not require any permissions.", "tags": [ "Card Systems" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "postalCode", "description": "Postal code of the passholder who is being registered. Can be included more than once to allow multiple values. Valid values can found in https://taxonomy.uitdatabank.be/api/city", "required": true } ], "deprecated": true }, "parameters": [ { "schema": { "type": "integer" }, "name": "cardSystemId", "in": "path", "required": true, "description": "The ID of the requested card system" } ] }, "/card-systems/{cardSystemId}/city-settings": { "get": { "x-internal": false, "summary": "Retrieve city settings for card system", "responses": { "200": { "description": "City specific settings", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CardSystemCitySettings" } }, "examples": { "Example": { "value": [ { "city": "GENT", "allowsCardlessRegistration": true, "contactEmail": "uitpas-gent@example.com" }, { "city": "MERELBEKE-MELLE", "allowsCardlessRegistration": true, "contactEmail": "uitpas-merelbeke-melle@example.com" } ] } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/invalid-postal-code\n* https://api.publiq.be/probs/uitpas/postal-code-not-in-card-system", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/cardsystem-not-found\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get-cardsystems-cardsystemid-city-settings", "security": [ { "CLIENT_IDENTIFICATION": [] }, { "CLIENT_ACCESS_TOKEN": [] }, { "USER_ACCESS_TOKEN": [] } ], "description": "Retrieve city specific settings for this card system.\n\nThis caller of this method, identified by client identification, client access token or user access token, does not require any permissions.", "tags": [ "Card Systems" ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "postalCode", "description": "Filter city setting to the city of this postal code. Can be included more than once to allow multiple values. Valid values can found in https://taxonomy.uitdatabank.be/api/city" } ] }, "parameters": [ { "schema": { "type": "integer" }, "name": "cardSystemId", "in": "path", "required": true, "description": "The ID of the requested card system" } ] }, "/card-systems/{cardSystemId}/membership-prices": { "get": { "summary": "Retrieve membership prices for a card system", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MembershipPrice" } }, "examples": { "Example": { "value": [ { "price": 3, "label": "UiTPAS inwoners +18 jaar", "description": "Volwassenen die binnen de regio wonen, betalen 3 euro voor hun UiTPAS" }, { "price": 0, "label": "UiTPAS inwoners -18 jaar", "description": "Kinderen die binnen de regio wonen krijgen een gratis UiTPAS" }, { "price": 5, "label": "UiTPAS niet-inwoners +18 jaar", "description": "Volwassenen die buiten de regio wonen, betalen 5 euro voor hun UiTPAS" }, { "price": 2, "label": "UiTPAS niet-inwoners -18 jaar", "description": "Kinderen die buiten de regio wonen, betalen 2 euro voor hun UiTPAS" }, { "price": 1, "label": "UiTPAS Kansenpas", "description": "Kansenpashouders betalen 1 euro voor hun UiTPAS" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/cardsystem-not-found\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get-card-systems-cardsystemid-membership-prices", "description": "Retrieve all membership prices by card type for a card system. The result will contain all prices for the cardsystem, which is primarily useful to display to a an anonymous user. To retrieve the price for an individual passholder, you can use [GET /passholders/membership-prices/{cardSystemId}](/reference/uitpas.json/paths/~1passholders~1membership-prices~1{cardSystemId}/get) (more details like social tariff, date of birth and residence are required) or [GET /passholders/{passholderId}/membership-prices/{cardSystemId}](/reference/uitpas.json/paths/~1passholders~1{passholderId}~1membership-prices~1{cardSystemId}/get) (if the passholder already exists).\n\nThis caller of this method, identified by client identification, client access token or user access token, does not require any permissions.", "parameters": [ { "schema": { "type": "string", "enum": [ "DIGITAL", "NFC_CARD" ] }, "in": "query", "name": "cardType", "description": "Type of the card", "required": true } ], "security": [ { "CLIENT_IDENTIFICATION": [] }, { "USER_ACCESS_TOKEN": [] }, { "USER_ACCESS_TOKEN": [] } ], "tags": [ "Card Systems" ] }, "parameters": [ { "schema": { "type": "integer" }, "name": "cardSystemId", "in": "path", "required": true, "description": "The ID of the card system" } ] }, "/orders": { "post": { "summary": "Create online order", "operationId": "post-orders", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "Example pending payment": { "value": { "id": "123456789", "status": "PENDING_PAYMENT", "paymentUrl": "https://payment-url.com", "email": "example@example.org", "totalPrice": 10, "customToken": "U742hZr^FkBQfxqQtz7Y%tt@q%SpoEkR52Q$2heET#G*S&N88CM64&E&H$%Sonop%adVxybPziNYm$NL%%fkKhQwQKpkoSmb8vWVmZ58VPd@87Xa@@a%hPQP&8", "mainPassholderRegistration": { "name": "Peeters", "firstName": "Marc", "inszNumber": "00000009007", "email": "marc.peeters@example.com", "dateOfBirth": "2000-01-01", "registrationOrganizer": { "id": "abc12345" }, "address": { "street": "Grote markt 12", "postalCode": "9300", "city": "Aalst", "country": "be" }, "optInPreferences": { "serviceMails": true, "infoMails": true, "milestoneMails": true, "sms": false, "post": true }, "nationality": "Belg", "legalTermsPaper": false, "legalTermsDigital": true, "parentalConsent": false, "registrationCardSystemId": 1 } } }, "Example pending uitid connect": { "value": { "id": "123456789", "status": "PENDING_UITID_CONNECT", "uitidAuthUrl": "https://uitid.be/auth", "email": "example@example.org", "totalPrice": 10, "registrationToken": "123456789", "mainPassholderRegistration": { "name": "Peeters", "firstName": "Marc", "inszNumber": "00000009007", "email": "marc.peeters@example.com", "dateOfBirth": "2000-01-01", "registrationOrganizer": { "id": "abc12345" }, "address": { "street": "Grote markt 12", "postalCode": "9300", "city": "Aalst", "country": "be" }, "optInPreferences": { "serviceMails": true, "infoMails": true, "milestoneMails": true, "sms": false, "post": true }, "nationality": "Belg", "legalTermsPaper": false, "legalTermsDigital": true, "parentalConsent": false, "registrationCardSystemId": 1 } } } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data\n* https://api.publiq.be/probs/uitpas/organizer-not-found\n* https://api.publiq.be/probs/uitpas/cardsystem-not-found\n* https://api.publiq.be/probs/uitpas/invalid-city\n* https://api.publiq.be/probs/uitpas/invalid-insz-number\n* https://api.publiq.be/probs/uitpas/email-already-used\n* https://api.publiq.be/probs/uitpas/invalid-social-tariff-validation-token\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] }, { "CLIENT_IDENTIFICATION": [] } ], "description": "Create an online order for one or more passholders.\n\nThis caller of this method, identified by client identification, client access token or user access token, must have ORDERS_CREATE permission.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "Example": { "value": { "mainPassholderRegistration": { "name": "Peeters", "firstName": "Marc", "inszNumber": "00000009007", "email": "marc.peeters@example.com", "dateOfBirth": "2000-01-01", "registrationOrganizer": { "id": "abc12345" }, "address": { "street": "Grote markt 12", "postalCode": "9300", "city": "Aalst", "country": "be" }, "optInPreferences": { "serviceMails": true, "infoMails": true, "milestoneMails": true, "sms": false, "post": true }, "nationality": "Belg", "legalTermsPaper": false, "legalTermsDigital": true, "parentalConsent": false, "registrationCardSystemId": 1 } } } } } }, "description": "Details of the new order to create." }, "tags": [ "Orders" ] } }, "/orders/{orderId}": { "get": { "summary": "Retrieve order", "operationId": "get-orders-orderid", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too Many Requests\n\nPossible error types:\n\n* https://api.publiq.be/probs/uitpas/rate-limited" } }, "description": "Retrieve order by ID.\n\nThe caller of this method, identified by client identification, client access token or user access token, must have ORDERS_READ permission.\n\nIn case this order is retrieved using client identification, `mainPassholder` and `extraPassholders` are left out of the response.\n\nThis endpoint is rate limited.", "tags": [ "Orders" ], "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] }, { "CUSTOM_TOKEN": [] } ] }, "parameters": [ { "schema": { "type": "string" }, "name": "orderId", "in": "path", "required": true, "description": "ID of the order" } ] }, "/passholders/status/insz-numbers/{inszNumber}": { "parameters": [ { "schema": { "type": "string" }, "name": "inszNumber", "in": "path", "required": true, "description": "the INSZ number to check" } ], "get": { "summary": "Retrieve the status of a passholder based on INSZ number", "operationId": "passholders-status-insz-numbers-insznumber", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "Status response", "properties": { "state": { "type": "string", "x-stoplight": { "id": "rqttsls3qw5rx" }, "enum": [ "USED", "UNUSED" ], "description": "State of the given INSZ number" } }, "required": [ "state" ] }, "examples": { "Example": { "value": { "state": "UNUSED" } } } } } }, "400": { "description": "Bad request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/invalid-insz-number\n\nThe detail property might include more information for the client developer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "description": "Too Many Requests\n\nPossible error types:\n\n* https://api.publiq.be/probs/uitpas/rate-limited\n\nThe detail property might include more information for the client developer.\n" } }, "description": "Retrieve the status of a passholder based on INSZ number.\n\nThis endpoint is rate limited.\n", "security": [ { "CLIENT_IDENTIFICATION": [] }, { "CLIENT_ACCESS_TOKEN": [] }, { "USER_ACCESS_TOKEN": [] } ], "parameters": [], "tags": [ "Passholders" ] } }, "/cards": { "get": { "summary": "Retrieve card status", "tags": [ "Cards" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" }, "examples": { "Active card": { "value": { "uitpasNumber": "0900000095902", "chipNumber": "042F51B2712380", "cardSystem": { "id": 1, "name": "UiTPAS Dender", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "9300", "name": "Aalst" }, { "postalCode": "9400", "name": "Ninove" } ], "permanent": true }, "cardType": "NFC_CARD", "status": "ACTIVE", "socialTariff": false } }, "Provisioned card": { "value": { "uitpasNumber": "0900000095902", "cardSystem": { "id": 1, "name": "UiTPAS Dender", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "9300", "name": "Aalst" }, { "postalCode": "9400", "name": "Ninove" } ], "permanent": true }, "cardType": "NFC_CARD", "status": "PROVISIONED", "socialTariff": false } } } } } }, "400": { "description": "Bad Request. Error type:\n\nhttps://api.publiq.be/probs/uitpas/invalid-uitpas-number", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get-cards", "description": "Retrieve card status for a given `uitpasNumber` or `chipNumber`.\n\nThe caller of this request must have `CARDS_READ` permission.", "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "uitpasNumber", "description": "The UiTPAS number of the card to search" }, { "schema": { "type": "string" }, "in": "query", "name": "chipNumber", "description": "The chip number of the card to search" } ] } }, "/cards/social-tariff/{cardSystemId}/active": { "get": { "summary": "Retrieve all valid social tariff cards", "tags": [ "Cards" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "description": "List of uitpas numbers", "items": { "x-stoplight": { "id": "btzarymlxotng" }, "type": "object", "properties": { "uitpasNumber": { "type": "string", "x-stoplight": { "id": "d5mcgwl29vxgc" }, "description": "uitpasNumber of the card", "readOnly": true }, "cardType": { "type": "string", "x-stoplight": { "id": "nflq0bksci1ny" }, "enum": [ "REGULAR", "GROUP" ], "description": "Type of the card", "readOnly": true }, "availableTickets": { "type": "integer", "x-stoplight": { "id": "rtlhxr5sy8tva" }, "description": "Available tickets. Only present for cards of type `GROUP`." } }, "required": [ "uitpasNumber", "cardType" ] } }, "examples": { "Full example": { "value": [ { "uitpasNumber": "0900000095902", "cardType": "REGULAR" }, { "uitpasNumber": "0900000067513", "cardType": "REGULAR" }, { "uitpasNumber": "0900000045410", "cardType": "GROUP", "availableTickets": 10 } ] }, "Delta Example": { "value": [ { "uitpasNumber": "0900000095902", "deltaOperation": "ADD", "cardType": "REGULAR" }, { "uitpasNumber": "0900000067513", "deltaOperation": "DELETE", "cardType": "REGULAR" }, { "uitpasNumber": "0900000045410", "cardType": "GROUP", "deltaOperation": "ADD", "availableTickets": 10 } ] } } } } }, "400": { "description": "Bad Request. Error type:\n\nhttps://api.publiq.be/probs/uitpas/invalid-uitpas-number", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "get-cards-social-tariff-cardSystemId-active", "description": "Retrieve all valid social tariff cards at this moment.\n\nThe response contains all current social tariff cards. Previously valid social tariff cards are omitted from the response. Please note that it is possible for a card to appear in this response, disappear some time later (e.g. temporarily blocked), and reappears again later (e.g. when unblocked).\n\nThe caller of this request must have `SOCIALTARIFF_EXPORT` permission.", "security": [ { "CLIENT_ACCESS_TOKEN": [] }, { "USER_ACCESS_TOKEN": [] } ], "parameters": [] }, "parameters": [ { "schema": { "type": "string" }, "name": "cardSystemId", "in": "path", "required": true, "description": "ID of the card system" } ] }, "/kiosks": { "get": { "summary": "Retrieve kiosks", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KiosksPaginatedCollection" }, "examples": { "Example 1": { "value": { "totalItems": 1, "member": [ { "id": "db385941-ece7-493d-8c4b-4320c4849646", "name": "CID-PPT-001", "deviceId": "ebee0a27-2dba-4231-aaae-15077884fa75", "organizers": [ { "id": "fd7e6177-4add-4fa8-a7fe-6e60127bfb35", "name": "CC De Schakel" } ], "cardSystem": { "id": 1, "name": "UiTPAS Dender", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "9300", "name": "Aalst" }, { "postalCode": "9400", "name": "Ninove" } ], "permanent": true }, "releaseTrack": "stable" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "get-kiosks", "description": "Retrieve active kiosk devices.\n\nThe caller of this request must have `KIOSKS_READ` permission or the caller must be an organizer admin user (any type) of the given organizer. In that case, `organizerId` is mandatory and must match the organizer of the admin user.", "security": [ { "CLIENT_ACCESS_TOKEN": [] }, { "USER_ACCESS_TOKEN": [] } ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "organizerId", "description": "Filter the kiosk results on this organizer" }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" } ], "tags": [ "Kiosks" ] }, "parameters": [] }, "/kiosks/{kioskId}/fixed-event": { "get": { "summary": "Retrieve fixed event of kiosk", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KioskDeviceEvent" }, "examples": {} } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found. Possible error types:\n\n* https://api.publiq.be/probs/url/not-found (in case kiosk is not found)\n* https://api.publiq.be/probs/uitpas/event-not-found (in case no event was configured)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get-kiosks-kioskId-fixed-event", "description": "Retrieve configured event of this kiosk.\n\nThis request returns `404 NOT FOUND` when no event is configured. In that case the kiosk will auto-detect its event.\n\nThe caller of this request must have `KIOSKS_READ` permission for the organizer of the kiosk or the caller must be an organizer admin user (any type) of the organizer of the kiosk.", "security": [ { "CLIENT_ACCESS_TOKEN": [] }, { "USER_ACCESS_TOKEN": [] } ], "parameters": [], "tags": [ "Kiosks" ] }, "parameters": [ { "schema": { "type": "string" }, "name": "kioskId", "in": "path", "required": true, "description": "The ID of the kiosk" } ], "put": { "summary": "Configure fixed event for kiosk", "operationId": "put-kiosks-kioskId-fixed-event", "responses": { "204": { "description": "Updated. No Content" }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data\n* https://api.publiq.be/probs/uitpas/event-not-found\n* https://api.publiq.be/probs/uitpas/event-not-acceptable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Kiosks" ], "description": "Configured event for this kiosk.\n\nThe caller of this request must have `KIOSKS_WRITE` permission for the organizer of the kiosk or the caller must be an organizer admin user (any type) of the organizer of the kiosk.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KioskDeviceEventRequest" } } }, "description": "Kiosk event request body" }, "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ] }, "delete": { "summary": "Remove fixed event for kiosk", "operationId": "delete-kiosks-kioskId-fixed-event", "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found. Possible error types:\n\n* https://api.publiq.be/probs/url/not-found (in case kiosk is not found)\n* https://api.publiq.be/probs/uitpas/event-not-found (in case no event was configured)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Remove the configured event for this kiosk.\n\nThe caller of this request must have `KIOSKS_WRITE` permission for the organizer of the kiosk or the caller must be an organizer admin user (any type) of the organizer of the kiosk.", "tags": [ "Kiosks" ], "security": [ { "USER_ACCESS_TOKEN": [] }, { "CLIENT_ACCESS_TOKEN": [] } ] } }, "/kiosk-devices/setup": { "parameters": [], "put": { "summary": "Setup new kiosk device", "operationId": "put-kiosks-setup", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KioskDevice" }, "examples": { "Example": { "value": { "id": "db385941-ece7-493d-8c4b-4320c4849646", "name": "CID-PPT-001", "deviceId": "ebee0a27-2dba-4231-aaae-15077884fa75", "organizers": [ { "id": "fd7e6177-4add-4fa8-a7fe-6e60127bfb35", "name": "CC De Schakel" } ], "cardSystem": { "id": 1, "name": "UiTPAS Dender", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "9300", "name": "Aalst" }, { "postalCode": "9400", "name": "Ninove" } ], "permanent": true }, "releaseTrack": "stable" } } } } } }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data\n* https://api.publiq.be/probs/uitpas/kiosk-not-found\n* https://api.publiq.be/probs/uitpas/kiosk-already-configured\n* https://api.publiq.be/probs/uitpas/kiosk-device-already-in-use", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "description": "Configure new kiosk device by looking it up by name and storing the provided device id. After this endpoint has been invoked, the other kiosk APIs can be used with the newly configured device id as `x-custom-token`.\n\nIn case no kiosk is found or the kiosk was already setup an error is returned:\n\n* https://api.publiq.be/probs/uitpas/kiosk-not-found\n* https://api.publiq.be/probs/uitpas/kiosk-already-configured\n\nThe **configuration code** of the device must be specicied in the `x-custom-token` header. This endpoint is rate limited to prevent abuse.\n\n\n\n> **This endpoint is exclusively for use by Kiosk devices themselves**. It cannot be used by other applications to manage the device.", "security": [ { "CUSTOM_TOKEN": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KioskDeviceSetup" }, "examples": { "Example": { "value": { "name": "CID-PPT-001", "deviceId": "ebee0a27-2dba-4231-aaae-15077884fa75" } } } } }, "description": "Kiosk Setup" }, "tags": [ "Kiosk devices" ] } }, "/kiosk-devices": { "get": { "summary": "Retrieve kiosk", "tags": [ "Kiosk devices" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KioskDevice" }, "examples": { "Example": { "value": { "id": "db385941-ece7-493d-8c4b-4320c4849646", "name": "CID-PPT-001", "deviceId": "ebee0a27-2dba-4231-aaae-15077884fa75", "organizers": [ { "id": "fd7e6177-4add-4fa8-a7fe-6e60127bfb35", "name": "CC De Schakel" } ], "cardSystem": { "id": 1, "name": "UiTPAS Dender", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "9300", "name": "Aalst" }, { "postalCode": "9400", "name": "Ninove" } ], "permanent": true }, "releaseTrack": "stable" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "get-kiosk-devices", "description": "Retrieve current kiosk.\n\nThe device id of the kiosk must be specicied in the `x-custom-token` header.\n\n\n\n> **This endpoint is exclusively for use by Kiosk devices themselves**. It cannot be used by other applications to manage the device.", "security": [ { "CUSTOM_TOKEN": [] } ] }, "parameters": [] }, "/kiosk-devices/events": { "get": { "summary": "Retrieve configured event", "tags": [ "Kiosk devices" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KioskDeviceEvent" }, "examples": { "Example": { "value": { "checkinPoints": 1, "event": { "id": "c7cf303a-8d92-4427-84e3-0cb508f7e4b6", "title": "Jeugdcentrum De Kouter" }, "checkinCode": "LGIWNWB" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get-kiosks-event", "description": "Retrieve the configured event of the kiosk.\n\nThis is a configuration endpoint, if you need to retrieve the **current** event, please use `GET /kiosk-devices/checkins`\n\nThe device id of the kiosk must be specicied in the `x-custom-token` header.\n\n\n\n> **This endpoint is exclusively for use by Kiosk devices themselves**. It cannot be used by other applications to manage the device.", "security": [ { "CUSTOM_TOKEN": [] } ] }, "parameters": [], "put": { "summary": "Configure event", "operationId": "put-kiosks-events", "responses": { "204": { "description": "Updated. No Content" }, "400": { "description": "Bad Request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data\n* https://api.publiq.be/probs/uitpas/event-not-found\n* https://api.publiq.be/probs/uitpas/event-not-acceptable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "description": "Update the current event of the kiosk.\n\nThe device id of the kiosk must be specicied in the `x-custom-token` header.\n\n\n\n> **This endpoint is exclusively for use by Kiosk devices themselves**. It cannot be used by other applications to manage the device.", "tags": [ "Kiosk devices" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KioskDeviceEventRequest" }, "examples": { "Example": { "value": { "id": "c7cf303a-8d92-4427-84e3-0cb508f7e4b6" } } } } }, "description": "Event" }, "security": [ { "CUSTOM_TOKEN": [] } ] }, "delete": { "summary": "Delete configured event", "operationId": "delete-kiosks-events", "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "description": "Delete configured event\n\nThe device id of the kiosk must be specicied in the `x-custom-token` header.\n\n\n\n> **This endpoint is exclusively for use by Kiosk devices themselves**. It cannot be used by other applications to manage the device.", "tags": [ "Kiosk devices" ], "security": [ { "CUSTOM_TOKEN": [] } ] } }, "/kiosk-devices/checkins": { "parameters": [], "post": { "summary": "Checkin passholder via kiosk", "operationId": "post-kiosks-checkin", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KioskDeviceCheckinResponse" }, "examples": { "Example": { "value": { "newPoints": 1, "totalPoints": 23 } } } } } }, "400": { "description": "Bad request. Possible error types:\n\n* https://api.publiq.be/probs/body/missing\n* https://api.publiq.be/probs/body/invalid-syntax\n* https://api.publiq.be/probs/body/invalid-data\n* https://api.publiq.be/probs/uitpas/card-blocked\n* https://api.publiq.be/probs/uitpas/checkin-not-allowed\n* https://api.publiq.be/probs/uitpas/event-not-found\n* https://api.publiq.be/probs/uitpas/passholder-not-found\n* https://api.publiq.be/probs/uitpas/maximum-reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Kiosk devices" ], "description": "Checkin a passholder with the given NFC chipnumber at the kiosk.\n\nThe device id of the kiosk must be specicied in the `x-custom-token` header.\n\n\n\n> **This endpoint is exclusively for use by Kiosk devices themselves**. It cannot be used by other applications to manage the device.", "security": [ { "CUSTOM_TOKEN": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KioskDeviceCheckinRequest" }, "examples": { "Example": { "value": { "chipNumber": "042F51B2712380" } } } } }, "description": "Kiosk checkin request" } }, "get": { "summary": "Retrieve the current checkin event", "operationId": "get-kiosks-checkins", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KioskDeviceEvent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Retrieve the current event of the kiosk. When returned, checkin on this kiosk and event is allowed.\n\nThe following logic is being used to determine the current checkin event:\n* is the event configured and is checkin currently allowed for that event? then use this event.\n* otherwise, the most suitable event is autodetected based on the organizers and locations of the kiosk.\n\nThe device id of the kiosk must be specicied in the `x-custom-token` header.\n\n\n\n> **This endpoint is exclusively for use by Kiosk devices themselves**. It cannot be used by other applications to manage the device.", "tags": [ "Kiosk devices" ], "security": [ { "CUSTOM_TOKEN": [] } ] } }, "/kiosk-devices/chip-numbers/{chipNumber}": { "parameters": [ { "schema": { "type": "string" }, "name": "chipNumber", "in": "path", "required": true, "description": "Hexadecimal notation of the chip number of an individual UiTPAS card." } ], "get": { "summary": "Retrieve total points of a passholder by chip number", "operationId": "get-kiosks-chip-numbers-chipNumber", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KioskPass" }, "examples": { "Example 1": { "value": { "totalPoints": 20 } } } } } }, "400": { "description": "Bad request. Possible error types:\n\n* https://api.publiq.be/probs/uitpas/card-blocked\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Retrieve total points of a passholder by chip number.\n\nThe device id of the kiosk must be specicied in the `x-custom-token` header.\n\n\n\n> **This endpoint is exclusively for use by Kiosk devices themselves**. It cannot be used by other applications to manage the device.", "tags": [ "Kiosk devices" ], "security": [ { "CUSTOM_TOKEN": [] } ] } } }, "components": { "schemas": { "Tariff": { "type": "object", "title": "Tariff", "description": "The Tariff describes the discounted price a passholder has to pay for a given ticket. ", "x-internal": false, "example": { "id": "SOCIALTARIFF-1", "name": "UiTPAS Kansentarief", "price": 1.5, "type": "SOCIALTARIFF" }, "x-tags": [ "Models" ], "properties": { "id": { "type": "string", "description": "ID of the tariff" }, "name": { "type": "string", "description": "Human-readable name of the tariff", "readOnly": true }, "price": { "type": "number", "description": "Discounted price to pay for this tariff, in euro.", "readOnly": true }, "type": { "type": "string", "enum": [ "SOCIALTARIFF", "COUPON" ], "description": "Type of discount being applied.", "readOnly": true } }, "required": [ "id" ] }, "MembershipPrice": { "type": "object", "title": "MembershipPrice", "description": "The MembershipPrice describes the price an UiTPAS membership in a specific cardsystem for a new or existing passholder. ", "x-internal": false, "example": { "price": 5, "label": "UiTPAS +18 jaar", "description": "Volwassenen die binnen de regio wonen, betalen 5 euro voor hun UiTPAS" }, "x-tags": [ "Models" ], "properties": { "price": { "description": "Price for the card system membership, in euro.", "type": "number" }, "label": { "type": "string", "x-stoplight": { "id": "pw5cjsq3l7ory" }, "description": "Label of the price that can be displayed to the end-user." }, "description": { "type": "string", "x-stoplight": { "id": "10d0zi5ldphwj" }, "description": "Description of the price that can be displayed to the end-user." } }, "required": [ "price", "label", "description" ] }, "TicketSale": { "description": "Model used both for registering new ticket sales and when searching for past ticket sales.\n\nThe `passholder` field is automatically included in responses if you have PASSHOLDERS_SEARCH permission. It is not required for ticket sale registrations.", "type": "object", "example": { "regularPrice": 10, "regularPriceLabel": "Volwassenen", "tariff": { "id": "COUPON1234" }, "eventId": "CBA2D826-9E85-47BD-8E0B-2BC7882E68FB", "uitpasNumber": "1234567890" }, "title": "TicketSale", "x-tags": [ "Models" ], "properties": { "id": { "type": "string", "description": "Unique id of a registered ticket sale. Not required for new ticket sale registrations", "readOnly": true }, "creationDate": { "type": "string", "x-stoplight": { "id": "jptbuymhglbl0" }, "format": "date-time", "description": "Creation date of the ticket sale. Always available in response.", "readOnly": true }, "regularPrice": { "type": "number", "description": "Regular price of the ticket before UiTPAS discounts" }, "regularPriceLabel": { "type": "string", "description": "Optional descriptive label of the regular price. Used in financial reporting" }, "tariffId": { "type": "string", "description": "Unique ID of the tariff that was paid for the ticket. (Deprecated, use `tariff.id` instead.)", "deprecated": true }, "tariff": { "$ref": "#/components/schemas/Tariff" }, "eventId": { "type": "string", "minLength": 1, "description": "Id of the event that the ticket sale was for" }, "eventTitle": { "type": "string", "x-stoplight": { "id": "werwwukp0fgy1" }, "description": "Title of the event that the ticket sale was for", "readOnly": true }, "uitpasNumber": { "type": "string", "minLength": 1, "description": "The passholder's UiTPAS number used to register this ticket sale. Note that the uitpasNumber of a passholder might change over time. This field will always contain the uitpasNumber used when registering the ticket sale. To identify the passholder, use the `passholder` field." }, "passholder": { "$ref": "#/components/schemas/Passholder" } }, "required": [ "regularPrice", "tariff", "eventId", "uitpasNumber" ] }, "Checkin": { "description": "Model used both for registering and searching checkins.\n\nThe `passholder` field is automatically included in responses if you have PASSHOLDERS_SEARCH permission. It is not required for check-in creation.", "type": "object", "title": "Checkin", "x-tags": [ "Models" ], "x-stoplight": { "id": "e0c828e2c92cb" }, "properties": { "id": { "type": "string", "description": "Unique id of the check-in. Not required for check-in creation.", "readOnly": true }, "creationDate": { "type": "string", "x-stoplight": { "id": "6pvyk6ulvstki" }, "description": "Creation date of the check-in. Always available in response.", "format": "date-time", "readOnly": true }, "eventId": { "type": "string", "minLength": 1, "description": "Id of the event where the passholder checked in" }, "eventTitle": { "type": "string", "x-stoplight": { "id": "wh57n4ld630j5" }, "description": "Title of the event where the passholder checked in", "readOnly": true }, "uitpasNumber": { "type": "string", "minLength": 1, "description": "The passholder's UiTPAS number used to create the check-in. Note that the uitpasNumber of a passholder might change over time. This field will always contain the uitpasNumber used when creating the check-in. To identify the passholder, use the `passholder` field." }, "points": { "type": "integer", "description": "Points earned by the passholder as a result of this check-in.", "readOnly": true }, "passholder": { "description": "Full passholder object of this check-in.", "allOf": [ { "$ref": "#/components/schemas/Passholder" } ], "readOnly": true } }, "required": [ "eventId", "uitpasNumber" ] }, "Error": { "title": "Error", "type": "object", "description": "RFC7807 error model for all publiq APIs.", "properties": { "type": { "type": "string", "description": "A URI reference that identifies the problem type. Can be used to recognize specific errors in your application code by comparing the complete URI." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem type (for developers)." }, "status": { "type": "integer", "description": "The HTTP status code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem (for developers). " }, "endUserMessage": { "type": "object", "description": "A human-readable explanation of the problem, specifically for end-users, in one or more languages. Typically available for domain errors, but not for errors caused by a technical issue in the integration (for example invalid JSON syntax in a request body). An `nl` value is always provided, other languages may be provided depending on the API and its intended audience. When this property is included, it is strongly encouraged to show this to the end-user.", "properties": { "nl": { "type": "string", "description": "A human-readable explanation of the problem, specifically for end-users, localized in Dutch." }, "fr": { "type": "string", "description": "A human-readable explanation of the problem, specifically for end-users, localized in French." }, "de": { "type": "string", "description": "A human-readable explanation of the problem, specifically for end-users, localized in German." }, "en": { "type": "string", "description": "A human-readable explanation of the problem, specifically for end-users, localized in English." } }, "required": [ "nl" ] }, "schemaErrors": { "type": "array", "description": "A list of one or more schema validation errors (usually used for error type https://api.publiq.be/probs/body/invalid-data).", "items": { "type": "object", "properties": { "jsonPointer": { "type": "string", "format": "json-pointer", "description": "RFC6901 compliant pointer that indicates what property/value was invalid." }, "error": { "type": "string", "description": "A human-readable (but often technical) reason why the property was invalid." } }, "required": [ "jsonPointer", "error" ] } } }, "required": [ "type", "title", "status" ], "x-internal": false }, "OrganizerPermissions": { "title": "OrganizerPermissions", "type": "object", "x-tags": [ "Models" ], "description": "Combination of organizer and its permissions", "properties": { "organizer": { "$ref": "#/components/schemas/Organizer" }, "permissions": { "type": "array", "description": "Permissions of the calling client for this organizer. This field is deprecated. Please use `permissionDetails`, which includes a user-readable label, instead.", "deprecated": true, "items": { "$ref": "#/components/schemas/Permission" } }, "permissionDetails": { "description": "Permissions of the calling client for this organizer.", "type": "array", "items": { "$ref": "#/components/schemas/PermissionDetail" } }, "linkedOrganizers": { "type": "array", "description": "Organizers linked to this organizer.", "items": { "$ref": "#/components/schemas/LinkedOrganizerPermissions" } } }, "required": [ "organizer" ] }, "LinkedOrganizerPermissions": { "title": "LinkedOrganizerPermissions", "type": "object", "x-tags": [ "Models" ], "properties": { "organizer": { "$ref": "#/components/schemas/Organizer" }, "permissionDetails": { "description": "Permissions of the calling client for this organizer.", "type": "array", "items": { "$ref": "#/components/schemas/PermissionDetail" } } }, "required": [ "organizer" ], "description": "Combination of organizer and its permissions, specifically targetted to be used when linked to another organizer." }, "Permission": { "title": "Permission", "type": "string", "x-tags": [ "Models" ], "enum": [ "TARIFFS_READ", "TICKETSALES_SEARCH", "TICKETSALES_REGISTER", "EVENTS_UPDATE", "EVENTS_READ", "EVENT_SETTINGS_READ", "EVENT_SETTINGS_UPDATE", "EVENTS_QR_CHECKINCODE", "CHECKINS_READ", "CHECKINS_WRITE", "ORGANIZERS_SEARCH", "ORGANIZERS_REPORTS", "ORGANIZERS_ADMINS_READ", "ORGANIZERS_ADMINS_WRITE", "PASSHOLDERS_PICTURE_READ", "PASSHOLDERS_PICTURE_WRITE", "PASSHOLDERS_SEARCH", "PASSHOLDERS_SEARCH_ALL", "PASSHOLDERS_SEARCH_BY_ID", "GROUPPASSES_SEARCH", "PASSHOLDERS_WRITE", "PASSHOLDERS_WRITE_SOCIALTARIFF_FULL_CARDSYSTEM", "PASSHOLDERS_WRITE_FOREIGN_COUNTRY", "PASSHOLDERS_WRITE_SOCIALTARIFF", "PASSHOLDERS_UPDATE", "PASSHOLDERS_DELETE", "PASSHOLDER_COUPONS_READ", "GROUPPASS_COUPONS_READ", "MEMBERSHIP_PRICES_READ", "PASSES_READ", "PASSES_INSZNUMBERS_READ", "PASSES_CHIPNUMBERS_READ", "REWARDS_WRITE", "REWARDS_READ", "REWARDS_REDEEM", "REWARDS_PASSHOLDERS_READ", "PASSHOLDERS_SELF_REGISTRATION", "PASSHOLDERS_SELF_CHECKIN", "PASSHOLDERS_SELF_READ", "PASSHOLDERS_REGISTER_UITID", "PASSHOLDERS_TRANSACTION_HISTORY", "PASSHOLDERS_FAMILY_MEMBERS", "ORDERS_READ", "ORDERS_CREATE", "PERMISSIONS_READ", "PERMISSIONS_WRITE", "CARDS_READ", "ASSOCIATIONS", "SOCIALTARIFF_EXPORT", "KIOSKS_READ", "KIOSKS_WRITE" ], "description": "ID of the permission" }, "PermissionDetail": { "type": "object", "title": "PermissionDetail", "description": "Permission details", "properties": { "id": { "$ref": "#/components/schemas/Permission" }, "label": { "type": "object", "description": "Human-readable label of the permission", "properties": { "nl": { "type": "string", "description": "Human-readable label of the permission in Dutch" }, "en": { "type": "string", "description": "Human-readable label of the permission in English" } }, "required": [ "nl" ] }, "cardSystemIds": { "type": "array", "description": "IDs of the card systems to which this permission applies", "items": { "type": "integer", "readOnly": true } } }, "required": [ "id" ] }, "Organizer": { "title": "Organizer", "type": "object", "description": "An organisation that partners with UiTPAS to provide discounts and/or rewards, and/or allows points to be collected at their events.", "x-tags": [ "Models" ], "properties": { "id": { "type": "string", "description": "Unique ID of an UiTPAS organizer. (Same as its ID in UiTdatabank)" }, "name": { "type": "string", "description": "Human-readable name of an UiTPAS organizer." }, "cardSystems": { "type": "array", "description": "Card systems linked to this organizer", "items": { "$ref": "#/components/schemas/CardSystem" } } }, "required": [ "id" ] }, "OrganizerAdmin": { "title": "OrganizerAdmin", "x-stoplight": { "id": "6or68aa5gscq9" }, "type": "object", "description": "An admin user for an organizer.", "x-tags": [ "Models" ], "properties": { "userId": { "type": "string", "description": "UiTiD user ID of this organizer admin. This field is always available in responses.", "x-stoplight": { "id": "xrz0hu56plasy" } }, "email": { "type": "string", "x-stoplight": { "id": "as12vt0gw8i9i" }, "description": "Email of the organizer admin. " }, "type": { "type": "string", "x-stoplight": { "id": "a804wfrysxttx" }, "description": "Type of the organizer admin.", "enum": [ "MEMBER", "ADMIN" ] } }, "required": [ "email", "type" ] }, "PassholdersPaginatedResponse": { "title": "PassholdersPaginatedResponse", "type": "object", "x-tags": [ "Models" ], "description": "Paginated response object for passholders", "properties": { "totalItems": { "type": "integer", "description": "Total amount of passholder results (can be more than the amount of results in the response)." }, "member": { "type": "array", "description": "List of passholder results for this specific (paginated) request.", "items": { "$ref": "#/components/schemas/Passholder" } } } }, "GrouppassesPaginatedResponse": { "title": "GrouppassesPaginatedResponse", "x-stoplight": { "id": "jd1p42sik46m7" }, "type": "object", "x-tags": [ "Models" ], "description": "Paginated response object for grouppasses", "properties": { "totalItems": { "type": "integer", "description": "Total amount of passholder results (can be more than the amount of results in the response)." }, "member": { "type": "array", "description": "List of passholder results for this specific (paginated) request.", "items": { "$ref": "#/components/schemas/Grouppass" } } } }, "RewardsPaginatedResponse": { "title": "RewardsPaginatedResponse", "type": "object", "x-tags": [ "Models" ], "description": "Paginated response object for rewards", "properties": { "totalItems": { "type": "integer", "description": "Total number of reward results (can be more than the amount of results in the response)." }, "member": { "type": "array", "description": "List of reward results for this specific (paginated) request.", "items": { "$ref": "#/components/schemas/Reward" } }, "facet": { "type": "object", "description": "Facet information for the requested facets.", "properties": { "categories": { "$ref": "#/components/schemas/Facet" }, "owningCardSystemId": { "$ref": "#/components/schemas/Facet" }, "type": { "$ref": "#/components/schemas/Facet" }, "sport": { "$ref": "#/components/schemas/Facet" }, "forKids": { "$ref": "#/components/schemas/Facet" }, "online": { "$ref": "#/components/schemas/Facet" }, "lastChance": { "$ref": "#/components/schemas/Facet" } } } } }, "RedeemedRewardsPaginatedResponse": { "title": "RewardsPaginatedResponse", "type": "object", "x-tags": [ "Models" ], "description": "Paginated response object for rewards", "properties": { "totalItems": { "type": "integer", "description": "Total number of redeemed reward results (can be more than the amount of results in the response)." }, "member": { "type": "array", "description": "List of redeemed reward results for this specific (paginated) request.", "items": { "$ref": "#/components/schemas/RedeemedReward" } } } }, "OrganizersPaginatedResponse": { "title": "OrganizersPaginatedResponse", "type": "object", "x-tags": [ "Models" ], "description": "Paginated response object for organizers", "properties": { "totalItems": { "type": "integer", "description": "Total number of organizer results (can be more than the amount of results in the response)." }, "member": { "type": "array", "description": "List of organizer results for this specific (paginated) request.", "items": { "$ref": "#/components/schemas/Organizer" } } } }, "OrganizerAdminsPaginatedCollection": { "title": "OrganizerAdminsPaginatedCollection", "x-stoplight": { "id": "ixcgvbnnh23z2" }, "type": "object", "x-tags": [ "Models" ], "description": "Paginated response object for organizer admins.", "properties": { "totalItems": { "type": "integer", "description": "Total number of organizer results (can be more than the amount of results in the response)." }, "member": { "type": "array", "description": "List of organizer results for this specific (paginated) request.", "items": { "$ref": "#/components/schemas/OrganizerAdmin" } } } }, "KiosksPaginatedCollection": { "title": "KiosksPaginatedCollection", "type": "object", "x-tags": [ "Models" ], "description": "Paginated response object for kiosks.", "properties": { "totalItems": { "type": "integer", "description": "Total number of kiosk results (can be more than the amount of results in the response)." }, "member": { "type": "array", "description": "List of kiosk results for this specific (paginated) request.", "items": { "$ref": "#/components/schemas/KioskDevice" } } } }, "AssociationsPaginatedResponse": { "title": "AssociationsPaginatedResponse", "x-stoplight": { "id": "ytc6u5zzkcfmv" }, "type": "object", "x-tags": [ "Models" ], "description": "Paginated response object for associations", "properties": { "totalItems": { "type": "integer", "description": "Total number of association results (can be more than the amount of results in the response)." }, "member": { "type": "array", "description": "List of association results for this specific (paginated) request.", "items": { "$ref": "#/components/schemas/Association" } } } }, "CheckinsPaginatedCollection": { "title": "CheckinsPaginatedCollection", "x-stoplight": { "id": "bczavdoj5gjvq" }, "type": "object", "x-tags": [ "Models" ], "description": "Paginated collection object for checkins", "properties": { "totalItems": { "type": "integer", "description": "Total number of checkin results" }, "member": { "type": "array", "description": "List of checkin results for this specific (paginated) request.", "items": { "$ref": "#/components/schemas/Checkin" } } } }, "TicketSalesPaginatedResponse": { "title": "TicketSalesPaginatedResponse", "type": "object", "x-tags": [ "Models" ], "description": "Paginated response object for ticket sales", "properties": { "totalItems": { "type": "integer", "description": "Total number of ticket sale results (can be more than the amount of results in the response)." }, "member": { "type": "array", "description": "List of ticket sale results for this specific (paginated) request.", "items": { "$ref": "#/components/schemas/TicketSale" } } } }, "Passholder": { "title": "Passholder", "type": "object", "x-tags": [ "Models" ], "description": "Person who holds an UiTPAS, the end-user of an UiTPAS. \n\nA `Passholder` can be identified by its `id`. However, there are cases where the passholder identifies using one of its UiTPAS numbers. That number is CardSystem specific, so it can be found under `cardSystemMemberships`. Every passholder should have at least one cardsystem membership.", "x-examples": {}, "properties": { "id": { "type": "string", "description": "This field is always available in responses and ignored in create and update operations.", "readOnly": true }, "name": { "type": "string", "description": "Last name of the passholder." }, "firstName": { "type": "string", "description": "First name of the passholder." }, "inszNumber": { "type": "string", "description": "Unique national (Belgian) INSZ number of an individual passholder to look up." }, "uitpasNumber": { "type": "string", "description": "The UiTPAS number of this passholder. This field contains the UiTPAS number of the oldest, still active cardsystem membership, that has an active card. This field is always available in responses and ignored in create and update operations." }, "cardSystemMemberships": { "type": "array", "description": "This field is always available in responses and ignored in create and update operations.", "items": { "$ref": "#/components/schemas/CardSystemMembership" }, "readOnly": true }, "email": { "type": "string", "description": "Contact email address of the passholder. Not present for every passholder. Multiple passholders can have the same email address." }, "creationDate": { "type": "string", "format": "date-time", "description": "This field is always available in responses and ignored in create and update operations.", "readOnly": true }, "dateOfBirth": { "type": "string", "format": "date", "description": "Date that the passholder was born." }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE", "X" ], "description": "Gender of the passholder." }, "registrationOrganizer": { "$ref": "#/components/schemas/Organizer" }, "points": { "type": "integer", "description": "Amount of points the passholder has currently saved (and not used).This field is always available in responses and ignored in create and update operations.", "readOnly": true }, "uitidStatus": { "type": "string", "enum": [ "REGISTERED", "UNREGISTERED" ], "description": "Whether or not the passholder has a an UiTiD registered. This field is always available in responses and ignored in create and update operations.", "readOnly": true }, "address": { "type": "object", "description": "Address that the passholder lives at. Always present in responses. Passholders living outside of Belgium (usually near the border) will only have a `postalCode` and `city` in their address.", "required": [ "postalCode", "city" ], "properties": { "street": { "type": "string", "description": "Street name, number and optional box number of the address." }, "number": { "type": "string", "description": "House number. This field is deprecated and will be empty. The house number is part of the `street` property.", "deprecated": true }, "box": { "type": "string", "description": "Postal box number. This field is deprecated and will be empty. The box number is part of the `street` property.", "deprecated": true }, "postalCode": { "type": "string", "description": "Postal code of the municipality." }, "city": { "type": "string", "description": "Human-readable name of the municipality." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code." } } }, "postalCode": { "type": "string", "deprecated": true, "description": "Postal code of the municipality that the passholder lives in. Deprecated in favor of `address.postalCode`", "readOnly": true }, "city": { "type": "string", "deprecated": true, "description": "Name of the municipality that the passholder lives in. Deprecated in favor of `address.city`.", "readOnly": true }, "phoneNumber": { "type": "string", "description": "Phone number that the passholder has registered, for example for SMS alerts." }, "optInPreferences": { "type": "object", "description": "Permissions that the passholder has given to be contacted.", "properties": { "serviceMails": { "type": "boolean", "description": "Important information about the functionality of UiTPAS." }, "milestoneMails": { "type": "boolean", "description": "Notification when you reach an important UiTPAS milestone, for example a specific amount of points or an exclusive reward becomes available to you." }, "infoMails": { "type": "boolean", "description": "Rewards, actions and events selected specifically for the passholder based on their UiTPAS history." }, "sms": { "type": "boolean", "description": "Free (sporadic) SMS messages with rewards, actions and events selected specifically for the passholder based on their UiTPAS history." }, "post": { "type": "boolean", "description": "Sporadic post mail with information about UiTPAS. Will be sent to the passholder's postal address." } }, "required": [ "serviceMails", "milestoneMails", "infoMails", "sms", "post" ] }, "nationality": { "type": "string", "description": "Human-readable name of the passholder's nationality." }, "parentalConsent": { "type": "boolean", "description": "Only used in passholder creation and updates. Set to true for under-aged passholder that have parental consent.", "writeOnly": true }, "legalTermsPaper": { "type": "boolean", "description": "Only used in passholder creation and updates. Set to true for passholders that received legal terms on paper.", "writeOnly": true }, "legalTermsDigital": { "type": "boolean", "description": "Only used in passholder creation and updates. Set to true for passholders that received legal terms digitally.", "writeOnly": true }, "registrationCardSystemId": { "type": "integer", "description": "Only used in passholder creation. Set to the id of the card system of which the passholder has to become a member.", "writeOnly": true }, "registrationVoucher": { "type": "string", "description": "Only used in passholder creation when the ser has a price reduction voucher.", "writeOnly": true }, "registrationCardType": { "type": "string", "description": "Only used and mandatory in passholder c", "enum": [ "DIGITAL", "NFC_CARD" ], "writeOnly": true }, "registrationUitpasNumber": { "type": "string", "description": "Only used in passholder creation using a physical card.", "writeOnly": true }, "registrationSocialTariffEndDate": { "type": "string", "description": "Only used in passholder creation using a `registrationUitpasNumber` with social tariff. Or when updating a passholder with social tariff. During registration, if no `registrationSocialTariffEndDate` is specified and `registrationUitpasNumber` has social tariff, a default date of April 30 of next year is used.", "format": "date", "writeOnly": true } }, "required": [ "name", "firstName", "dateOfBirth", "address" ] }, "PassholderRegistration": { "title": "PassholderRegistration", "type": "object", "x-tags": [ "Models" ], "description": "Registration request of a passholder, mainly used in the online order flow.\n\nA `PassholderRegistration` is not yet `Passholder` but one can be created (e.g. when the order is paid) using the information from the `PassholderRegistration`.", "x-examples": {}, "properties": { "id": { "type": "string", "description": "ID of the PassholderRegistation. **Note:** This is not same as the later `Passholder` id. This field is always available in responses.", "readOnly": true }, "name": { "type": "string", "description": "Last name of the passholder to register." }, "firstName": { "type": "string", "description": "First name of the passholder to register." }, "inszNumber": { "type": "string", "description": "Unique national (Belgian) INSZ number of an individual passholder." }, "email": { "type": "string", "description": "Contact email address of the passholder to register" }, "creationDate": { "type": "string", "format": "date-time", "description": "This field is always available in responses.", "readOnly": true }, "dateOfBirth": { "type": "string", "format": "date", "description": "Date that the passholder to register was born." }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE", "X" ], "description": "Gender of the passholder to register." }, "registrationOrganizer": { "$ref": "#/components/schemas/Organizer" }, "address": { "type": "object", "description": "Address that the passholder to register lives at. Always present in responses. Passholders living outside of Belgium (usually near the border) will only have a `postalCode` and `city` in their address.", "required": [ "postalCode", "city" ], "properties": { "street": { "type": "string", "description": "Street name, number and optional box number of the address." }, "number": { "type": "string", "description": "House number. This field is deprecated and will be empty. The house number is part of the `street` property.", "deprecated": true }, "box": { "type": "string", "description": "Postal box number. This field is deprecated and will be empty. The box number is part of the `street` property.", "deprecated": true }, "postalCode": { "type": "string", "description": "Postal code of the municipality." }, "city": { "type": "string", "description": "Human-readable name of the municipality." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code." } } }, "phoneNumber": { "type": "string", "description": "Phone number of the passholder to register, for example for SMS alerts." }, "optInPreferences": { "type": "object", "description": "Permissions that the passholder has given to be contacted.", "properties": { "serviceMails": { "type": "boolean", "description": "Important information about the functionality of UiTPAS." }, "milestoneMails": { "type": "boolean", "description": "Notification when you reach an important UiTPAS milestone, for example a specific amount of points or an exclusive reward becomes available to you." }, "infoMails": { "type": "boolean", "description": "Rewards, actions and events selected specifically for the passholder based on their UiTPAS history." }, "sms": { "type": "boolean", "description": "Free (sporadic) SMS messages with rewards, actions and events selected specifically for the passholder based on their UiTPAS history." }, "post": { "type": "boolean", "description": "Sporadic post mail with information about UiTPAS. Will be sent to the passholder's postal address." } }, "required": [ "serviceMails", "milestoneMails", "infoMails", "sms", "post" ] }, "parentalConsent": { "type": "boolean", "description": "Set to true for under-aged passholder that have parental consent." }, "legalTermsPaper": { "type": "boolean", "description": "Set to true for passholders that received legal terms on paper." }, "legalTermsDigital": { "type": "boolean", "description": "Set to true for passholders that received legal terms digitally." }, "registrationCardSystemId": { "type": "integer", "description": "Set to the id of the card system of which the passholder has to become a member." }, "registrationVoucher": { "type": "string", "description": "Price reduction voucher." }, "registrationSocialTariff": { "type": "object", "description": "Optional request for social tariff", "properties": { "requested": { "type": "boolean", "description": "`true` if social tariff is requested for this registration. Always available in responses if `registrationSocialTariff` exists.", "readOnly": true }, "idToken": { "type": "string", "description": "The Social Tariff Validation ID token of the user. Use the [social tariff validation flow](/reference/uitpas.json/paths/~1social-tariff-validation~1start/get) to obtain such ID tokens. If specified, this token must be valid, contain `hasSocialTariff:true` and the identity fields must match the fields in this registration. In all other cases an error is returned.", "writeOnly": true } } } }, "required": [ "name", "firstName", "dateOfBirth", "registrationOrganizer", "address" ] }, "Grouppass": { "title": "Grouppass", "x-stoplight": { "id": "upy28l7gpkmzw" }, "type": "object", "x-tags": [ "Models" ], "description": "Grouppass is a special kind of UiTPAS concept: it has an `uitpasNumber` like regular passholders, but it can only participate in ticket sale flows (either social tariff or using coupons). \n\nThe social tariff for grouppasses is a little bit different from regular passholders, because a grouppass is entitled to buy a certain amount of `totalTicketsPerYear`, of which the remaining amount is indicated by `availableTickets`.\n\nA grouppass cannot check-in at events, or redeem rewards.\n\nA `Grouppass` can be identified by its `id`. However, there are cases where the grouppass is identified using its UiTPAS number. Every grouppass has one (and only one) uitpas number.", "x-examples": { "Example": { "id": "b5a5bb75-6cae-452b-b029-d12d3b425b1b", "name": "Test groep", "uitpasNumber": "0900000045410", "email": "testgrouppass@example.com", "creationDate": "2019-08-24T14:15:22+00:00", "socialTariff": { "status": "ACTIVE", "endDate": "2024-12-31T01:00:00+00:00", "totalTicketsPerYear": 20, "availableTickets": 9 }, "cardSystem": { "id": 1, "name": "UiTPAS Dender", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "9300", "name": "Aalst" }, { "postalCode": "9400", "name": "Ninove" } ], "permanent": true }, "address": { "postalCode": "9300", "city": "Aalst", "country": "be" }, "telephone": "012/456789" } }, "properties": { "id": { "type": "string", "description": "This field is always available in responses.", "readOnly": true }, "name": { "type": "string", "description": "Name of the grouppass." }, "uitpasNumber": { "type": "string", "description": "The UiTPAS number of this grouppass. This field is always available in responses." }, "cardStatus": { "type": "string", "x-stoplight": { "id": "nnzfui82in9z5" }, "description": "Status of the card linked to this grouppass.", "enum": [ "PROVISIONED", "LOCAL_STOCK", "ACTIVE", "BLOCKED", "DELETED" ] }, "email": { "type": "string", "description": "Contact email address of the grouppass." }, "creationDate": { "type": "string", "format": "date-time", "description": "This field is always available in responses.", "readOnly": true }, "socialTariff": { "type": "object", "x-stoplight": { "id": "59mykno6i5b0b" }, "description": "Social tariff of the grouppass (if applicable)", "properties": { "status": { "type": "string", "x-stoplight": { "id": "f035pqngnrdtf" }, "enum": [ "ACTIVE", "EXPIRED" ], "description": "Status of the social tariff:\n- `ACTIVE`: the grouppass is entitled to social tariff\n- `EXPIRED`: the grouppass is NOT entitled to social tariff anymore\n" }, "endDate": { "type": "string", "x-stoplight": { "id": "mtikoui6mpcn5" }, "description": "Exact moment the grouppass's right to a social tariff expires.", "format": "date-time" }, "totalTicketsPerYear": { "type": "integer", "x-stoplight": { "id": "93mtfqrw53djc" }, "description": "Total number of tickets this grouppass can buy per year." }, "availableTickets": { "type": "integer", "x-stoplight": { "id": "qytz7wdi7sqg4" }, "description": "Number of available ticketsales" } }, "required": [ "status" ] }, "cardSystem": { "$ref": "#/components/schemas/CardSystem" }, "address": { "type": "object", "description": "Address of the grouppass. Always present in responses.", "required": [ "postalCode", "city" ], "properties": { "street": { "type": "string", "description": "Full street name, number and box of the grouppass" }, "postalCode": { "type": "string", "description": "Postal code of the municipality." }, "city": { "type": "string", "description": "Human-readable name of the municipality." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code." } } }, "telephone": { "type": "string", "x-stoplight": { "id": "46g76ybvflcsd" }, "description": "Telephone contact number of this grouppass" } }, "required": [ "name", "cardStatus", "cardSystem", "address" ] }, "PassholderSelfRegistration": { "title": "PassholderSelfRegistration", "type": "object", "example": { "name": "Lastname", "firstName": "Firstname", "cardSystem": { "id": 27 }, "email": "firstname.lastname@example.com", "dateOfBirth": "1980-01-01", "postalCode": "9000", "city": "Gent", "registrationOrganizer": { "id": "d2f898b1-455e-44ee-b08a-c4c05b1ab900" } }, "properties": { "name": { "type": "string", "description": "Last name of the new passholder." }, "firstName": { "type": "string", "description": "First name of the new passholder." }, "dateOfBirth": { "type": "string", "format": "date", "description": "Date that the new passholder was born." }, "email": { "type": "string", "description": "Email address of the new passholder. Must be unique." }, "postalCode": { "type": "string", "description": "Postal code of the Belgian municipality that the new passholder lives in." }, "city": { "type": "string", "description": "Human-readable name of the Belgian municipality that the new passholder lives in." }, "cardSystem": { "$ref": "#/components/schemas/CardSystem" }, "registrationOrganizer": { "$ref": "#/components/schemas/Organizer" } }, "required": [ "name", "firstName", "dateOfBirth", "postalCode", "city", "cardSystem", "registrationOrganizer" ], "x-tags": [ "Models" ] }, "Pass": { "type": "object", "title": "Pass", "x-tags": [ "Models" ], "description": "The `Pass` entity includes basic information about the UiTPAS and its related `Passholder`. ", "example": { "passholderId": "b34c19fc-bcf9-4d10-aeb2-6bc9efd38b68", "uitpasNumber": "0560002524314", "passType": "INDIVIDUAL", "firstName": "Jan", "points": 12, "postalCode": "1000", "socialTariff": { "status": "EXPIRED", "endDate": "2022-12-31T22:59:59" }, "messages": [ { "level": "WARN", "text": "Je sociaal tarief is verlopen. Contacteer je UiTPAS balie." } ] }, "properties": { "passholderId": { "type": "string", "description": "ID of the passholder associated with this pass", "readOnly": true }, "passType": { "type": "string", "x-stoplight": { "id": "5l6ksrclyqezu" }, "description": "Indicates whether this pass belongs to an individual passholder or a group (Grouppas)", "enum": [ "INDIVIDUAL", "GROUP" ], "readOnly": true }, "uitpasNumber": { "type": "string", "description": "UiTPAS number of this pass", "readOnly": true }, "firstName": { "type": "string", "description": "First name of the passholder." }, "points": { "type": "integer", "description": "Number of points of the passholder of this pass", "readOnly": true }, "postalCode": { "type": "string", "description": "Postal code of the passholder of this pass", "readOnly": true }, "socialTariff": { "type": "object", "description": "Information about the possible social tariff of the passholder. This object is always present, however a passholder is only entitled to social tariff if the `status` property has value `ACTIVE`.", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ACTIVE", "EXPIRED", "NONE" ], "description": "Status of the social tariff:\n- `ACTIVE`: the passholder is entitled to social tariff\n- `EXPIRED`: the passholder is NOT entitled to social tariff anymore\n- `NONE`: the passholder is NOT entitled to social tariff" }, "endDate": { "type": "string", "format": "date-time", "description": "Exact expiration date of the passholder's entitlement to a social tariff. This property must not be used to determine the social tariff status, because `status` can be `ACTIVE` while the `endDate` is in the past during a 'grace period'. This property is not available when status is `NONE`.", "readOnly": true } } }, "messages": { "type": "array", "description": "Message that, if present, must be displayed to the user", "items": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "INFO", "WARN", "ERROR" ], "description": "Severity level of the message", "readOnly": true }, "text": { "type": "string", "description": "Actual text of the message to be displayed to the user" } }, "required": [ "level", "text" ] }, "readOnly": true } }, "required": [ "passholderId", "passType", "uitpasNumber", "firstName", "points", "postalCode", "socialTariff" ], "readOnly": true }, "FamilyMember": { "type": "object", "title": "FamilyMember", "x-tags": [ "Models" ], "description": "The `FamilyMember` entity including basic information about the `Passholder` family member.", "x-stoplight": { "id": "2e1288b442b2a" }, "properties": { "uitpasNumber": { "type": "string", "x-stoplight": { "id": "vffgzwi7q0jmc" }, "description": "UiTPAS number of the family member passholder. This field is always available in responses, mandatory in POST requests and ignored in PUT requests." }, "passholder": { "x-stoplight": { "id": "hx6tv58az4pq2" }, "allOf": [ { "$ref": "#/components/schemas/Passholder" } ], "readOnly": true }, "creationDate": { "type": "string", "format": "date-time", "description": "Creationdate of the family member in its family. This field is always available in responses.", "readOnly": true }, "icon": { "type": "string", "description": "Icon of the family member" }, "mainFamilyMember": { "type": "boolean", "description": "Indicates whether this is the main family member (= the passholder that created this list of family members)", "readOnly": true } } }, "CardSystemMembership": { "title": "CardSystemMembership", "description": "Membership info of an individual passholder in a specific card system.", "type": "object", "x-tags": [ "Models" ], "properties": { "cardSystem": { "$ref": "#/components/schemas/CardSystem" }, "uitpasNumber": { "type": "string", "description": "This is a convenience propery that contains the uitpasNumber of the `currentCard` if there is a current card and that card is `ACTIVE`." }, "currentCard": { "$ref": "#/components/schemas/CardSystemMembershipCard" }, "status": { "type": "string", "enum": [ "ACTIVE", "BLOCKED" ], "description": "Whether the membership is active or blocked.", "readOnly": true }, "socialTariff": { "type": "object", "description": "If the passholder has (or had) right to a social tariff, this object contains details like the end date. Check the `status` of the `socialTariff`: the passholder is only currently entitled to a social tariff is `status` is `ACTIVE`. ", "properties": { "status": { "type": "string", "enum": [ "ACTIVE", "EXPIRED", "SUSPENDED" ], "description": "Status of the social tariff:\n- `ACTIVE`: the passholder is entitled to social tariff\n- `EXPIRED`: the passholder is NOT entitled to social tariff anymore\n- `SUSPENDED`: the passholder is temporarily NOT entitled to social tariff. In this case a extra property `suspendedUntilDate` will also be available." }, "endDate": { "type": "string", "format": "date-time", "description": "Exact moment the passholder's right to a social tariff expires." }, "inGracePeriod": { "type": "boolean", "description": "When the end date of the right to a social tariff has passed, the passholder may still be in a grace period that they can buy tickets at a social tariff until their right to a social tariff has been renewed." }, "suspendedUntilDate": { "type": "string", "format": "date-time", "description": "Date until this social tarif is suspended (only available when status is `SUSPENDED`)" }, "expired": { "type": "boolean", "description": "If true, the passholder's right to a social tariff has completely expired (the end date has passed and the passholder is no longer in a grace period). **This property is deprecated.** Please use the `status` property instead.", "deprecated": true } }, "required": [ "status", "endDate" ] } }, "required": [ "cardSystem" ] }, "CardSystemMembershipCard": { "title": "CardSystemMembershipCard", "x-stoplight": { "id": "c61r94oays9ih" }, "type": "object", "description": "Representation of an UiTPAS card embedded in a CardSystemMembership.", "properties": { "uitpasNumber": { "type": "string", "x-stoplight": { "id": "wt5795os9zlly" }, "description": "UiTPAS number of this card." }, "cardType": { "type": "string", "x-stoplight": { "id": "0wg00e7ok83tp" }, "enum": [ "NFC_CARD", "DIGITAL" ], "description": "Type of this card." }, "status": { "type": "string", "x-stoplight": { "id": "ic0htdaaq5wmr" }, "description": "Status of this card.", "enum": [ "ACTIVE", "BLOCKED", "DELETED" ] } }, "required": [ "uitpasNumber", "status" ] }, "CardSystem": { "title": "CardSystem", "description": "A region, usually one or multiple municipalities in Belgium, that uses UiTPAS and provides discounts and/or rewards. For example \"Paspartoe\" (Brussels), UiTPAS Leuven, UiTPAS Hasselt, UiTPAS Gent, and so on.", "type": "object", "x-tags": [ "Models" ], "example": { "id": 1, "name": "UiTPAS Dender", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "9300", "name": "Aalst" }, { "postalCode": "9400", "name": "Ninove" } ], "permanent": true }, "properties": { "id": { "type": "integer", "description": "ID of the card system" }, "name": { "type": "string", "description": "Name of the card system. This field is always available in responses." }, "branding": { "type": "object", "description": "Branding information of the card system", "properties": { "logo": { "type": "string", "description": "URL to the logo of the card system" }, "primaryColor": { "type": "string", "description": "Color code of the primary branding color." }, "secondaryColor": { "type": "string", "description": "Color code of the secondary branding color." } } }, "links": { "type": "object", "description": "Links of the card system", "properties": { "website": { "type": "string", "description": "URL of the website of the card system" } } }, "cities": { "type": "array", "description": "List of cities that are part of this card system", "items": { "$ref": "#/components/schemas/City" } }, "permanent": { "type": "boolean", "description": "Indicates whether this is a permanent card system" }, "allowsCardlessRegistration": { "type": "boolean", "description": "Indicates if cardless registration is enabled" }, "cardlessRegistrationType": { "type": "string", "description": "Indicates the types of online cardless registrations this cardsystem supports.", "enum": [ "ALL", "REGULAR", "SOCIALTARIFF", "NONE" ] }, "socialTariffInfo": { "type": "string", "description": "Optional information about social tariff entitlement in this card system." } }, "required": [ "id" ] }, "Report": { "type": "object", "title": "Report", "description": "The status of a report export.", "x-tags": [ "Models" ], "properties": { "status": { "type": "string", "enum": [ "STARTED", "AVAILABLE", "FAILED" ], "description": "Whether the report has started (but not ready yet), is available for download, or failed to be created." }, "id": { "type": "integer", "description": "Unique ID of the report export. Can be used to retrieve the status of the export." }, "message": { "type": "string", "description": "Included if `status` is `FAILED`. Describes why it was not possible to export the report." }, "period": { "$ref": "#/components/schemas/ReportPeriod" }, "creationDate": { "type": "string", "format": "date-time", "description": "Date that the report export was initially requested." } }, "required": [ "status", "id", "creationDate" ] }, "ReportPeriod": { "title": "ReportPeriod", "type": "object", "description": "Date range for which to export a list of financial transactions.", "properties": { "startDate": { "type": "string", "format": "date", "description": "Minimum date of all transactions to include in the report. (Inclusive)" }, "endDate": { "type": "string", "format": "date", "description": "Maximum date of all transactions to include in the report. (Inclusive)" } }, "required": [ "startDate", "endDate" ], "x-tags": [ "Models" ] }, "EventCardSystem": { "title": "EventCardSystem", "type": "object", "example": { "id": 1, "name": "UiTPAS Dender", "enabled": true, "manualDistributionKeys": [ { "id": 123, "name": "€1,5 halve dag", "enabled": true } ] }, "x-tags": [ "Models" ], "description": "CardSystem in an event context, optionally including manual distributionKeys.\n\nThis model is only used in the GET and PUT `/events/{eventId}/card-systems` to configure the card systems and distribution keys for an event.\n\n\n\n> **This model and corresponding endpoints are only needed for exceptional cases.** In most cases card systems and distribution keys are set automatically on events, so you don't need to retrieve or change them.\n", "properties": { "id": { "type": "integer", "description": "ID of the card system" }, "name": { "type": "string", "description": "Name of the card system" }, "enabled": { "type": "boolean", "description": "State of this card system for the event." }, "manualDistributionKeys": { "type": "array", "description": "List of distribution keys, used to determine the price of discounted UiTPAS tariffs, which can be enabled or disabled manually for the event.", "items": { "type": "object", "description": "Distribution key that can be enabled or disabled manually for the related event.", "properties": { "id": { "type": "integer", "description": "Unique ID of the manual distribution key." }, "name": { "type": "string", "description": "Human-readable name of the distribution key." }, "enabled": { "type": "boolean", "description": "Whether the distribution key is enabled or not for this specific event." } }, "required": [ "id", "enabled" ] } } }, "required": [ "id", "enabled" ] }, "TariffsResponse": { "title": "TariffsResponse", "description": "Response object for tariffs", "type": "object", "example": { "available": [ { "id": "SOCIALTARIFF-1", "name": "UiTPAS Kansentarief", "price": 1.5, "type": "SOCIALTARIFF", "remaining": 1 } ] }, "x-tags": [ "Models" ], "properties": { "available": { "type": "array", "description": "List of available tariffs.", "items": { "$ref": "#/components/schemas/TariffAvailibility" } }, "endUserMessage": { "type": "object", "description": "Optional property that, if provided, contains information for the end-user about potentially unavailable tariffs (while the end user might expect otherwise). e.g. if no tariff of type `SOCIALTARIFF` is available, while the passholder has a valid social tariff, this field can contain a human-readable explanation of the problem, specifically for end-users, in one or more languages. An `nl` value is always provided, other languages may be provided. When this property is included, it is strongly encouraged to show this to the end-user. It is also important to note that this message is context-aware: e.g. when filtering tariffs on `type=SOCIALTARIFF`, this message won't include information about coupons. Furthermore keep in mind this 'end user message' does not necessarily contain a fatal error. A message might be relevant to show while there are still other tariffs available.", "properties": { "nl": { "type": "string", "description": "A human-readable explanation of the problem, specifically for end-users, localized in Dutch." }, "fr": { "type": "string", "description": "A human-readable explanation of the problem, specifically for end-users, localized in French." }, "de": { "type": "string", "description": "A human-readable explanation of the problem, specifically for end-users, localized in German." }, "en": { "type": "string", "description": "A human-readable explanation of the problem, specifically for end-users, localized in English." } }, "required": [ "nl" ] } } }, "TariffAvailibility": { "example": { "id": "COUPON5678", "name": "Cultuurbon 8 euro", "price": 2, "remaining": 1, "type": "COUPON" }, "description": "The `TariffAvailibility` includes all information about the `Tariff`, which describes the discounted price a passholder has to pay for a given ticket, and the `remaining` number of tickets this passholder can buy for this event at this Tariff.", "title": "TariffAvailibility", "allOf": [ { "$ref": "#/components/schemas/Tariff" }, { "type": "object", "properties": { "remaining": { "type": "integer", "example": 1, "readOnly": true, "description": "Amount of tickets available at this price for this event, for the given passholder." } }, "required": [ "remaining" ] } ], "x-tags": [ "Models" ] }, "Period": { "title": "Period", "type": "object", "example": { "begin": "2019-08-24T14:15:22+00:00", "end": "2019-08-24T14:15:22+00:00" }, "x-tags": [ "Models" ], "description": "Period entity with a begin and optional end date.", "properties": { "begin": { "type": "string", "format": "date-time", "description": "Start date of the period (inclusive)." }, "end": { "type": "string", "format": "date-time", "description": "End date of the period (inclusive)." } }, "required": [ "begin" ] }, "Reward": { "type": "object", "title": "Reward", "description": "Reward model", "x-tags": [ "Models" ], "properties": { "id": { "type": "string", "description": "ID of the reward", "readOnly": true }, "title": { "type": "string", "description": "Title of the reward" }, "type": { "type": "string", "description": "Type of the reward", "enum": [ "POINTS", "WELCOME" ] }, "promotionalDescription": { "type": "string", "description": "Promotion description" }, "publicationPeriod": { "$ref": "#/components/schemas/Period" }, "points": { "type": "number", "description": "Number of points needed to redeem the reward. Required for reward of type POINTS." }, "categories": { "type": "array", "description": "List of categories of this reward. Required for reward of type POINTS.", "items": { "type": "string", "enum": [ "Eten en drinken", "Doen", "Gadget of item", "Goede doel" ] } }, "moreInfoURL": { "type": "string", "description": "URL where a user can find more info about this reward. Required for reward of type POINTS.", "format": "uri" }, "grantingPeriod": { "$ref": "#/components/schemas/Period" }, "owningCardSystem": { "$ref": "#/components/schemas/CardSystem" }, "applicableCardSystems": { "type": "array", "description": "List of CardSystems whose members can redeem this reward. ", "items": { "$ref": "#/components/schemas/CardSystem" } }, "allCardSystems": { "type": "boolean", "description": "If set to true, `applicableCardSystems` will always contain all UiTPAS CardSystems.", "default": true }, "organizers": { "type": "array", "description": "List of Organizers where this reward can be redeemed.", "items": { "$ref": "#/components/schemas/Organizer" } }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "DELETED" ], "description": "Status of this reward.", "readOnly": true }, "maxAvailableUnits": { "type": "integer", "description": "Maximum (total) available units of this reward." }, "unitsTaken": { "type": "integer", "description": "Number of rewards already redeemed.", "readOnly": true }, "practicalInfo": { "type": "string", "description": "Practical info for passholders who want to redeem this reward." }, "pictures": { "type": "array", "description": "List of URLs to zero or more images of this reward.", "items": { "type": "string", "format": "uri" } }, "redeemPeriod": { "$ref": "#/components/schemas/Period" }, "forKids": { "type": "boolean", "description": "true if this reward is specifically targetted to children." }, "sport": { "type": "boolean", "description": "true if this is a sport reward" }, "featured": { "type": "boolean", "description": "true if this reward is currently set as 'featured'" }, "online": { "type": "boolean", "description": "true if this reward can be redeemed online" }, "lastChance": { "type": "boolean", "description": "true if this rewards will not be redeemable anymore in the near future", "readOnly": true }, "redeemConstraint": { "type": "object", "description": "Defines how many times this reward can be redeemed by the same passholder in a specific period.", "properties": { "volume": { "type": "integer", "description": "The maximum number of times this reward can be redeemed by the same passholder." }, "period": { "type": "string", "description": "The calendar period this volume constraint applies to:\n- `ABSOLUTE`: the constraint applies to any period.\n- `DAY`: the constraint applies from 00:00 to 23:59\n- `WEEK`: the constraint applies from Monday 00:00 to Sunday 23:59\n- `MONTH`: the constraint applies from the first of the month at 00:00 to the last day of the month 23:59\n- `QUARTER`: this constraint applies to the first day of the quarter to the last day: January-March, April-June, July-September, October-December.\n- `YEAR`: from the Jan 1st to Dec 31st", "enum": [ "ABSOLUTE", "DAY", "WEEK", "MONTH", "QUARTER", "YEAR" ] } }, "required": [ "volume", "period" ] } }, "required": [ "title", "type", "promotionalDescription", "publicationPeriod" ] }, "RedeemedReward": { "type": "object", "title": "RedeemedReward", "x-tags": [ "Models" ], "properties": { "id": { "type": "string", "description": "ID of the redeemed reward." }, "reward": { "$ref": "#/components/schemas/Reward" }, "redeemDate": { "type": "string", "format": "date-time", "description": "Date of the redeem action." }, "redeemInfo": { "type": "object", "description": "Information about the redeem action.", "properties": { "text": { "type": "string", "description": "Text to show to the user who redeemed this reward." }, "link": { "type": "string", "format": "uri", "description": "Link for a call-to-action for the redeemed reward." }, "label": { "type": "string", "description": "Label for the call-to-action of the redeemed reward." } } }, "redeemCode": { "type": "string", "description": "Redeem code to show to the user who redeemed this reward. (Only applicable to certain rewards that are configured in the UiTPAS Card System admin)" } }, "required": [ "id", "reward", "redeemDate" ] }, "Facet": { "title": "Facet", "type": "object", "description": "Each property is a possible filter value, mapping to an object with a human-readable name and amount of results if the filter value is applied in combination with the other active filters.", "additionalProperties": { "type": "object", "properties": { "name": { "type": "object", "description": "Internationalized human-readable name for the filter value.", "properties": { "nl": { "type": "string", "description": "Human-readable name for the filter value localized in Dutch." } } }, "count": { "type": "integer", "description": "Amount of results if the filter is applied in combination with the other active filters." } }, "required": [ "name", "count" ] }, "x-tags": [ "Models" ], "example": { "option1": { "name": { "nl": "Option 1" }, "count": 3 }, "option2": { "name": { "nl": "Option 2" }, "count": 4 } }, "x-examples": { "Example": { "option1": { "name": { "nl": "Human-readable name for option1" }, "count": 3 }, "option2": { "name": { "nl": "Human-readable name for option2" }, "count": 4 } } } }, "CardSystemsPaginatedCollection": { "title": "CardSystemsPaginatedCollection", "type": "object", "x-tags": [ "Models" ], "description": "Paginated response object for card systems", "properties": { "totalItems": { "type": "integer", "description": "Total number of card system results (can be more than the amount of results in the response)." }, "member": { "type": "array", "description": "List of card system results for this specific (paginated) request.", "items": { "$ref": "#/components/schemas/CardSystem" } } } }, "TransactionsPaginatedCollection": { "title": "TransactionsPaginatedCollection", "type": "object", "x-tags": [ "Models" ], "description": "Paginated response object for transactions", "properties": { "totalItems": { "type": "integer", "description": "Total number of card system results (can be more than the amount of results in the response)." }, "member": { "type": "array", "description": "List of card system results for this specific (paginated) request.", "items": { "$ref": "#/components/schemas/Transaction" } } } }, "Transaction": { "type": "object", "title": "Transaction", "x-tags": [ "Models" ], "description": "Transaction", "properties": { "title": { "type": "string", "description": "Title of the transaction", "readOnly": true }, "location": { "type": "string", "description": "Location of the transaction", "readOnly": true }, "creationDate": { "type": "string", "format": "date-time", "description": "Creationdate of the transaction", "readOnly": true }, "points": { "type": "number", "description": "Points of the transaction. Extra points (e.g. at check-in) are positive numbers. Used points (e.g. redeeming a reward) are negative numbers.", "readOnly": true } }, "required": [ "title", "location", "creationDate", "points" ], "readOnly": true }, "City": { "title": "City", "type": "object", "x-tags": [ "Models" ], "example": { "postalCode": "9300", "name": "Aalst" }, "properties": { "postalCode": { "type": "string", "description": "Postalcode of the city" }, "name": { "type": "string", "description": "Name of the city" } }, "required": [ "postalCode", "name" ] }, "Order": { "type": "object", "title": "Order", "description": "Order object", "properties": { "id": { "type": "string", "x-stoplight": { "id": "n9hihx4x3wa17" }, "description": "ID of the order. This property is always present in responses.", "readOnly": true }, "status": { "type": "string", "x-stoplight": { "id": "6t5j0p21gcxwj" }, "enum": [ "PENDING_PAYMENT", "PENDING_UITID_CONNECT", "COMPLETED", "CANCELLED" ], "description": "Status of the order. This property is always present in responses.", "readOnly": true }, "paymentUrl": { "type": "string", "x-stoplight": { "id": "bmo5ep7z3wbn2" }, "description": "Payment URL (only when status is `PENDING_PAYMENT`)", "readOnly": true }, "email": { "type": "string", "x-stoplight": { "id": "9heoomg0mq75m" }, "description": "Email of the orderer. This property is always present in responses.", "readOnly": true }, "totalPrice": { "type": "number", "x-stoplight": { "id": "f198xd50mpxmg" }, "description": "Total price of the order. This property is always present in responses.", "readOnly": true }, "registrationToken": { "type": "string", "x-stoplight": { "id": "q1oexa53dyky7" }, "description": "Optional registration token. If this order is `PENDING_UITID_CONNECT` this field is present to allow for easy UiTiD account linking.", "readOnly": true }, "customToken": { "type": "string", "description": "Custom token that can be used for a limited number of time to request this order using `GET /orders/id` without any further authentication.", "readOnly": true }, "mainPassholderRegistration": { "$ref": "#/components/schemas/PassholderRegistration" }, "extraPassholderRegistrations": { "type": "array", "description": "Optional list of extra passholders in the order", "items": { "$ref": "#/components/schemas/PassholderRegistration" } }, "redirectUrlAfterPayment": { "type": "string", "description": "Where to redirect after payment. Extra query params `orderId` and `customToken` are added to this URL when used to redirect the user, so the receiving client can `GET` the latest status of the order.", "writeOnly": true }, "redirectUrlAfterCancelPayment": { "type": "string", "description": "Where to redirect after payment is cancelled. Extra query params `orderId` and `customToken` are added to this URL when used to redirect the user, so the receiving client can `GET` the latest status of the order.", "writeOnly": true } }, "required": [ "mainPassholderRegistration" ] }, "Card": { "title": "Card", "x-stoplight": { "id": "zqvfbrdvemv9g" }, "type": "object", "description": "Representation of an UiTPAS card.", "properties": { "uitpasNumber": { "type": "string", "x-stoplight": { "id": "wt5795os9zlly" }, "description": "UiTPAS number of this card." }, "cardSystem": { "$ref": "#/components/schemas/CardSystem" }, "cardType": { "type": "string", "x-stoplight": { "id": "0wg00e7ok83tp" }, "enum": [ "NFC_CARD", "DIGITAL" ], "description": "Type of this card." }, "status": { "type": "string", "x-stoplight": { "id": "ic0htdaaq5wmr" }, "description": "Status of this card.", "enum": [ "PROVISIONED", "LOCAL_STOCK", "ACTIVE", "BLOCKED", "DELETED" ] }, "socialTariff": { "type": "boolean", "x-stoplight": { "id": "k6sdxxpe9zvpe" }, "description": "Indicated the social tariff status of this card." } }, "required": [ "uitpasNumber", "cardSystem", "status", "socialTariff" ] }, "CheckinStatus": { "title": "CheckinStatus", "type": "object", "properties": { "allowed": { "type": "boolean", "description": "Indicates whether a checkin is currently possible." }, "endUserMessage": { "type": "object", "description": "Optional property that, if provided, contains information for the end-user about why the checkin is currently not allowed.", "properties": { "nl": { "type": "string", "description": "A human-readable explanation of the problem, specifically for end-users, localized in Dutch." }, "fr": { "type": "string", "description": "A human-readable explanation of the problem, specifically for end-users, localized in French." }, "de": { "type": "string", "description": "A human-readable explanation of the problem, specifically for end-users, localized in German." }, "en": { "type": "string", "description": "A human-readable explanation of the problem, specifically for end-users, localized in English." } }, "required": [ "nl" ] } }, "description": "The status of a potential checkin, including an `endUserMessage` when it's not allowed." }, "PassholderPicture": { "title": "PassholderPicture", "x-stoplight": { "id": "3ipzpxwesu2dv" }, "type": "object", "properties": { "pictureUrl": { "type": "string", "x-stoplight": { "id": "je23zfyodev7c" }, "description": "URL of the picture of the passholder." } }, "required": [ "pictureUrl" ] }, "DownloadLinkResponse": { "title": "DownloadLinkResponse", "x-stoplight": { "id": "a922luo99cksx" }, "type": "object", "properties": { "downloadLink": { "type": "string", "x-stoplight": { "id": "3opxrhpcw3s6u" }, "description": "Download link for the requested file" } }, "required": [ "downloadLink" ] }, "KioskDeviceEvent": { "title": "KioskDeviceEvent", "x-stoplight": { "id": "y5atjfuzrvep1" }, "type": "object", "description": "Event model used in Kiosk APIs", "properties": { "checkinPoints": { "type": "integer", "x-stoplight": { "id": "b416vifd5i684" }, "description": "Points earned when passholds checks in" }, "event": { "type": "object", "x-stoplight": { "id": "345z9zuzxe547" }, "description": "Current event of the kiosk.", "required": [ "id", "title" ], "properties": { "id": { "type": "string", "x-stoplight": { "id": "6b10ruuepsrjo" }, "description": "ID of the event" }, "title": { "type": "string", "x-stoplight": { "id": "dxavbqgc8aysl" }, "description": "Title of the event" } } }, "checkinCode": { "type": "string", "x-stoplight": { "id": "orc9gdhisu1ya" }, "description": "Checkin code for the event" } }, "required": [ "checkinPoints", "event", "checkinCode" ] }, "KioskDevice": { "title": "KioskDevice", "x-stoplight": { "id": "hh3kfd7lxxds9" }, "type": "object", "description": "Representation of the kiosk entity", "x-examples": { "Example": { "id": "db385941-ece7-493d-8c4b-4320c4849646", "name": "CID-PPT-001", "deviceId": "ebee0a27-2dba-4231-aaae-15077884fa75", "organizers": [ { "id": "fd7e6177-4add-4fa8-a7fe-6e60127bfb35", "name": "CC De Schakel" } ], "cardSystem": { "id": 1, "name": "UiTPAS Dender", "branding": { "logo": "https://www.uitpas.be/_nuxt/img/1351557.svg", "primaryColor": "rgba(0,0,0,1.0)", "secondaryColor": "rgba(97,166,14,1.0)" }, "links": { "website": "https://www.uitpas.be" }, "cities": [ { "postalCode": "9300", "name": "Aalst" }, { "postalCode": "9400", "name": "Ninove" } ], "permanent": true }, "releaseTrack": "stable" } }, "properties": { "id": { "type": "string", "description": "ID of the kiosk. This field is always available in responses.", "readOnly": true }, "name": { "type": "string", "x-stoplight": { "id": "g2vr54zw4cq7o" }, "description": "Name of the kiosk. This field is always available in responses.", "readOnly": true }, "organizers": { "type": "array", "description": "Organizers linked to this kiosk", "items": { "$ref": "#/components/schemas/Organizer" } }, "locations": { "type": "array", "x-stoplight": { "id": "m988ozti2dcka" }, "description": "Locations linked to this kiosk", "items": { "$ref": "#/components/schemas/Location" } }, "deviceId": { "type": "string", "x-stoplight": { "id": "7q3dpudb6iaay" }, "description": "Device ID linked to this kiosk." }, "cardSystem": { "$ref": "#/components/schemas/CardSystem" }, "releaseTrack": { "type": "string", "x-stoplight": { "id": "af2qu41h1ry0m" }, "description": "Release track of this kiosk", "enum": [ "beta", "stable" ] } }, "required": [ "id", "name", "deviceId", "cardSystem", "releaseTrack" ] }, "KioskDeviceEventRequest": { "title": "KioskDeviceEventRequest", "x-stoplight": { "id": "2bfdjhsqwwxj1" }, "type": "object", "description": "Model to configure the kiosk event", "properties": { "id": { "type": "string", "description": "ID of the event" } }, "required": [ "id" ] }, "KioskDeviceCheckinRequest": { "title": "KioskDeviceCheckinRequest", "x-stoplight": { "id": "p017ejlluigiv" }, "type": "object", "properties": { "chipNumber": { "type": "string", "x-stoplight": { "id": "upndvphy3uppq" }, "description": "Chipnumber of the passholder to checkin" } }, "required": [ "chipNumber" ] }, "KioskDeviceCheckinResponse": { "title": "KioskDeviceCheckinResponse", "x-stoplight": { "id": "a0b3354689f18" }, "type": "object", "description": "Checkin via kiosk response", "properties": { "newPoints": { "type": "integer", "description": "New points as a result of this checkin", "x-stoplight": { "id": "9xh8ib4eacnsd" } }, "totalPoints": { "type": "integer", "description": "Total points of the passholder after this checkin" } }, "required": [ "newPoints", "totalPoints" ] }, "KioskDeviceSetup": { "title": "KioskDeviceSetup", "x-stoplight": { "id": "ylj4q1p2eeisl" }, "type": "object", "properties": { "name": { "type": "string", "x-stoplight": { "id": "xs87oo7o9eqfy" }, "description": "Name of the KIOSK" }, "deviceId": { "type": "string", "x-stoplight": { "id": "phadvfcafaeuc" }, "description": "Device ID of the kiosk" } }, "required": [ "name", "deviceId" ] }, "Location": { "title": "Location", "x-stoplight": { "id": "jsek0i5fkc5ai" }, "type": "object", "description": "Location model", "properties": { "id": { "type": "string", "description": "ID of the location" }, "name": { "type": "string", "x-stoplight": { "id": "xqbdyntqozql8" }, "description": "Name of the location" } }, "required": [ "id", "name" ] }, "EventSettings": { "title": "EventSettings", "x-stoplight": { "id": "vn36pgcxzw6l7" }, "type": "object", "description": "Event setting within UiTPAS", "properties": { "id": { "type": "string", "description": "ID of the event" }, "passholderTicketLimit": { "$ref": "#/components/schemas/PeriodLimit" }, "checkinLimit": { "$ref": "#/components/schemas/PeriodLimit" }, "checkinPoints": { "type": "integer", "x-stoplight": { "id": "2w5lssksar2hk" }, "description": "Points earned after a checkin for this event" } }, "required": [ "id", "checkinPoints" ] }, "PeriodLimit": { "title": "PeriodLimit", "type": "object", "description": "Period limit settings", "properties": { "volume": { "type": "integer", "description": "Volume of this limit" }, "periodType": { "type": "string", "enum": [ "ABSOLUTE", "DAY", "WEEK", "MONTH", "QUARTER", "YEAR" ], "description": "Period type of the limit" } }, "required": [ "volume", "periodType" ] }, "KioskPass": { "title": "KioskPass", "x-stoplight": { "id": "pia2mamgrb6kc" }, "type": "object", "description": "Pass information", "properties": { "totalPoints": { "type": "integer", "x-stoplight": { "id": "g914t3kiofl8f" }, "description": "Total points of the passholder" } }, "required": [ "totalPoints" ] }, "CardSystemSocialTariffSettings": { "title": "CardSystemSocialTariffSettings", "x-stoplight": { "id": "gr3fmeyv787ao" }, "type": "object", "description": "CardSystemSocialTariffSettings", "properties": { "postalCode": { "type": "string", "x-stoplight": { "id": "0xm0rbvq3kdcb" }, "description": "Postal code" }, "allowsCardlessRegistration": { "type": "boolean", "x-stoplight": { "id": "9q12nus6hxclk" }, "description": "true if social tariff registration is allowed for passholder with `postalCode`." } }, "required": [ "postalCode", "allowsCardlessRegistration" ] }, "CardSystemCitySettings": { "title": "CardSystemCitySettings", "x-stoplight": { "id": "opeie5n4zc8p3" }, "type": "object", "description": "CardSystemCitySettings", "properties": { "city": { "type": "string", "x-stoplight": { "id": "0xm0rbvq3kdcb" }, "description": "These settings apply to this city." }, "allowsCardlessRegistration": { "type": "boolean", "x-stoplight": { "id": "9q12nus6hxclk" }, "description": "true if social tariff registration is allowed for passholder with `postalCode`." }, "contactEmail": { "type": "string", "x-stoplight": { "id": "jhikn8amk44e6" }, "description": "Contact email of this card system in the given city." } }, "required": [ "city", "allowsCardlessRegistration", "contactEmail" ] }, "SocialTariffValidation": { "title": "SocialTariffValidation", "x-stoplight": { "id": "gryzsngewgyjv" }, "type": "object", "description": "SocialTariffValidation information", "properties": { "user": { "$ref": "#/components/schemas/SocialTariffValidationPerson" }, "children": { "type": "array", "x-stoplight": { "id": "f6pyicmviravx" }, "description": "Optional list of children of the identified persion.", "items": { "$ref": "#/components/schemas/SocialTariffValidationPerson" } } }, "required": [ "user" ] }, "SocialTariffValidationTokenRequest": { "title": "SocialTariffValidationTokenRequest", "x-stoplight": { "id": "h9f7buv9bbqp3" }, "type": "object", "description": "SocialTariffValidationTokenRequest", "properties": { "code": { "type": "string", "x-stoplight": { "id": "aj11gec4d2o3p" }, "description": "code from step 2 in the authentication process" }, "codeVerifier": { "type": "string", "x-stoplight": { "id": "9ov8etk9jcnq4" }, "description": "code_verifier from step 1 in the authentication process" } }, "required": [ "code", "codeVerifier" ] }, "SocialTariffValidationTokenResponse": { "title": "SocialTariffValidationTokenResponse", "type": "object", "description": "SocialTariffValidationTokenRequest", "properties": { "token": { "type": "string", "x-stoplight": { "id": "aj11gec4d2o3p" }, "description": "code from step 2 in the authentication process" } }, "required": [ "token" ] }, "SocialTariffValidationPerson": { "type": "object", "description": "SocialTariffValidationPerson", "properties": { "inszNumber": { "type": "string", "description": "INSZ number of the identified person" }, "familyName": { "type": "string", "description": "Family name of the identified person" }, "givenName": { "type": "string", "description": "Given name of the identified person" }, "hasSocialTariff": { "type": "boolean", "description": "True if the person is entitled to social tariff" }, "uitpasNumber": { "type": "string", "description": "Optional `uitpasNumber` if the person with the given `inszNumber` already has an UiTPAS. If this property is not null, the user cannot proceed registration of a new passholder." }, "street": { "type": "string", "description": "Street and house number of the user if known." }, "postalCode": { "type": "string", "description": "Postal code of the user if known." }, "city": { "type": "string", "description": "City of the user if known." }, "idToken": { "type": "string", "description": "Social Tariff Validation ID token of the user used in /`POST orders` request." }, "idTokenExpiresAt": { "type": "string", "format": "date-time", "description": "Date and time until the ID token is valid. If the ID token is expired it can't be used in `POST /orders`. The client must repeat the social tariff validation flow to obtain a new ID token." } }, "required": [ "inszNumber", "familyName", "givenName", "hasSocialTariff", "idToken", "idTokenExpiresAt" ], "title": "SocialTariffValidationPerson" }, "Association": { "title": "Association", "x-stoplight": { "id": "0cqmy2cuzwux0" }, "type": "object", "description": "Association", "x-examples": {}, "properties": { "id": { "type": "string", "description": "ID of the association" }, "name": { "type": "string", "x-stoplight": { "id": "bl1hgz5y2wooc" }, "description": "Name of the association. This field is always available in responses", "readOnly": true }, "endDateType": { "type": "string", "x-stoplight": { "id": "siqftnrb8ax7e" }, "description": "Indicates how end dates are set for memberships of this association. This field is always available in responses.", "enum": [ "CUSTOM", "BASED_ON_DATE_OF_BIRTH", "BASED_ON_REGISTRATION_DATE" ], "readOnly": true } }, "required": [ "id" ] }, "AssociationMembership": { "title": "AssociationMembership", "x-stoplight": { "id": "mb1bs9upl614a" }, "type": "object", "x-examples": {}, "properties": { "association": { "$ref": "#/components/schemas/Association" }, "status": { "type": "string", "x-stoplight": { "id": "kdp35yno8ebht" }, "enum": [ "ACTIVE", "EXPIRED", "NONE" ], "description": "Status of the membership. This field is always available in responses.", "readOnly": true }, "endDate": { "type": "string", "x-stoplight": { "id": "eradjp82wpqv0" }, "format": "date", "description": "End date of the membership. This field is available in responses if status is `ACTIVE` or `EXPIRED`. This field is required in requests for association with a `CUSTOM` endDateType." }, "renewable": { "type": "boolean", "x-stoplight": { "id": "ahns1w7wy66mj" }, "description": "True if this membership can currently be renewed. This fields is always available in responses.", "readOnly": true }, "newEndDate": { "type": "string", "x-stoplight": { "id": "lxwcvxz2cbqrz" }, "format": "date", "description": "New end date of the membership in case it is renewed or created. This field can be used to pre-fill the endDate field in a front-end UI. It is only available when: `endDateCalculation` of the association is `CUSTOM`, and the status is `NONE` (new membership) or `renewable` is true (renew membership).", "readOnly": true } }, "required": [ "association" ] }, "MembershipRequest": { "title": "MembershipRequest", "x-stoplight": { "id": "ffmqhyqswhm6o" }, "type": "object", "description": "Membership request model", "properties": { "cardType": { "type": "string", "x-stoplight": { "id": "qof4ex52e0ae5" }, "enum": [ "NFC_CARD", "DIGITAL" ], "description": "Type of the card in the new membership" }, "uitpasNumber": { "x-stoplight": { "id": "di5zmsweur7xj" }, "type": "string", "description": "Uitpas number of the physical card. Only required when cardType is NFC_CARD." }, "address": { "type": "object", "x-stoplight": { "id": "ugw7b7xei7cbz" }, "description": "New address of the passholder. Required when the passholder receives a social tariff membership and his current address is outside the card system.", "properties": { "street": { "type": "string", "x-stoplight": { "id": "nejol4a8vhq7r" }, "description": "Street name, number and optional box number of the address." }, "postalCode": { "type": "string", "x-stoplight": { "id": "csz5bpz4u8z8m" }, "description": "Postal code of the municipality." }, "city": { "type": "string", "x-stoplight": { "id": "vpmiuu2h7ju7c" }, "description": "Human-readable name of the municipality." } }, "required": [ "street", "postalCode", "city" ] }, "socialTariff": { "type": "object", "x-stoplight": { "id": "jkw53cz3xe5tf" }, "description": "Indicates whether the new membership should receive social tariff", "properties": { "socialTariffEndDate": { "type": "string", "x-stoplight": { "id": "njwmjsvu77qg1" }, "format": "date", "description": "End date of the social tariff. If not specified, the response when validateOnly=true will contain the system default for social tariff end dates." } } }, "voucher": { "type": "string", "x-stoplight": { "id": "rhuyzfbchz0n4" }, "description": "Voucher for price reduction of the new membership." }, "registrationOrganizer": { "$ref": "#/components/schemas/Organizer" } }, "required": [ "cardType", "registrationOrganizer" ] }, "GrantedCoupon": { "type": "object", "x-stoplight": { "id": "6952809026004" }, "properties": { "id": { "type": "integer", "x-stoplight": { "id": "gy3cnzbjsos7m" }, "description": "ID of this granted coupon" }, "coupon": { "type": "object", "x-stoplight": { "id": "7uhshingout9h" }, "required": [ "id", "name" ], "description": "The coupon of this granted coupon", "properties": { "id": { "type": "string", "x-stoplight": { "id": "9lc2aar0ke5mt" }, "description": "ID of the coupon" }, "name": { "type": "string", "x-stoplight": { "id": "ju827c3hyobo6" }, "description": "Name of the coupon" }, "description": { "type": "string", "x-stoplight": { "id": "0m1k758km1di4" }, "description": "Description of the coupon" } } }, "validityPeriod": { "type": "object", "x-stoplight": { "id": "d7x4iwrrak9tm" }, "description": "Validatity period of this coupon", "properties": { "begin": { "type": "string", "x-stoplight": { "id": "hzer6iazpfcpd" }, "format": "date-time", "description": "Coupon is valid from this date" }, "end": { "type": "string", "x-stoplight": { "id": "p62zqlsppr3gg" }, "format": "date-time", "description": "Coupon is valid until this date. After this date, this coupon will appear as status `EXPIRED`" } }, "required": [ "begin" ] }, "status": { "type": "string", "x-stoplight": { "id": "pua8h5vd8410c" }, "enum": [ "ACTIVE", "EXPIRED" ], "description": "Status of this granted coupon" }, "remaining": { "type": "object", "x-stoplight": { "id": "wp3luo60wgz57" }, "description": "Remaining ticket sales for this granted coupon (is applicable)", "properties": { "volume": { "type": "integer", "x-stoplight": { "id": "tmfnerf0ntoor" }, "description": "Volume of the remaining ticketsales" }, "period": { "type": "string", "x-stoplight": { "id": "a0yelgv8k0gy1" }, "enum": [ "ABSOLUTE", "DAY", "WEEK", "MONTH", "QUARTER", "YEAR" ], "description": "Period of the remaining ticketsales" } }, "required": [ "volume", "period" ] } }, "required": [ "id", "coupon", "status" ], "title": "GrantedCoupon" } }, "securitySchemes": { "USER_ACCESS_TOKEN": { "type": "oauth2", "flows": {}, "description": "A user access token, obtained by redirecting the end user to publiq's authorization server to login using the **Authorization Code OAuth Flow**. See the [authentication docs about user access tokens](https://docs.publiq.be/docs/authentication/methods/user-access-token) for more info." }, "CLIENT_ACCESS_TOKEN": { "type": "oauth2", "flows": {}, "description": "A client access token, obtained by exchanging your client id and client secret for a token via an HTTP request to publiq's authorization server using the **Client Credentials OAuth Flow**. See the [authentication docs about client access tokens](https://docs.publiq.be/docs/authentication/methods/client-access-token) for more info." }, "CLIENT_IDENTIFICATION": { "name": "x-client-id", "type": "apiKey", "in": "header" }, "CUSTOM_TOKEN": { "name": "x-custom-token", "type": "apiKey", "in": "header" } }, "parameters": { "uitpasNumber": { "schema": { "type": "string" }, "name": "uitpasNumber", "in": "path", "required": true, "description": "Unique UiTPAS number of a registered pass." }, "inszNumber": { "schema": { "type": "string" }, "name": "inszNumber", "in": "path", "required": true, "description": "Unique national (Belgian) INSZ number of an individual passholder to look up." }, "chipNumber": { "schema": { "type": "string" }, "name": "chipNumber", "in": "path", "required": true, "description": "Hexadecimal notation of the chip number of an individual UiTPAS card." }, "passholderId": { "schema": { "type": "string" }, "name": "passholderId", "in": "path", "description": "Unique ID of an UiTPAS passholder.", "required": true }, "organizerId": { "schema": { "type": "string" }, "name": "organizerId", "in": "path", "required": true, "description": "Unique ID of an UiTPAS organizer. (Same as its ID in UiTdatabank)" }, "reportId": { "schema": { "type": "integer" }, "name": "reportId", "in": "path", "required": true, "description": "Unique ID of the generated financial report." }, "start": { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "start", "description": "Position to start returning results from. When set to `0` the results starting from the very first position will be returned. When set to for example `10` the results 0-9 will be skipped and the ones starting from position 10 will be returned. Can be used in combination with `limit` for pagination." }, "limit": { "schema": { "type": "integer", "default": 20, "minimum": 0 }, "in": "query", "name": "limit", "description": "Maximum amount of results to return. Can be used in combination with `start` for pagination. **Important**: the maximum value for `limit` is `500`. Exceeding this value will result in an error." } }, "responses": { "Unauthorized": { "description": "Unauthorized. Your request is missing the required credentials to authenticate. See the Authentication documentation for more info.\n\n* type: https://api.publiq.be/probs/auth/unauthorized\n* detail: might contain a developer-readable explanation of the reason", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" }, "x-examples": { "Unauthorized": { "value": { "type": "https://api.publiq.be/probs/auth/unauthorized", "title": "Unauthorized", "status": 401 } } } } } }, "Forbidden": { "description": "Forbidden. Your request was successfully authenticated but you do not have permission to perform this particular request.\n\n* type: https://api.publiq.be/probs/auth/forbidden\n* detail: might contain a developer-readable explanation of the reason", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" }, "x-examples": { "Forbidden": { "value": { "type": "https://api.publiq.be/probs/auth/forbidden", "title": "Forbidden", "status": 403, "detail": "user must be admin of organiser abcd1234" } } } } } } }, "requestBodies": {} } }