Register a purge contacts API task

Abstract

How to register contact data purge tasks with the xConnect purging tool Web API.

You can use the xConnect data purge Web API to remove unwanted data from your contacts. To do this, you must register a data purge task.

To register a task:

  • Use the following API:

    <instance>/sitecore/api/datatools/purge/tasks/contacts

    The successful task registration request returns the task ID used for status monitoring, for example:

    {
        "TaskId": "049cd8b3-b120-4949-a42f-cdc2fe4f3086"
    }

Parameters

The following describes the POST parameters that you can send to the Web API to register a data purge task:

Parameter

Optional

Default

Type

Description

BatchSize

Yes

100

Integer

The extraction batch size of contacts.

The BatchSize system parameter controls the amount of data extracted from the collection database for each cursor read.

Important

Use a small batch size for the purging process to not overload the system too much, and so it can cancel tasks with less impact. Task cancellation is not an immediate process and does not cancel an ongoing batch.

DefaultSplitItemCount

Yes

100

Integer

Contact data extraction cursor split count.

The DefaultSplitItemCount system parameter controls the split process of contact data extraction.

ExpiresAfterHours

Yes

24

Integer

The expiration of the task in the final state.

The final task status is either successful or failed and removed from the system after the expiration period.

CutoffDays

No

-

Nullable Integer

The last contact activity must be greater or equal to the specified amount of days.

The CutoffDays parameter specifies the number of days the contact is not interacting with the brand.

The data extraction process finds contacts based on its LastModified value compared to the CutOffDays parameter. The LastModified date-time reflects the last interaction of the contact.

StartPercentile

Yes

Null

Nullable Double

The start sampling range value. The range restriction (0…1).

The percentile range specifies the subset of data to extract. Use this parameter to perform the purging in small batches to avoid stressing the system too much.

The data extraction process finds contacts based on the percentile range and the CutOffDays parameter, which is a required parameter when using a percentile range.

EndPercentile

Yes

Null

Nullable Double

The end sampling range value. The range restriction (0…1).

The percentile range specifies the subset of data to extract. Use this parameter to perform the purging in small batches to avoid stressing the system too much.

The data extraction process finds contacts based on the percentile range and the CutOffDays parameter, which is a required parameter when using a percentile range.

Conditions

Yes

""

String

List of condition names. Multiple conditions run with the AND logical operator.

The Conditions parameters let you specify custom condition keys that must be used to identify contacts for purging. You must register custom conditions in the Cortex Processing Engine.

You delimit Conditions IDs with a comma.

The filtering with conditions is performed in-memory, not at the database level. If the contact passes all the conditions, then the data purge tool can purge the contact.