Request profile data export

Profile Data Export

Request profile data export. The export can be requested for specific segment or based on event dates and the data can include attributes, tags, events and topic state.

When segment_filter request parameter is provided, only the profiles from the selected segment are exported, otherwise the export file contains all profiles on the account.

Only the attributes, tags and events explicitly declared in the corresponding request parameters are exported. Even though you're only interested in events, you still need to request at least one attribute or tag for the profiles to even show up in the export file.

For events use start_at (mandatory) and end_at parameters to specify the time period for the exported events. When end_at is not provided in a request, it is defaulted to one week after start_at.

How to use

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

Call this URL repeatedly with exponential backoff 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 report 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.

In rare cases when the export processing has failed, calling the poll URL returns HTTP 503 Service Unavailable. If that happens, please request a new export with the POST endpoint.

Compression

By default the report file is an uncompressed JSON so your code should treat it as .json. 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 .json.gz.

Export file

The export file is in the JSON format.

On the top level there is a JSON dictionary with profiles. The keys in this dictionary are profile export keys.

For each profile, export file contains sections JSON dictionary. The keys in this dictionary are section IDs. Use "Get sections" endpoint of this API to map these IDs to the specific section definitions.

Each section contains both, attributes and tags, inside the attributes JSON dictionary. The keys in this dictionary are IDs of the attributes and tags. Use "Get attributes" and "Get tags" endpoints of this API to map these IDs to the specific attribute and tag definitions. The objects in this dictionary have the following properties:

  • value

    The data type of this property depends on the attribute type. For tags the value is always null and the sheer fact that the attribute exists in the export file means that the corresponding profile was tagged with this particular tag.

If any event type has been requested for a specified section, the corresponding section object also contains events JSON array. Each object in this array represents a single event and contains the following information:

  • correlationId

    ID for the event assigned by the event source (Email Tool). The same correlationId value may be repeated if the event has been sent multiple times due to a retry logic.

  • sourceEventTime

    Time of the event in milliseconds since Unix epoch reported by the event source. This feature was introduced at the beginning of 2020 so events prior to that may have event_time equal to 0. The value of 0 is also possible when the event source did not specify the event time.

  • typeId

    Event version ID. Use "Get events" endpoint of the API to map these IDs to the specific event definitions.

  • createdAt

    Time of the event in milliseconds since Unix epoch as seen on Audience server when it received the event.

  • data

    Data specific to a particular event type as defined by "Get events" endpoint of the API

Limits

Maximum export time window for events is three months. Validated when requesting an export.

The export file can include up to 75 attributes and 25 tags. Validated when requesting an export.

Pending export count limit. If reached, HTTP 429 Too Many Requests is returned.

Maximum file size limit. If you request an export with very large data set, i.e. many attributes or large time window that results in many events, you may receive a status of error when attempting to request or download an export. You can then retry the export request aiming at a smaller data subset.

Usually the errors in processing are caused by:

  • using too complex segments
  • providing too many attributes and/or tags
  • providing too many event types

More information

Video guides

Language
Authentication
Bearer
URL
Click Try It! to start a request and see the response here!