Request profiles in segment by consent report (beta)

Beta

This is a new feature in APSIS One API since June 2021 and we are still keeping a close look on performance and potential issues. Please report any feedback to [email protected].

Profiles in Segment by Consent Report

Request a report 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 report 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 report 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 report file contents.

Use the channels request body property to provide a mapping from your desired channels to the report 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 report 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.

exportKeyEmailConsentMobileConsentEmailMobile
e1ea6ded-61e7-494f-8221-2eb5cf3b2b4d[email protected]41726480987[email protected]41726480987
d7cdbdf2-b899-4abd-829d-080b93bbc7b7[email protected][email protected]48765320019
3ff64da9-c436-49df-872d-f40e4a4dee7046895123092[email protected]46895123092
31e80abd-b890-461f-9e30-e41c87f4d2ff[email protected]48700000013

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. If you set it to true, then the profiles who have not consented to any topic from the request or have unsubscribed from all topics in the request will not be present in the report file.

Remaining report file contents

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

For each segments provided in the request body the report 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.

How to use

Once completed 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 report 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 report file is an uncompressed CSV so your code should treat it as .csv. If you prefer a compressed report, 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 report multiple times using the same poll URL with or without compression.

Additional file format support

By default the report 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 report 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

Language
Authentication
Bearer
JWT
URL