Consents

The Consent API allows you to create, delete, update and manage all your consents. Get started quickly by using our predefined consent bases or create your own custom consents.

With the consent API you can:

Manage all your customers consents
Use pre-defined consents without worrying about GDPR
Create custom consents
Integrate with your CRM

You can find the complete reference to the Consents API here: https://developer.entur.org/pages-customers-docs-customers-api

Data model

To be able to register a consent there several things that you need to be aware of. The consent service contains three models:

Consent Base: The consent base contains the legal information of a consent. A consent base can be shared across multiple organisation because the terms can be generic and reusable. Furthermore, the consent base has a field called consentOwnerOrgId. If set, the organisation which owns the consent, and can use it exclusively. Keep this field blank for the consents that are shared between multiple organisations. Note that ConsentTerms and InternalDescription are modelled separately. If ConsentTerms are changed, a new version of the ConsentBase is created. It is possible to add other language versions of the terms without creating a new version.
Consent: While the consent base holds information about what the consent entails, consent provides the link to each organisation and the type of communication that is supported. We say that we instantiate a consent base with a consent.
Given Consent: A given consent is the connection between the customer and what consent the customer consented to.

Versioning

A consent base can have 1 or more versions. The versions has 3 different modes: draft, active, inactive. These modes are controlled by the fields validFrom and validTo.

Draft: If validFrom is not set or set to a datetime in the future.
Active: If validFrom is set to a datetime in the past and validTo is not set or set to a datetime in the future
InActive: If validTo is set to a datetime in the past

A consent base can not update fields after it has become active, with the exception of internalDescription and adding terms in new languages. To retrieve a consent base that are in draft-mode, you need to specify explicit the request to include all versions. See docs for reference.

Consent has the same fields validFrom and validTo to determine if it is active or not. These fields are partial controlled by the consent bases validFrom and validTo. A consents validFromcannot be set before the consent base validFrom and a consents validTocannot be set after the consent base validTo. If a consent base shortens its validTo, it will cascade to consents validTo.

Because of GDPR you are not allowed to change a consent without informing the customers, you will have to create a new version to change the terms and obtain new given consents from your users. Important! The given consent (the decision the customer have made) won’t be deleted unless the user has consented to the new version. When the customer has registered a new given consent and the consent is valid, the previous given consent will be deleted automatically.

Useful keywords:

ConsentOwnerOrgId describes which partner that owns the consent base. In the case that the value is null (empty), it is available for all partners.
OrganisationId describes the partner that instantiated the consent base into a consent.
CreatedByOrgId describes the partner that obtained the givenConsent from the customer.
CustomerNumber is the unique identifier of a customer in Entur systems. All customers, regardless of owning organisation, has a customer number.
CustomerRef (customer reference) identifies a customer within an organisation, and can be provided by the external organisation during customer creation. It is required to be unique within an organisation, if provided
ConsentCode is both used as a unique identifier of a consent base and used among administrators to quickly know what kind of consent it is without having to read the terms and description.
Traveller A customer registered on an order as a traveller.
Agent The entity performing the sale. This may be the operator but it doesn't have to be.
Operator The entity responsible for the transport on a leg in a given order.
Leg a part of a journey, from one stop to the next change. For instance, travelling Bergen->Oslo->Eidsvoll has two legs, and it may or may not be the same operator.

Consents are collected from the travellers by the agents and then distributed to the operators through a kafka-topic [read more].

$When the traveller, or customer service on behalf of the traveller, updates the consents, a message will be sent through a kafka-topic.\nThe operator can then fetch the new consents using the API.$

Use cases

An Agent kan register the consents for a customer through the given-consents api:

curl -X POST \
  https://api.entur.io/customers/v2/consents/client/given-consents \
  -H  "Authorization: Bearer $PARTNER_TOKEN" \
  -H  "Content-Type: application/json" \
  -d '{
    "customerRef" : "DEMO__1",
    "customerNumber": 1234567,
    "consentId" : 715,
    "consentChoice" : true,
    "email" : "test.testesen@entur.org",
    "telephoneNumber" : "12345678",
    "countryCode": "+47",
    "expirationDate" : "2029-11-01T12:00:00+0100"
}'

# Output: {"id":7330,"customerNumber":1234...

Get available consents

curl \        
  https://api.entur.io/customers/v2/consents/admin/consents \ 
  -H  "Authorization: Bearer $PARTNER_TOKEN"
  
# Output: 
#
#[
#  {
#    "id": 711,
#    "consentBase": {
#      "consentCode": "CONSENTS_API_TEST",
#      "terms": [...],
#      "validFrom": "2018-11-01T12:00:00+0000",
#      "validTo": "2118-11-01T12:00:00+0000",
#      "version": 1
#      ...
#    },
#    "organisationId": 399,
#    ...
#  },
#  {
#    "id": 715,
#    "consentBase": {
#      "consentCode": "DEMO",
#      "consentOwnerOrgId": ...,
#      "terms": [...],
#      "validFrom": "2019-09-01T00:00:00+0000",
#      "version": 1,
#      ...
#    },
#    "organisationId": ...,
#    ...
#  }
#]

This list of Consents and ConsentBases are available to you to send in GivenConsents on. If you own the ConsentBase, it will have your consentOwnerOrgId, and only you will se consents connected to it. If it has no consentOwnerOrgId, all organisations can connect to it and you will see all available consents.

Fetch GivenConsents

If you are listening to the kafka topic mentioned above, you will receive GivenConsentChanged events containing no GDPR data, but with the relevant ids. Read about real time updates here When fetching data, to avoid DoSing the server, please use the bulk API if at all possible:

curl -X POST \
  https://api.entur.io/customers/v2/consents/client/given-consents/get-by/bulk \
  -H  "Authorization: Bearer $PARTNER_TOKEN" \
  -H  "Content-Type: application/json" \
  -d '{
    "customerNumbers": [1234567,1234568]
}'

# Output:
#[
#  {
#    "id": 7330,
#    "customerNumber": 1234567,
#    "customerRef": "DEMO__1",
#    "consentId": 715,
#    "consent": {
#      "id": 715,
#      "consentCode": "DEMO",
#      "consentBase": {
#        "consentCode": "DEMO",
#        "terms": [...],
#        "validFrom": "2019-09-01T00:00:00+0000",
#        "version": 1,
#        "consentOwnerOrgId": __,
#        "orgNameSubstitutionPattern": "[ORG]",
#        "createdAt": "2019-09-05T11:54:38+0000",
#        "changedAt": "2019-09-05T11:54:38+0000"
#      },
#      "organisationId": __,
#      "isEmailSupported": true,
#      "isSmsSupported": true,
#      "validFrom": "2019-09-01T00:00:00+0000",
#      "createdAt": "2019-09-05T12:00:27+0000",
#      "changedAt": "2019-09-05T12:00:27+0000",
#      "emailSupported": true,
#      "smsSupported": true
#    },
#    "consentChoice": true,
#    "email": "test.testesen@entur.org",
#    "telephoneNumber": "12345678",
#    "countryCode": "+47",
#    "expirationDate": "2029-11-01T11:00:00+0000",
#    "createdByOrgId": __,
#    "createdAt": "2019-09-05T12:18:56+0000",
#    "changedAt": "2019-09-05T12:18:56+0000"
#  },
# ...
#]

If none of the existing Consents or ConsentBases fit your use case, you can create your own. This will typically be done through the Entur Partner interface. This is what is happening on the API.

curl -X POST \
  https://api.entur.io/customers/v2/consents/admin/consent-bases \
  -H  "Authorization: Bearer $PARTNER_TOKEN" \ 
  -H  "Content-Type: application/json" \
  -d '{
    "consentCode": "DEMO",
    "internalDescription": [
        {      
          "description": "This is a demo consent-base created to show how it can be done. This text is only shown in Entur Partner.",
          "languageCode": "ENG"
        },
        {      
          "description": "Dette er en demo consent-base som viser hvordan man lager en slik. Denne tekst vises kun i Entur Partner.",
          "languageCode": "NOB"
        }
    ],  
    "orgNameSubstitutionPattern": "[ORG]",
    "terms": [
        {
          "fullDescription": "These are the full Terms of this consent-base. They may span multiple\n lines and may contain markup tags:\n##A header.\nSome **bold** text. This text can be edited via the Entur Partner interface, but only until the validFrom date is passed.",
          "languageCode": "ENG",
          "shortDescription": "Demo consent. This is the shortDescription shown in dropdowns and on mobile devices."
        },
        {
          "fullDescription": "Her kan skrives den fulle tekst for det man sier ja til når man takker ja til dette samtykket.\nMan kan skrive på flere linjer, og bruke _markup_. Teksten kan senere endres, hvis ikke validFrom er passert.",
          "languageCode": "NOB",
          "shortDescription": "Demo samtykke. Dette er shortDescription som brukes i lister og overskrifter."
        },
        {
          "fullDescription": "Tjenesten støtter også nynorsk.",
          "languageCode": "NNO",
          "shortDescription": "Demo samtykke på nynorsk."
        }
    ],
    "validFrom": "2019-09-01T00:00+00:00",
    "validTo": null
  }'


# Output: {"consentCode":"DEMO","terms":[{...

The above creates a ConsentBase for your organisation only. Note for internal developers - if supplying an Internal token, this is accessible for all organisations; use consentOwnerOrgId to limit this. The first version always has version=1, so to add a Consent:

curl -X POST \
  https://api.entur.io/customers/v2/consents/admin/consents \
  -H  "Authorization: Bearer $PARTNER_TOKEN" \
  -H  "Content-Type: application/json" \
  -d '{
    "organisationId": _,
    "consentBaseVersion": 1,
    "consentCode": "DEMO",
    "isEmailSupported": true,
    "isSmsSupported": true,
    "validFrom": "2019-09-01T00:00+00:00",
    "validTo": null
  }'


# Output: {"id":715,"consentCode":"DEMO"...