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.

🚧

Under construction

Consent 2.0 is currently in development and we're constantly refining all the changes and processes mentioned on this page so all of this is subject to change

How to integrate with Consent while 2.0 is in development?

While Consent 2.0 is under development and you would like to create new integrations with the APSIS One platform through APSIS One API, we suggest that you have two options.

If you urgently need to integrate then simply use Consent 1.0 endpoints. You will need to switch to Consent 2.0 endpoints when your account is being migrated. In this scenario you may be duplicating the work.

An alternative that avoids added cost is to defer the integration efforts until Consent 2.0 is available in APSIS One and your account gets it. You may not want to wait that long though.

When will I be asked to migrate to Consent 2.0?

Currently we're planning to deliver Consent 2.0 and start with the account migrations end of Q3 2022. Note that this estimate can change.

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. We will give enough time for you to feel comfortable switching.

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) (beta) 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.

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) (beta) 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) (beta) 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.

Importing and exporting profiles

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

Provide consent list discriminator when using any of these APSIS One API features:

- Request profile import
- Request profile import (version 2) (in development)
- Request duplicate profile in segment by consent export
- Request profile in segment by consent export
- Count profiles in segment by consent
The Get consent lists feature is not supported in Consent 2.0.

The consent list discriminator parameter is deprecated for all of these import and export endpoints.

Update your integrations to stop providing the consent list discriminator parameter in the requests.

The above imports and exports are affected due 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.

Common errors

No address to consent

If you get the following error message from Create a consent (version 2) (beta) 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