Skip to content

How to store and access user consent

In discover.swiss terms & conditions including different versions can be configured to the partner and attached to any kind of data. If it is needed that the user agrees to one of them it is saved in the Business-trail. For more information about the concept see Terms and conditions.
Here is a step-by-step instruction on how you can use the functionality in your application for example to

  • keep control over which version of your terms&conditions the user has accepted or declined
  • store consent or rejection of cookies

Define the term and termversion

We need the following information to configure it for you (soon you can do that yourself in the partner-portal):

  • code: identifier - we may extend it by partner information
  • version: number, string, whatever suits our system
  • name: a human readable name in any language you want to support
  • validFrom: the starting date when the term is/was in place. You can configure a new version ahead of time and they will go live on this date
    ...until the next TermVersion in the same language is valid
  • termDocument: the url to the webpage or document which contains detailed term information in the appropriate language

Tip

To make sure you present the current version of a term and the appropriate links to the user query the current version on {profilUrl}/termversions/{termCode}/currentVersion where termCode = the code of the term not the version

Users with a profile (registered or guest)

Use the POST /terms endpoint described here 

{
    "accepted": "true",
    "termCode": "ZHT-AGB|ZHT-DPP",
    "origin": "Zürich City Guide",
    "ipAddress": "156.12.254.6",
    "termVersion": [
        {
            "code": "ZHT-AGB-2.0"
        },
        {
            "code": "ZHT-DPP-2019-10-28"
        }
    ]
}
This will make an entry for each mentioned termCode in one request and return the same result like the "check consent" below.
It is store in the profile of the user.

The minimal POST to accept a term is 

{
    "accepted": "true",
    "termCode": "ZHT-AGB",
    "origin": "Zürich City Guide"
}
This will accept the current version, now and add the ip-number of the requester.

Use the GET /terms/{termCode} endpoint described here
If you query for terms that do not exist -> http-status 404

{profilUrl}/terms/ZHT-AGB will return 

{
    "termCode": "ZHT-AGB",
    "accepted": true,
    "acceptedDate": "2020-07-10T13:16:09.7692615+00:00",
    "termVersions": [
        {
            "@id": "http://localhost:7071/api/termversion/ZHT-AGB-2.0",
            "code": "ZHT-AGB-2.0",
            "name": "Allgemeine Geschäftsbedingungen von Zürich Tourismus",
            "termDocument": "https://www.zuerich.com/gtc",
            "validFrom": "2018-08-28T23:00:00+02:00",
            "termCode": "ZHT-AGB"
        }
    ]
}
And you can check several at once
{profilUrl}/terms/ZHT-AGB|ZHT-DPP 
{
    "termCode": "ZHT-AGB|ZHT-DPP",
    "accepted": true,
    "acceptedDate": "2020-07-10T13:16:09.7692615+00:00",
    "termVersions": [
        {
            "@id": "http://localhost:7071/api/termversion/ZHT-DPP-2019-10-28",
            "code": "ZHT-DPP-2019-10-28",
            "name": "Datenschutzerklärung von Zürich Tourismus",
            "termDocument": "https://www.zuerich.com/datenschutz",
            "validFrom": "2019-10-27T23:00:00+01:00",
            "termCode": "ZHT-DPP"
        },
        {
            "@id": "http://localhost:7071/api/termversion/ZHT-AGB-2.0",
            "code": "ZHT-AGB-2.0",
            "name": "Allgemeine Geschäftsbedingungen von Zürich Tourismus",
            "termDocument": "https://www.zuerich.com/gtc",
            "validFrom": "2018-08-28T23:00:00+02:00",
            "termCode": "ZHT-AGB"
        }
    ]
}

if a term is not accepted yet or if there is a new version since the last acceptance or if the user declined the term meanwhile: 

{
    "termCode": "ZHT-DPP",
    "accepted": false,
    "termVersions": [
        {
            "@id": "http://localhost:7071/api/termversion/ZHT-DPP-2020-07-01",
            "code": "ZHT-DPP-2020-07-01",
            "name": "Datenschutzerklärung von Zürich Tourismus",
            "termDocument": "https://www.zuerich.com/datenschutz",
            "validFrom": "2020-07-01T02:00:00+02:00",
            "termCode": "ZHT-DPP"
        }
    ]
}
so the important part is: "accepted": false, The rest can be used to display the version which must be accepted.

Use the same code like when accepting a consent but set "accepted": false

{
    "accepted": false,
    "termCode": "ZHT-AGB",
    "origin": "Zürich City Guide"
}

anonymous users without a profile

Typically used for cookie consent on a public homepage.

Use the POST /anonymous/terms endpoint described here 

{
    "accepted": "true",
    "origin": "www.graubünden.ch",
    "TermCode": "GRF-cookie",
    "ipAddress": "22.22.15.15"
}
It behaves like the /terms endpoint described above, but it returns a ProfileTokenResponse.
This allows to handle the tokens like on a guest account and use it to check or decline the consent later like it is described above.

Each call without any auth-tokens creates a new independent entry.

Warning

We do not create 1 profile for 1 IP-Number! Many persons/machines access the internet over the same IP-Address.