openapi: 3.2.0 info: title: Publiq Grouppasses API version: '4.0' contact: name: publiq helpdesk email: technical-support@publiq.be url: https://docs.publiq.be x-refined-note: - x-source differs across the merged source definitions and was not carried description: 'Operations tagged Grouppasses across 2 of this provider''s published API definitions: uitpas-uitpas.json, publiq-uitpas-openapi.yml. Each path carries the servers of the definition it was published in.' servers: - url: https://api-test.uitpas.be description: Testing - url: https://api.uitpas.be description: Production tags: - name: Grouppasses paths: /grouppasses: parameters: [] 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 Example with client identification: value: totalItems: 1 member: - id: b5a5bb75-6cae-452b-b029-d12d3b425b1b uitpasNumber: 0900000045410 cardStatus: ACTIVE 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 '400': description: 'Bad Request. Possible error types: * https://api.publiq.be/probs/uitpas/invalid-uitpas-number * https://api.publiq.be/probs/url/query-limit-exceeded The 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 content: application/problem+json: schema: $ref: '#/components/schemas/Error' operationId: get-grouppasses description: 'Retrieve grouppasses based on search parameters. **Note**: For now this endpoint requires either `uitpasNumber` or `chipNumber`, so this endpoint currently cannot be used to search _all_ grouppasses. > **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`. > * When the caller is identified with client identification, this endpoint is rate limited (see the `429` response) and only a subset of the `grouppass` properties is returned. See the individual property descriptions. The caller of this request, identified by client identification, client access token or user access token, must have `GROUPPASSES_SEARCH` permission.' security: - USER_ACCESS_TOKEN: [] - CLIENT_ACCESS_TOKEN: [] - CLIENT_IDENTIFICATION: [] 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 servers: - url: https://api-test.uitpas.be description: Testing - url: https://api.uitpas.be description: Production /grouppasses/{passholderId}: parameters: - schema: type: string name: passholderId in: path required: true description: ID of the Grouppass 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. The caller of this request must have `GROUPPASSES_SEARCH` permission.' security: - USER_ACCESS_TOKEN: [] - CLIENT_ACCESS_TOKEN: [] parameters: [] tags: - Grouppasses servers: - url: https://api-test.uitpas.be description: Testing - url: https://api.uitpas.be description: Production /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: * https://api.publiq.be/probs/uitpas/passholder-no-active-cardsystems * https://api.publiq.be/probs/uitpas/organizer-not-found ' 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. The 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 servers: - url: https://api-test.uitpas.be description: Testing - url: https://api.uitpas.be description: Production components: responses: Unauthorized: description: 'Unauthorized. Your request is missing the required credentials to authenticate. See the Authentication documentation for more info. * type: https://api.publiq.be/probs/auth/unauthorized * 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. * type: https://api.publiq.be/probs/auth/forbidden * 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 schemas: Error: $ref: https://raw.githubusercontent.com/cultuurnet/apidocs/main/projects/errors/models/Error.json 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 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 uitpasNumber: type: string description: The UiTPAS number of this grouppass. This field is always available in responses. name: type: string description: Name of the grouppass. Not available when the caller is identified with client identification. 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. Not available when the caller is identified with client identification. 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: - `ACTIVE`: the grouppass is entitled to social tariff - `EXPIRED`: the grouppass is NOT entitled to social tariff anymore ' 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. Not available when the caller is identified with client identification. 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. required: - postalCode - city telephone: type: string x-stoplight: id: 46g76ybvflcsd description: Telephone contact number of this grouppass. Not available when the caller is identified with client identification. required: - cardStatus - cardSystem 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 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' 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 Error_2: 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 parameters: 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.' 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 x-refined-from: - uitpas-uitpas.json - publiq-uitpas-openapi.yml