Profiles

Use case examples

Note, all endpoints in the customers api requires access tokens.

Look up a profile

curl --request GET \
  --url 'https://api.entur.io/customers/v2/profiles/<customerIdentifier>' \
  --header 'Authorization: Bearer <token>'

Create a new profile

curl --request POST \
  --url 'https://api.entur.io/customers/v2/profiles/' \
  --header 'Authorization: Bearer <token>' \
  --data '{"firstName": "Ola", "surname": "Nordmann", "email": "ola@nordmann.org", "languagePreference": "NO", "createdBy": "test", "createdByChannel": "test", "organisationId": 1, "password":"abcD123"}'

Search for profiles

Search will return the profiles that match all search parameters. To see all available search parameters, see the api documentation.

curl --request GET \
  -- url = 'https://api.entur.io/customers/v2/profiles?email=<EMAIL>&surname=<NAME>' \
  -- header 'Authorization: Bearer <token>'

Concepts within profiles

This guide describes basic concepts within the customers/vX/profiles api.

Customers

A customer is a person or legal entity who has created a profile within the Customers api to gain advantages and track journeys within the Entur sales system. Each profile is connected to a specific organisation, and no organisation can gain profile data connected to a different organisation (i.e. NSB cannot view information about Entur profiles).

A profile is uniquely identified by its customerNumber. This references is used throughout the Entur sales system to connect a profile to its purchases, consents, loyalty programs, contact with customer support, etc. A profile can also be uniquely identified with the combination of customerRef and organisationId. CustomerRef can be set when creating the profile, and can be used to hold an external reference originating in the partner systems.

Temporary profiles

Temporary profiles are used with a subsection of the customers api; /profiles/temporary. In addition, temporary profiles can be included in customer search (/profiles/customers/includeTemporary=true). All domains are allowed to create and manage temporary profiles.

Temporary profiles are used to contain customer information that is necessary for a specific journey and/or ticket, when the customer does not wish to register a permanent profile. A temporary profile must have an expiration date; typically the deadline for applying for a refund or replacement tickets. All provided parameters, including expiration date, are updatable. After the profile is expired, all customer information is deleted and is not recoverable. Temporary profiles have restricted usage within the Customers api. A temporary profile can have consents, postal addresses and preferences, but not ecards or loyalty programs. A temporary profile can be converted to a permanent profile if done before the profile expires.

Authentication and authorization

Access controls

All of the customer endpoints are restricted by Auth0. This means that all requests must have an Authorization: Bearer <JWT-token> header.

This header is acquired from auth0, using service-to-service authentication. This will generate an access token with your organisation identifier:

curl --request POST \
  --url 'https://partner.entur.org/oauth/token' \
  --header 'content-type: application/json' \
  --data '{"grant_type":"client_credentials","client_id": "yourClientCredentials","client_secret": "yourClientSecret","audience": "https://api.entur.io"}'

Access restrictions

We expect communication via a service, not directly from a front-end application. To this end, we've set the CORS restrictions so you can't connect directly to the API from a browser (except from these pages).

The Customers APIs all check that the current client has the necessary rights before allowing access to customer data. In practice, this means that a client with a Partner-JWT-token for an organisation will only ever have access to customers in that organisation. If you try to access a customer you're not entitled to see, you will get a 404 response, as if the customer didn't exist.

API Versioning

Deprecation

The current version of the Customers API (at time of writing, v2) supports the features of the previous version (with a caveat, see below).

Methods and endpoints marked as deprecated in this version will be removed in the next version and should not be used in new code.

Migration from customers-v1 to customers-v2:

While we have strived to maintain backwards compatibility, the handling of consents have changed quite a bit, primarily due to GDPR. To make sure this is noted by the clients, we've moved the legacy consent model from /customers/v1/consents to /customers/v2/consents/v1 .

We recommend using the customers/v2/consents API going forward, as this is actively being developed.