Skip to main content

StackAdapt

Updated

Connect StackAdapt to Avid to push your donor audience segments to StackAdapt as CRM Audiences for ad targeting, and to pull StackAdapt campaign and delivery data into Avid Insights reporting. One connection enables both. Audience syncs run on demand: Avid uploads data to StackAdapt when you trigger a Pathway, not on a schedule.

Use this article when

  • You need to connect StackAdapt to Avid for the first time.
  • You need to reconnect or update an existing StackAdapt connection.
  • You want to send an Avid audience segment to StackAdapt for ad targeting.
  • You want StackAdapt campaign performance data to appear in Avid Insights reporting.

Applies to

Requirement Details
Avid plan Insights plan or Trial. Pathways is not available on the Benchmarks plan. If you do not see Pathways in the sidebar, contact your Account Manager or submit a support ticket.
StackAdapt account API access to your StackAdapt account. You will need a GraphQL Public API key, which you request from your StackAdapt account team.
Avid permission Access to Settings > Connections. Using Pathways also requires the pathways.edit or direct_mail.edit permission.
Time estimate About 5 minutes once you have your API key.

Permission matrix

Role (StackAdapt) Required access What it enables in Avid Where to verify
API access A GraphQL Public API key for your StackAdapt account. This is a token you request from your StackAdapt account team. Connect Avid to StackAdapt, verify the connection, and create or update CRM Audiences through Pathways. Request from your StackAdapt account representative. Do not use a REST API key.
Advertiser access Access to the specific advertiser or advertisers in StackAdapt you want to target. Restrict a CRM Audience to a specific advertiser when you set up a Pathway. Avid loads your advertiser list live from StackAdapt. If you lack access, the advertiser does not appear in the list. Confirm with your StackAdapt account team that your account includes the intended advertiser or advertisers.

Connect StackAdapt to Avid

Before you start, request a GraphQL Public API key (a token from your StackAdapt account team) if you do not already have one. Do not use a REST API key. The connection will fail with one.

  1. In Avid, go to Settings > Connections.
  2. Open the StackAdapt connection from your connections list. If StackAdapt is not listed yet, add it as a new system. The StackAdapt connection shows Reporting and Audiences badges.
  3. Enter your API Key. This is your GraphQL Public API key from your StackAdapt account team. The field is masked as you type. The form reads: "Connect StackAdapt using a GraphQL Public API key from your StackAdapt representative. Do not use a REST API key."
  4. Select the Environment Type. Choose Production (the default) unless your StackAdapt account team gave you a Sandbox key for testing.
  5. Set the Start Date in YYYY-MM-DD format. This controls how far back Avid loads your StackAdapt reporting data. Avid pre-fills a default (for example, 2024-01-01); adjust it if you want a different history window. You can only set this when you first create the connection. It cannot be changed later.
  6. Click Save. Avid verifies your key by calling StackAdapt. If the key is valid, the connection is saved with the name StackAdapt.

Expected result: The StackAdapt connection appears in Settings > Connections with the Reporting and Audiences badges.

What the connection enables

CRM Audiences through Pathways

Push Avid audience segments (groups of donors) to StackAdapt as CRM Audiences for ad targeting. You set this up in Pathways, Avid's feature for sending audiences to advertising platforms.

Each sync uploads a fresh file and replaces the audience with your current segment. It does not add to the previous list.

  1. Go to Pathways and add a new Pathway.
  2. Select your audience segment.
  3. Choose StackAdapt as the destination. Avid sends the segment as a CRM Audience (shown as the Destination Object value CRM Audience under Advanced Settings).
  4. On the Column Mapping screen, map your email field to the StackAdapt Email column. This is the required primary key. The Pathway will not save without it.
  5. Optionally map the data columns you have: First name, Last name, Phone, Address, City, State, and Zip.
  6. Set the four StackAdapt configuration columns under Additional Columns by choosing a value for each (see the table below).
  7. Review and save the Pathway.
StackAdapt configuration columns

These four columns appear under Additional Columns in the Pathway's column mapping. Choose a value for each from its dropdown.

Column Options Default Notes
Upload region US, GB (EU) US The region where StackAdapt processes your uploaded file.
Audience region US, UK US The region of the audience itself. The upload region uses GB while the audience region uses UK. These are different values.
CRM provider (default), Experian, Liveramp, Experian then Liveramp (default) "(default)" uses StackAdapt's default identity provider. Experian and Liveramp are third-party identity-matching providers you arrange through StackAdapt.
Advertiser ID (unrestricted), then your StackAdapt advertisers (unrestricted) Avid loads your advertiser list live from StackAdapt. Choose "(unrestricted)" to leave the audience available across advertisers, or pick a specific advertiser to restrict it.

Avid creates or updates a CRM Audience named AVID - {segment name} in StackAdapt. Repeated syncs to the same Pathway update that same audience rather than creating duplicates.

Volume guidance (a StackAdapt requirement, not enforced by Avid):

  • Minimum 100 unique CRM records per file.
  • At least 1,000 unique CRM records recommended.
  • At least 1,000 matched CRM records to run a lookalike audience expansion.

If your segment has no data rows, Avid completes the sync with 0 records and does not contact StackAdapt.

Processing time: After a sync, allow time for StackAdapt to process the file before you select the audience in a campaign. Avid does not report StackAdapt's match status, so check StackAdapt directly. Campaign creation, creatives, and bidding all happen in StackAdapt, not Avid.

Reporting and ad performance

The same StackAdapt connection brings campaign and delivery data into Avid Insights reporting. The Start Date you set when you created the connection controls how far back that data loads. Reporting syncs separately from the CRM Audience Pathway.

Test and verify

Checkpoint What to look for
After connecting The StackAdapt connection appears in Settings > Connections with the Reporting and Audiences badges.
After first Pathway sync The Pathways sync status shows completed and displays a record count. In StackAdapt, confirm the audience named AVID - {segment name} appears, allowing processing time.

Troubleshooting

Connection errors

Error message Cause Fix
API Key is required. No key was entered. Paste your GraphQL Public API key into the API Key field.
Environment Type must be Production or Sandbox. The environment field was left blank or holds an invalid value. Choose Production or Sandbox from the dropdown.
Could not verify StackAdapt API key: StackAdapt API did not return account data. Check your API token. The key is invalid, expired, a REST API key instead of a GraphQL Public API key, or for the wrong environment. Request a valid GraphQL Public API key from your StackAdapt account team. Confirm the Environment Type matches the key. A Production key needs Production selected; a Sandbox key needs Sandbox.
Start Date must be a valid date. The start date is blank or not in the required format. Enter the date as YYYY-MM-DD (for example, 2024-01-01).

Pathway sync errors

Error message Cause Fix
StackAdapt CRM audiences require a column mapped to Email (destination column "EMAIL"). The Pathway was saved without a column mapped to Email. Edit the Pathway, map your email field to the StackAdapt Email column, then save.
StackAdapt GraphQL errors: ... or StackAdapt createCrmSegment userErrors: ... StackAdapt rejected the request. The full error text states the specific reason. Confirm your API key is still valid and matches the selected environment. Confirm your StackAdapt account has access to the advertiser you chose. Confirm your segment has data rows. Retry the sync.
StackAdapt file upload failed (HTTP ...). The file transfer to StackAdapt failed, usually a network or authentication issue. Confirm your API key is valid and try again. If it persists, contact support with the full error text.

Known limitations

  1. Audience sync is on demand, not scheduled. Avid pushes data to StackAdapt only when you trigger a Pathway sync. To refresh your audience, re-trigger the Pathway.
  2. Each sync replaces, it does not append. Avid uploads a fresh file and replaces the audience with your current segment. Records no longer in the segment are removed.
  3. Minimum 100 unique CRM records per file (1,000+ recommended). This is a StackAdapt requirement, not an Avid limit. Avid does not block small syncs, but StackAdapt may not process a file below this size.
  4. Lookalike expansion needs at least 1,000 matched records. This is a StackAdapt requirement, not an Avid limit.
  5. Avid does not report StackAdapt match or processing status. After a sync, check StackAdapt directly to confirm the audience processed and to see match rates.
  6. Supported regions are limited to the dropdown options. Upload regions are US and GB (EU). Audience regions are US and UK. Other regions are not available.
  7. Campaign creation happens in StackAdapt, not Avid. Avid sends the audience. Creatives, bidding, targeting, and budget are all set in StackAdapt.
  8. Start Date cannot be changed after the connection is created. To load data from a different starting point, create a new connection.

When to contact support

Contact Avid support if:

  • The connection fails repeatedly after you request a fresh API key and retry.
  • A Pathway sync fails with an error not listed above.
  • The Advertiser ID list is empty but you expect to see advertisers.
  • The StackAdapt connection no longer shows as active after it was working.

Include the following when you reach out:

  • The exact error message (copy the full text).
  • The name of the Pathway that failed.
  • The StackAdapt environment you selected (Production or Sandbox).
  • The name of the audience segment you were syncing.
  • The approximate date and time of the failed sync.