# Administrating consents

## Overview
The consents API allows you to create and administrate terms for consent, and store your customers' given consents to these terms.

## Before you begin
- Your client needs a partner access token to use this API, see the [authentication guide](/docs/authentication#partner-apis).
- Your client needs to be assigned the role `Klientrolle - Samtykkeklient - Administrator`.

## Terminology
- **Consent base**: contains the legal terms for consent, in all the languages you define.
- **Consent**: connects your organisation to the consent base.
- **Given consent**: The actual consent given by the customer.

## State handling and versioning
Consent bases and consents have state handling, using the fields validFrom and validTo. The three different states are as follows:
- **Draft**: If `validFrom` is not set or set to a time in the future.
- **Active**: If `validFrom` is in the past and `validTo` is not set or set to a time in the future.
- **Inactive**: If `validTo` is in the past

Consent bases and consents can be updated as long as they’re in the draft state, using `PUT` endpoints. After they’re active, there are only a few fields that can be changed using the `PATCH` endpoints.

Each consent base and consent have a version number. If you wish to do changes after the consent base or consent is active, you have to create a new version. Versions of the same entity cannot be active at the same time, so `validFrom` and `validTo` cannot overlap.

## Administrating consent terms
See the [consents admin API](/apis/customers/consents-admin) for full documentation on how to administrate consent bases and consents

### Create a consent base
When creating a new consent base, it requires a code unique within the system for later identification. The maximum length of this code is 20 characters, and we recommend that it includes the codespace for your organisation to avoid conflicts. E.g. use  “ENT_INFO_SMS” for a consent base containing terms for receiving information about a journey on sms.

To create a new consent base, use

::endpoint[consents/addConsentBase]

The response from creating the consent base will contain a version number. Use the version number when updating the consent base later and when creating consents.


### Create consent
After you’ve created your consent base, you need to create the consent. This requires the consent code and the version number of the consent base you just created.

::endpoint[consents/addConsent]

### Updating consent base
Consent bases are versioned. If you want to update the terms for a consent base when it is active, you have to create a new version.

The `validTo` and `validFrom` for two versions of a consent base cannot overlap.

After you’ve created a new version of a consent base, you need to create a new consent and collect new given consents from the customers.

Create a new version of the consent base using following endpoint:

::endpoint[consents/createNewVersionOfConsentBase]


## Collect given consents from customers
When consents have been created for you organisation and the consents are active, you can start collecting given consents from customers in your client.

See [the consents client API](/apis/customers/consents-client) for documentation on how display consent terms and collect given consents