Configure destinations for StackAdapt

StackAdapt is a programmatic advertising platform for running campaigns across display, native, video, connected TV, audio, and digital out-of-home channels. Send customer profiles and audiences to StackAdapt for audience targeting.

You can configure Amperity to send customer profiles and audience membership to a StackAdapt CRM audience using the StackAdapt GraphQL API. The email field is required and is the only audience primary key. Amperity sends email addresses and every other value as they appear in Amperity; it does not hash or normalize them. Rows with no email address are skipped and counted as failed.

Amperity matches column names to StackAdapt profile fields without regard to case:

Amperity column

StackAdapt profile field

amperity_id

external_id

email

email

first_name

first_name

last_name

last_name

phone

phone

address

address

city

city

state

state

country

country

postal_code

postal_code

timezone

timezone

birth_date

birth_date, sent as a date

Every other column is sent as a custom field named after the column. Its type follows the column’s type: dates and datetimes are sent as dates, integers and decimals as numbers, booleans as booleans, and everything else as text.

Amperity does not send blank or empty values. A field that is blank in Amperity is left out of the profile that Amperity sends, rather than sent as an empty value.

Note

This destination uses the StackAdapt GraphQL API .

Beta

The StackAdapt connector is in beta. Contact your Amperity representative to learn more.

Note

Amperity sends only what changed since the previous run. Each run sends, in order:

  1. Profiles whose fields changed, without changing their audience membership.

  2. Customers who left the audience, with an exit action for the CRM audience.

  3. Customers who joined the audience, with an enter action for the CRM audience.

The List name is both the name and the ID of the StackAdapt CRM audience. StackAdapt has no separate step for creating an audience, so the CRM audience is created from this name the first time Amperity sends to it. The first run, and the first run after the list name changes, sends every customer. When nothing changed since the previous run, Amperity sends nothing and reports every row as succeeded.

Amperity splits each run into several requests, keeps only a few requests in progress at a time, and limits how quickly it sends them.

Important

Amperity treats each request as a whole and does not report a result for each profile: an error in StackAdapt’s response fails the whole request. A run reports success when every request succeeds; Amperity does not wait to confirm that the profiles appear in StackAdapt.

A failed request fails the run. Requests that succeeded earlier in that run stay applied, so a failed run can leave some profiles updated.

  • A rejected API key, or an error that StackAdapt reports inside an otherwise successful response, fails the run without a retry, because the same request would fail again. For a rejected API key, ask your StackAdapt account team to check the API key. For any other error, the run shows StackAdapt’s error message; check the Advertiser ID and External provider settings on the destination.

  • A request that times out, exceeds the StackAdapt rate limit, or fails because StackAdapt is unavailable is retried. If it still fails, or if StackAdapt returns any other HTTP error, Amperity retries the whole run every 10 minutes for up to an hour.

Get details

Review the following details before configuring credentials for StackAdapt and before configuring Amperity to send customer profiles and audiences to StackAdapt.

Detail 1.

Credential settings

API Key

Required

The StackAdapt GraphQL API token for your StackAdapt account. The token must have write access to the advertiser that audiences are sent to.

StackAdapt does not offer a self-serve page for API tokens. Ask your StackAdapt account team for a GraphQL API token with write access to the advertiser that Amperity sends audiences to.

Detail 2.

Required configuration settings

Advertiser ID

Required

The numeric ID of the StackAdapt advertiser that audiences are sent to. Find it in the StackAdapt UI, or ask your StackAdapt account team. The connection test fails if the API key cannot see this advertiser, and lists the advertisers that the API key can see. It also fails if the API key can see the advertiser but cannot write to it.

Audience primary key

Required

The primary key for the audience. Set to “email”.

External provider

Required

The provider identifier that StackAdapt uses for Amperity. The default value is “amperity”. Change this only if your StackAdapt account team gives you a different value. If StackAdapt rejects the value, the run fails and shows the error from StackAdapt; ask your StackAdapt account team for the value to use.

List name (Required at orchestration)

The name of the StackAdapt CRM audience. Amperity creates the CRM audience from this name the first time it sends to it, and uses the same name as the CRM audience’s ID.

Important

Changing the list name sends to a new CRM audience. Amperity sends every customer to the CRM audience with the new name on the next run. The CRM audience with the old name stays in StackAdapt, and Amperity no longer updates it.

Detail 3.

Optional configuration settings

Profiles are opted in to marketing

Marks every profile in a send as opted in to marketing. Amperity sends this as one value for the whole send, so individual profiles cannot be marked differently. Leave this setting off unless the query or segment only returns customers who have consented to marketing. This setting is off by default.

Detail 4.

A query that outputs the fields to send to StackAdapt. The email field is required. Columns that match a StackAdapt profile field, such as first_name or postal_code, update that field; every other column is sent as a custom field.

Configure credentials

Configure credentials for StackAdapt before adding a destination.

An individual with access to StackAdapt should use SnapPass to securely share “API Key” details with the individual who configures Amperity.

To configure credentials for StackAdapt

Step one.

From the Settings page, select the Credentials tab, and then click the Add credential button.

Step two.

In the Create credential dialog box, do the following:

  1. From the Plugin dropdown, select “StackAdapt”.

  2. Assign the credential a name and description that ensures other users of Amperity can recognize when to use this destination.

Step three.

The settings that are available for a credential vary by credential type. For the “stackadapt” credential type, configure settings, and then click Save.

API Key

Required

The StackAdapt GraphQL API token for your StackAdapt account. The token must have write access to the advertiser that audiences are sent to.

StackAdapt does not offer a self-serve page for API tokens. Ask your StackAdapt account team for a GraphQL API token with write access to the advertiser that Amperity sends audiences to.

Add destination

Use a sandbox to configure a destination for StackAdapt. Before promoting your changes, send a sample audience, and then verify the results in StackAdapt. After verifying the end-to-end workflow, push the destination from the sandbox to production.

To add a destination for StackAdapt

Step one.

Open the Destinations page, select the New destinations button, and then select Orchestration.

Add destination

To configure a destination for StackAdapt, do one of the following:

  1. Click the row in which StackAdapt is located. Destinations list alphabetically and you can scroll up and down the list.

  2. Search for StackAdapt. Start typing “stack”. The list filters to show only matching destinations. Select “StackAdapt”.

Step two.

Select the credential for StackAdapt from the Credential dropdown, and then click Continue.

Tip

Amperity validates the connection when the destination is saved. If the connection cannot be validated, an error is shown and the destination is not saved.

The connection test checks that the API key can see the advertiser in the Advertiser ID setting and has write access to it.

Step three.

In the “Destination settings” dialog box, assign the destination a name and description that ensures other users of Amperity can recognize when to use this destination.

Configure business user access

By default a destination is available to all users who have permission to view personally identifiable information (PII).

Enable the Admin only checkbox to restrict access to only users assigned to the Datagrid Operator and Datagrid Administrator policies.

Enable the PII setting checkbox to allow limited access to PII for this destination.

Use the Restrict PII access policy option to prevent users from viewing data marked as PII anywhere in Amperity and from sending data to downstream workflows.

Step four.

Configure the following settings, and then click “Save”.

Advertiser ID

The numeric ID of the StackAdapt advertiser that audiences are sent to. Find it in the StackAdapt UI, or ask your StackAdapt account team. The connection test fails if the API key cannot see this advertiser, and lists the advertisers that the API key can see. It also fails if the API key can see the advertiser but cannot write to it.

Audience primary key

The primary key for the audience. Set to “email”.

External provider

The provider identifier that StackAdapt uses for Amperity. The default value is “amperity”. Change this only if your StackAdapt account team gives you a different value. If StackAdapt rejects the value, the run fails and shows the error from StackAdapt; ask your StackAdapt account team for the value to use.

List name (Required at orchestration)

The name of the StackAdapt CRM audience. Amperity creates the CRM audience from this name the first time it sends to it, and uses the same name as the CRM audience’s ID.

Important

Changing the list name sends to a new CRM audience. Amperity sends every customer to the CRM audience with the new name on the next run. The CRM audience with the old name stays in StackAdapt, and Amperity no longer updates it.

Profiles are opted in to marketing

Marks every profile in a send as opted in to marketing. Amperity sends this as one value for the whole send, so individual profiles cannot be marked differently. Leave this setting off unless the query or segment only returns customers who have consented to marketing. This setting is off by default.

Step five.

After configuring this destination users may use:

  • Orchestrations to send query results

  • Orchestrations and campaigns to send audiences

Step six.

Validate the audience with StackAdapt by using a sample audience with a very small membership. For example: 10 or 100 members or the minimum audience size recommended by StackAdapt. Send the sample audience to StackAdapt and verify the sample audience is correct in StackAdapt. Make adjustments if necessary. Only send full audiences after validation is complete.