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.

🚧

In beta

Consent 2.0 is currently in beta testing. While the specification for the related One API endpoints should not change, this guide gets updated from time to time so check back now and then for more information.

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 during Q1 2023. 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) 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) 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.

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