Overview

Initiate

The initiate step begins the process of bulk import. Valid requests receive an HTTPS 200 - OK response including an access token. The access token is required to stage, execute, and retrieve the status of the bulk import. It is also used for retrieving records that failed to import.

This token is only active for six hours before it expires. Once expired, it cannot be used again for staging, executing, retrieving the import status or exceptions.

Using Match Criteria for Imports

MatchCriteria is an optional parameter that serves as a matching identifier when updating profiles. It can be used in scenarios where you want to update profiles using other unique identifiers instead of the ProfileId. Currently, AlternateIdType is the only supported match criteria. MatchValue must be provided with the match criteria. If MatchCriteria is not provided, the Import API will match on the ProfileId when performing updates. If ProfileId is not found, a new profile is created.

The Bulk Import API also supports a set of refresh parameters that allows you to remove any existing piece of information from user profiles. When its value is set to true, information not included in the import request will be deactivated on the profile.

When you set the RefreshContacts parameter to true, the following behavior is applied:

Any existing contact element that is not included in your import request is deactivated.
Any preferences associated with it are archived if PreservePreferences flag is set to false.
All matching contact elements are updated with the information specified in your request.
Any existing information not included in the import request will not be updated. For example, if IsMobile or IsDefault property is not included in your request, it will remain intact.

Deleting Profiles using Bulk Import API:

To initiate a bulk deletion of profiles, set the value of the "ImportAction" parameter to "Delete" in your Initiate request, as shown below.

Plain text

{
  "Name”: “Weekly Leads",
  "DataStageDuration":"3",
  "ImportAction": "Delete",
  “MatchCriteria”: “AlternateIdType”,
  “MatchValue”: “SalesforceId”
}

Key points to remember:

To perform a delete operation using the Bulk API, the API user must also have the “Delete Profiles” permission enabled within their user group.
Upon execution, all matching profiles specified in the request are completely removed from the system.
If you specify the MatchCriteria, profiles that include the matching AlternateIdType and the AlternateId value specified for that Type are removed from the system.
The Bulk API will mark the records as Validation Failed if the AlternateId value does not match the Type specified.
You can use the optional ReasonCode property to store the reason for deletion for audit purposes.

Header Parameters

Authorizationstring Required

Authorization token

Content-Typestring

Path Parameters

clientIdstring Required

This is your organization’s MyPreferences account Id. A 404 is returned if this value is invalid.

Body Parameters

Namestring Required

Name associated with the bulk import operation.

DataStageDurationnumber

Determines the number of days for retaining staged data before it is permanently deleted. If not specified, it defaults to 3 days. The staging duration cannot exceed 10 days. Range: inclusive between 0 and 10.

Maximum

ImportActionstring

Specifies whether to add or delete profiles. Supported values are "Add" and "Delete".

MatchCriteriastring

An optional parameter that can be used as a matching identifier in the absence of a Profile ID. Currently, AlternateIdType is the only supported match criteria.

MatchValuestring

TypeName associated with the match criteria. Specify the name of an AlternateIdType configured in your account since AlternateIdType is the only supported Match Criteria.

RefreshAlternateIdsboolean

If set to true, existing AlternateIds that are NOT included in the import will be deactivated. Default value is false.

RefreshContactsboolean

If set to true, existing profile contact elements that are NOT included in the import will be deactivated along with any preferences associated with them. Default value is false.

RefreshCustomFieldsboolean

If set to true, existing CustomFields that are NOT included in the import will be deleted. Default value is false.

RefreshGroupsboolean

If set to true, existing Groups that are NOT included in the import, will be deactivated. Default value is false.

RefreshTagsboolean

If set to true, existing Tags that are NOT included in the import, will be deleted. Default value is false.

AllowPriorConsentsboolean

A boolean flag, when set to true, permits adding an older version of a consent to the profile, provided that a more recent version of the consent is not already present.

Response

200

Object

The request was successfully processed.

Response Attributes

AccessTokeninteger

Token used to stage, execute, and retrieve import status and failed records.

Statusstring

Returns the current state of the import. 'Initiated', 'Staging', 'Queued', 'Processing', 'Completed', or 'Failed'.

Expiresstring

Date when the access token will expire. Default expiration time is 12 hours.

Namestring Required

Name associated with the bulk import operation.

DataStageDurationinteger

Maximum

ImportActionstring

Specifies whether to add or delete profiles. Supported values are "Add" and "Delete".

MatchCriteriastring

An optional parameter that can be used as a matching identifier in the absence of a Profile ID. Currently, AlternateIdType is the only supported match criteria.

MatchValuestring

TypeName associated with the match criteria. Specify the name of an AlternateIdType configured in your account since AlternateIdType is the only supported Match Criteria.

RefreshAlternateIdsboolean

If set to true, existing AlternateIds that are NOT included in the import will be deactivated. Default value is false.

RefreshContactsboolean

If set to true, existing profile contact elements that are NOT included in the import will be deactivated along with any preferences associated with them. Default value is false.

RefreshCustomFieldsboolean

If set to true, existing CustomFields that are NOT included in the import will be deleted. Default value is false.

RefreshGroupsboolean

If set to true, existing Groups that are NOT included in the import, will be deactivated. Default value is false.

RefreshTagsboolean

If set to true, existing Tags that are NOT included in the import, will be deleted. Default value is false.

AllowPriorConsentsboolean

A boolean flag, when set to true, permits adding an older version of a consent to the profile, provided that a more recent version of the consent is not already present.

400

Object

The request was invalid and cannot be processed. This may be a result of a malformed request. You must update the request before trying again.

401

Object

Authentication credentials are missing or incorrect. You must verify your ClientId, UserId, and Authorization Scheme before trying again.

403

Object

The authentication credentials were insufficient to grant access to the requested resource. In most cases, your user may not have the appropriate permissions to access the requested resource. Verify User Group permissions for your user before trying again.

404

Object

The requested resource cannot be found. Most errors in this category are returned when a resource specified on the URL path is not found. In certain instances, it is also returned when a parameter specified in the request body is also not found. See error description for more details.

503

Object

The server is unable to handle your request due to a temporary condition. You must delay your request for some time before trying again. Notify PossibleNOW Support if it’s a continuous occurrence.

Sections

Initiate

Using Match Criteria for Imports

Deleting Profiles using Bulk Import API:

Header Parameters

Path Parameters

Body Parameters

Response

Response Attributes

What made this section unhelpful for you?

Response

What made this section unhelpful for you?