One API integration FAQ for Consent 2.0

This page provides answers for the frequently asked questions regarding Consent 2.0 and aims to help you understanding the changes in your integrations with APSIS One API required when migrating your account.

How soon do I need to migrate to Consent 2.0?

Consent 1.0 endpoints were deprecated during 2022 and reached end of support on the 1st of June 2023. This means that that part of your integration to APSIS One is already not covered by our Support and that we no longer can ensure to be able to fix issues that might arise from your integration using these endpoints.

The sooner you're able to do this straightforward change, the sooner you will be able to enjoy the benefits of the new Consent 2.0.

What happens if I don't switch to Consent 2.0 endpoints?

If you are not able to migrate, then we will not be able to migrate your account to Consent 2.0 without breaking your integration.

Since the entire legacy consent management solution ("Consent 1.0") is reaching end-of-support after the 30th of April your account's consent management will after that day no longer be covered by our Support and we will no longer be able to ensure to fix potential issues that might arise.

It is therefore of outmost importance that you schedule the migration of your API integration to be completed before this date.

How is my account migrated to Consent 2.0?

First, we will ask you to switch your integrations with APSIS One API from Consent 1.0 endpoints to Consent 2.0 endpoints.

When you confirm that you've switched, we will block Consent 1.0 endpoints in APSIS One API for your account. This prevents execution of the legacy code not aware of Consent 2.0 against your APSIS One account.

Finally, we will perform a data migration to Consent 2.0 for your APSIS One account.

When the data migration is complete, all the Consent 2.0 features become available on APSIS One platform and Consent 2.0 endpoints in APSIS One API switch to the new behavior.

Will switching to Consent 2.0 endpoints break my Consent 1.0 integrations?

No. While your account is operating in Consent 1.0 mode, using Consent 2.0 endpoints in APSIS One API has the same effect as using Consent 1.0 endpoints.

I have multiple integrations with APSIS One API. Do I have to switch them all at once?

No. You can switch your integrations individually and deploy the changes independently. You are also able to switch the scenarios described below individually.

How do I switch from Consent 1.0 endpoints to Consent 2.0 endpoints?

In order to understand the differences between Consent 1.0 and 2.0 in APSIS One API let's look at the usual integration scenarios and discuss how to achieve them with both Consent releases.

The tables in this section aim to provide a mapping between Consent 1.0 and Consent 2.0 endpoints in APSIS One API.

Getting a list of available topics

Consent 1.0Consent 2.0
1. Call Get consent lists to find out what consent lists are available in your section.

2. Call Get topics to see the topics within a consent list of choice.
1. Call Get topics (version 2) to get all topics available in your section (across all consent lists).

This scenario is simplified in the API thanks to this change:

📘

New in Consent 2.0: Consent lists no longer exposed in APSIS One API

While consent lists still remain a UI concept, they are no longer a consideration in the API with Consent 2.0. Note that in APSIS One UI we recently renamed consent lists to folders and topics to subscriptions.

Identifying topics with the same names across folders

If your folder (formerly consent list) and topic structure is such that your topic names are not unique within your section then you may run into a problem identifying them using just Get topics (version 2) endpoint. In such case there are two solutions:

  1. Go to APSIS One and edit your subscriptions to change the names of the topics. This way the information provided by Get topics (version 2) should be sufficient to uniquely identify the topics.
  2. You my have reasons not to rename your topics. The model returned by Get topics (version 2) contains folder_discriminator. Use it with Get all topic folders to identify the folders to which your topics belong.

Providing consent

Consent 1.0Consent 2.0
1. Call Create a consent to provide a consent for an address over a specific channel. This can be an opt-in consent to a specific topic within a specific consent list in a specific section or an opt-out consent to a specific topic, a whole section or the whole account.

2. After creating an opt-in consent, call Subscribe profile to topic to assign a profile to a topic.
At the time when you performing the switch discussed here your profiles have been or are being created using Consent 1.0. For such profiles it is required that an attribute value exists for an attribute corresponding to the channel over which you want to create a consent. So for example if you want to create an email consent a profile needs to have an attribute value set for Email attribute. This requirement will be lifted for profiles created when your account is fully migrated to Consent 2.0.

As a prerequisite you'll need to update your integrations to ensure the above. This is usually achieved by updating your configuration for Request profile import or using Set attributes on a profile.

1. Call Create a consent (version 2) to provide a consent for a profile over a specific channel. This can be an opt-in or opt-out consent to a specific topic.

This scenario is simplified in the API thanks to this change:

📘

New in Consent 2.0: Consent is given on a profile level

In Consent 1.0 consents are created on an address level. An example of an address is [email protected]. For this reason an additional action of subscribing a profile to a topic is also needed.

In Consent 2.0 consents are created on a profile level. In APSIS One profiles are identified by a keyspace and profile key. For example, [email protected] can be a profile key in com.apsis1.keyspaces.email keyspace. No need to subscribe profiles to topics anymore.

But there's also another change we're introducing in order to improve performance:

📘

New in Consent 2.0: No support for consent hierarchy

In Consent 2.0 consents are created on a topic level only. We no longer support creating opt-out consents on section or an account level.

For this reason you are no longer able to use Remove section opt-out endpoint.

Checking existing consents

Consent 1.0Consent 2.0
1. Call Get opt-in consents to get all topics with opt-in consents for an address.

2. Call Get all topic subscriptions for a profile (in development) (deprecated) to see topics to which a profile is assigned.
1. Call Get consents (version 2) to get topics with consents of specific types for a profile.

This scenario is simplified thanks to the changes already mentioned in the previous scenarios.

Changing profile email or phone number

The APSIS One platform enables your profiles to provide consent to receive communication from you. Consent is created using a selected communication channel: email, SMS or both. Each of these channels has a corresponding profile attribute: email and mobile, respectively. So when a profile consents to receive information from you over the email channel, the platform will use their primary email address attribute when sending emails.

As long as your account uses Consent 1.0, a consent is bound to the address. This changes in Consent 2.0, where consent is created on the profile level.

Consent 1.0Consent 2.0
1. Call Set attributes on a profile to change their email or phone number

2. Use Create a consent with the opt-out type for the original email or phone number

3. Use Create a consent with the opt-in type for the new email or phone number
1. Call Set attributes on a profile (version 2) to change their email or phone number (we will refer to them as addresses from now on)

Set attributes on a profile (version 2) automatically moves consent from the original address to the new one while your account uses Consent 1.0 and will work correctly when your account gets migrated to Consent 2.0

This scenario is simplified thanks to the changes already mentioned in the previous scenarios.

Importing profiles

Consent 1.0Consent 2.0
Affected features:

- Request profile import
- Request profile import (version 2)

1. Call Get consent lists to find out what consent lists are available in your section.

2. Provide consent list discriminator when using any of the affected features.

3. Consent is given on the address level. For each consent you want to import, provide that address in the import file and use address field selector request body property to point to it.
The Get consent lists feature is not supported in Consent 2.0.

The consent list discriminator parameter is deprecated for all of these import endpoints. Update your integrations to stop providing the consent list discriminator parameter in the requests.

Consent is given on the profile level in Consent 2.0.

The address field selector parameter is deprecated for all of these import endpoints. Update your integrations to stop providing the address field selector parameter in the requests.

Profile import (version 1) is deprecated, we suggest switching to new Profile import (version 2) endpoint.

The above import features are affected due to the changes already mentioned in the previous scenarios.

Exporting profiles

Consent 1.0Consent 2.0
Affected features:

- Request duplicate profile in segment by consent export
- Request profile in segment by consent export
- Count profiles in segment by consent

1. Call Get consent lists to find out what consent lists are available in your section.

2. Provide consent list discriminator when using any of the affected features.
The Get consent lists feature is not supported in Consent 2.0.

The consent list discriminator parameter is deprecated for all of these export endpoints. Update your integrations to stop providing the consent list discriminator parameter in the requests.

The above export features are affected due to the changes already mentioned in the previous scenarios.

Common errors

No address to consent

If you get the following error message from Create a consent (version 2) then your profile does not have a value for the attribute corresponding to the channel over which you want to create a consent. Ensure your profile has an Email (or Mobile) attribute set before attempting to create consent over the Email (or SMS) channel.

{
  "status": 400,
  "title": "No address to consent",
  "type": "https://developer.apsis.com/page/error-codes#aud-1601",
  "status_code": 400
}

📘

Have questions?

Contact [email protected] to learn more