# Personalization

Personalizations (persons) are uniquely identified by their first- and lastname and their birthdate. That also means that those three fields are mandatory. The other values are quite flexible. This also means that it is not possible to change first- and lastname as well as birthdate, all other values can be changed. If one of the three needs to change the personalization entry has to be deleted and a new one has to be added.

To avoid clashes with internal personalization attributes only attributes can be added that have an id starting with x-. Also validations can only be added for those attributes. Once a attribute or a validation has been published in the system it should be considered immutable. Other integrators could also use the attribute and if it changes in a way they cannot handle things will break. To avoid that no editing and deleting of attributes and validations is possible. If changes are needed create a new attribute. A attribute can have more than one validation in case we have slightly different requirements in different areas. A validation is always valid for a category (see Catalog API) or for all other categories if the category has not been specified.

# Remark

WARNING

There is the possibility to generalize necessary personalization values from offer variants to offers and from offers to all of the persons. That means that if all (or most of the) variants of a offer have the same personalization values we omit them and put them on the offer instead. The same would be true for our offers. Those would then be moved to the global level. If personalization at a specific level is not specified it means that it has been generalized away. Offers and variants that do not require personalization at all in contrast have a empty personalization array ([]) on them.

Generally the logic is like the following:

  • look at the variant level for personalization, if it is not there look at the offer level instead
  • if personalization is also not speficied at the offer levellook at the global level instead
  • there you should either find some personalization attributes or at least a empty personalization array

# Endpoint Structure

  • call /personalizations/list to get all available personalization data of the customer, this is meant for personalization management
  • call /personalizations/search to search within the available personalization data by first- and lastname (all personalizations that have first- and lastname start with the specified string), this is meant for selecting available personalizations at the personalization screen
  • call /personalizations to add a new personalization entry identified by first- and lastname as well as birthdate
  • call PATCH /personalizations/{personalizationId} to update values of the personalization entry (with the exception of first- and lastname and birthdate)
  • call DELETE /personalizations/{personalizationId} to remove a personalization entry with all data
  • call GET /personalizations/attributes to get the structure of all existing personalization attributes including how they could be rendered, the types they accept and how they should be validated, this is used to render input masks for management of the personalization values
  • call POST /personalizations/attributes to add a new personalization attribute via the API, personalization attributes that are added here are available for all users at once, attribute ids are restricted to those starting with x- so that attributes created by integrators do not clash with internally used/created attributes
  • call POST /personalizations/validations to add a new way of validation for a attribute, also here attributes are restricted to those starting with x- so no validations of internal attributes can be changed. If now category id is specified the validation is valid for all categories that do not have a specific validation assigned.
  • call POST /personalizations/external to query external services like e.g. SwissPass for person data. Generally a type will be required in the request and also be returned in the response. Request and response content will vary according to the external service used. This is POST because of the varying content of the request. Otherwise no change of server resources is expected to be performed.

# Available Personalization Attributes

Currently the following built-in personalization attributes are supported. If the client has the need to add additional personalization attributes to the system it can do so (see below).

  • birthdate - birth date
  • country - country of address
  • email - e-mail address
  • firstname - first name
  • gender - gender
  • idNumber - number/identifier of identity document
  • idType - type of identity document
  • keycardId - keycard identifier
  • language - main/desired language
  • lastname - last name
  • nationality - country of origin
  • phone - phone number
  • photo - identity photo
  • postCode - post code of address
  • street - street name of address
  • streetNumber - house number of address
  • swisspassId - SwissPass number
  • swisspassPostCode - SwissPass post code
  • title - (academic) title

# Glossary

category - part of the system that groups together similar products and sells them in a distinct fashion (partly) different from other groups of products, in other words: products are categorized depending on their characteristics

internal personalization attributes - personalization attributes that are part of the software and are not created by integrators

personalization attribute - (specification of) a field where data can be saved into, part of the whole body of all personalization data fields

personalization data - either the whole body of personalization information available for a customer or the whole body of available personalization data fields

personalization entry - a record of personalization data for a customer, which is identified by firstname, lastname and birthdate and can hold different data depending on the available personalization attributes

personalization value - the value save to a personalization attribute

validation - definition of how a personalization attribute should be validated

← Transport - Mountain Railway →