{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/publiq/main/json-schema/publiq-passholder-schema.json",
  "title": "Passholder",
  "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-generated": "2026-10-09",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/publiq-uitpas-openapi.yml#/components/schemas/Passholder",
  "type": "object",
  "x-tags": [
    "Models"
  ],
  "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": "#/$defs/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": {
      "allOf": [
        {
          "$ref": "#/$defs/Organizer"
        }
      ],
      "writeOnly": true,
      "description": "Only used in passholder creation or update."
    },
    "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
    },
    "registrationPicture": {
      "type": "string",
      "description": "Base64 encoded string of the picture of this passholder. Only used in passholder creation.",
      "format": "byte",
      "x-stoplight": {
        "id": "ikgxjklji2guj"
      },
      "writeOnly": true
    },
    "registrationNote": {
      "type": "string",
      "description": "Only used in passholder creation. The admin-private note about this pas",
      "x-stoplight": {
        "id": "449kx338dtu1q"
      },
      "writeOnly": true
    }
  },
  "required": [
    "name",
    "firstName",
    "dateOfBirth",
    "registrationOrganizer",
    "address"
  ],
  "$defs": {
    "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"
      ],
      "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": "#/$defs/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"
      ]
    },
    "CardSystemMembership": {
      "title": "CardSystemMembership",
      "description": "Membership info of an individual passholder in a specific card system.",
      "type": "object",
      "x-tags": [
        "Models"
      ],
      "properties": {
        "cardSystem": {
          "$ref": "#/$defs/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": "#/$defs/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"
      ]
    },
    "City": {
      "title": "City",
      "type": "object",
      "x-tags": [
        "Models"
      ],
      "properties": {
        "postalCode": {
          "type": "string",
          "description": "Postalcode of the city"
        },
        "name": {
          "type": "string",
          "description": "Name of the city"
        }
      },
      "required": [
        "postalCode",
        "name"
      ]
    },
    "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": "#/$defs/CardSystem"
          }
        },
        "linkedLocationId": {
          "type": "string",
          "description": "ID of the location linked to this organizer.",
          "readOnly": true
        },
        "address": {
          "type": "object",
          "description": "Address of this organizer. This property is alway available in responses.",
          "required": [
            "city"
          ],
          "properties": {
            "street": {
              "type": "string",
              "description": "Street address of this organizer"
            },
            "postalCode": {
              "type": "string",
              "description": "Postal code of this organizer"
            },
            "city": {
              "type": "string",
              "description": "City of this organizer"
            }
          },
          "readOnly": true
        }
      },
      "required": [
        "id"
      ]
    }
  }
}