Request profile in segment by consent export

Profile in segment by consent export

Request an export with profiles that fall into the specified segments and have consented to the particular topics via the specific channels.

Options for consent filtering

This feature supports two methods of specifying channels.

Provide single channel

This option is more automated and recommended when you're interested in consent through a single channel, either email or SMS, for all topics you've provided in the request.

Provide your desired channel in the channel_discriminator request body property.

In terms of columns, the export file contains the attribute corresponding to the channel specified in the request: Email attribute for email channel and Mobile attribute for SMS channel.

As for rows, the export file contains the consented profiles. It also contains profiles that have either not consented to receive or unsubscribed from receiving the communication via that channel (email or SMS) and the topics selected via the request parameters. These records contain blank values in Email or Mobile columns.

Provide multiple channels

This recommended option lets you export consent for multiple channels, email and SMS, in one request. It also gives you more flexibility with the export file contents.

Use the channels request body property to provide a mapping from your desired channels to the export file fields.

In the example below I'm interested in email and SMS consents to any of my topics but I also want to export the email and mobile attribute values:

{
  "section_discriminator": "usercreated.sections.europe-r6tz73a27t",
  "consent_list_discriminator": "usercreated.targets.jeans-3ayb7167e4",
  "topic_discriminators": [ "usercreated.topics.bluejeans-cbyntm8qnw", "usercreated.topics.greenjeans-cbyntm8qnw" ],
  "channels": [
    { "field_name": "EmailConsent", "channel_discriminator": "com.apsis1.channels.email" },
    { "field_name": "MobileConsent", "channel_discriminator": "com.apsis1.channels.sms" }
  ],
  "attributes": [
    { "field_name": "Email", "attribute_version_id": "1852749" },
    { "field_name": "Mobile", "attribute_version_id": "1852750" }
  ]
}

The export file for the above request contains email address in the EmailConsent column only for profiles that consented to any of the specified topics via the email channel. Same for MobileConsent and SMS channel.

The other columns, Email and Mobile, are not related to consent. They contain the email and mobile attribute values as requested via the attributes parameter.

In our example John consented to any of the topics via both, email and SMS, and Anna only via SMS.

Excluding unsubscribed profiles

You can use the exclude_unsubscribed_profiles request body parameter to skip the unsubscribed profiles from the export file. If you set it to true, then the profiles that do not currently have an opt-in or confirmed-opt-in consent to any topic from the request via any channel from the request will not be present in the export file.

More on consent types here.

Remaining export file contents

The export file always contains the export key. You can select attributes and tags to include their value as columns in the export file.

For each segments provided in the request body the export file contains a column. These columns are named after the segment names from the request body. A row contains 1 when a corresponding profile matched the segment in question. Otherwise that row says 0.

When exclude_unsubscribed_profiles is true then a subscribed column also appears in the export file. This is for internal use and should not be relied upon by your integration.

How to use

Once executed successfully, this endpoint returns a poll URL that is valid for 1 day.

Call this URL repeatedly with exponential back-off using the same authentication token as for the other APSIS One API calls. Until the result is ready, you will keep getting HTTP 404 Not Found response status code.

As soon as the export file is ready, the poll URL returns HTTP 200 OK and starts streaming a export file as a response.

The HTTP 410 Gone means that the file is no longer available or the ID used is invalid.

Compression

By default the export file is an uncompressed CSV so your code should treat it as .csv. If you prefer a compressed export, provide Accept-Encoding: gzip request header when calling the poll URL. The response will then contain Content-Encoding: gzip header and you will be able to handle the file as .csv.gz.

You can download the same export multiple times using the same poll URL with or without compression.

Additional file format support

By default the export file is a CSV and the Content-Type response header when calling the poll URL is similar to text/csv;charset=UTF-8;header=present. We also support Excel (XLSX) file format. To receive it, provide the Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet request header when calling the poll URL. The response will then contain Content-Type header with the same value.

You can download the same export multiple times using the same poll URL in different file formats.

Limits

Receiving HTTP 413 Payload Too Large from this POST request usually means that the request body contains a number of topics, attributes and/or tags that is currently not supported.

More information

Accept-Encoding request header

Accept request header