Partner data: add third-party fields to your audiences

Partner data is optional third-party data you can add to your audiences, personas and exports. Each dataset comes from a data partner and has its own price. A dataset stays off until an organization Owner or Admin accepts that price and enables the dataset for a project.

Base URL: https://api.delivr.ai
Authentication: Organization API key for the API calls below (X-Api-Key and X-Api-Secret). Enabling a dataset is done in the dashboard. Accepting its price can also be done with a key.

Available datasets

The live list, with each dataset's current price, is in the Data partners page of the dashboard. The list is also in the public catalog described under Read the catalog. More datasets can be added over time.

How it is priced and billed

• Each dataset has a rate in USD per 1,000 records. It is charged on top of your base rate for the audience or export.
• Records are charged when they are selected, filtered or delivered, including exports and refreshes.
• Partner data is charged at the same quantity as the base charge: per person, or per company on an account audience. A values list or dataset audience has no base charge, so its partner data is charged on its own, per delivered row.
• Some datasets carry a separate rate when the records are activated through DelivrDSP. The dashboard shows both rates before you enable the dataset.
• Charges appear on your regular Delivr invoice, as a separate line for each dataset (marked "(DSP)" for DelivrDSP activations). The lines are added to the invoice for the period. Coupons do not discount these lines. This applies to accounts invoiced on the current billing plan, which is also the plan partner data requires. Partner data charges are non-refundable.
• Delivr gives 30 days' notice before a price increase. A scheduled change is listed beside the current price.

To see what a download would add before you run it, call the download endpoint with dry_run=true. See Check the cost first.

Turn on a dataset

An Owner or Admin of the organization does this in the dashboard.

1. In your project, press Cmd+K (Ctrl+K on Windows) and search for Data partners. The page is at https://app.delivr.ai/{org_id}/data-partners.
2. Open a dataset to see its fields, coverage and price.
3. Select the Enable button, which shows the rate. Confirming accepts the price and enables the dataset for that project.

Datasets are enabled per project. Downloads and exports that use a dataset's fields are refused until its price has been accepted and the dataset is enabled for the project.

Accept a price with an API key

An organization API key can accept a dataset's current price for its own organization. This records the acceptance only. It does not enable the dataset for a project, which is still done in the dashboard.

Take partner_id and price_id from the field catalog (partner_dataset on any field of the dataset, see Read the field catalog). Add dsp_price_id when the dataset has a separate DelivrDSP rate (partner_dataset.dsp_price.price_id):

curl -s -X POST "https://api.delivr.ai/data/core/v1/partners/$PARTNER_ID/price-acceptance" \
  -H "X-Api-Key: $DELIVR_API_KEY" \
  -H "X-Api-Secret: $DELIVR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"price_id": "'"$PRICE_ID"'"}'

Accepting binds your organization to that price, so call it only when your organization has agreed to it. The acceptance is recorded for the key's own organization and attributed to the API client. An organization_id in the body is ignored.

A 201 or 200 body:

{
  "organization_id": "<your organization id>",
  "partner_id": "<partner id>",
  "price_id": "<price id>",
  "dsp_price_id": null,
  "cpm_usd": "<USD per 1,000 records>",
  "accepted_at": "<RFC 3339 time>",
  "terms_version": "<terms version>"
}

See acceptPartnerPrice.

Who can enable

Set this under Settings > Data partners, at https://app.delivr.ai/{org_id}/settings/data-partners. There are three modes, set for the organization and optionally overridden per project:

For an agency's client projects the default is Off. Where an agency enables partner data for a client, the client sees that the agency bills for it rather than a price.

A member who cannot enable a dataset sees Request access, which sends a request to the people who can.

If a dataset is locked

• Not enabled for this project. Its fields show in the field picker as not enabled, and cannot be added. Ask an Owner or Admin to enable the dataset.
• Your billing plan does not support partner data. The dataset is shown but cannot be enabled, with the message "Your organization's billing plan doesn't support partner data. Contact support to enable it." Only accounts on the current billing plan can enable partner data. Contact support to move your account.
• Partner data is turned off for this project. The project's mode is Off. Change it in Settings > Data partners.

Use the fields

Once a dataset is enabled, its fields appear in the field pickers for audiences, personas and exports. Each partner field has a key of the form <slug>__<column>, where <slug> is the dataset's slug. Partner fields are text fields and are available on audiences, not on events.

Which audiences can use partner data

Each dataset is person-level or company-level (grain in the field catalog).

A dataset an audience type cannot use is refused with a message saying it cannot be used on that type of audience.

Read the field catalog

List only partner fields, naming the project so the response can say which datasets that project has enabled:

curl -s "https://api.delivr.ai/api/v1/field-catalog?category=partner_data&schema_type=audience&project_id=$DELIVR_PROJECT_ID" \
  -H "X-Api-Key: $DELIVR_API_KEY" \
  -H "X-Api-Secret: $DELIVR_API_SECRET"

Each partner field carries the usual field properties plus:

partner_dataset.enabled is true when the project named by project_id (or the X-Project-Id header) may use the dataset. With no project named, it is false. A key bound to one project always reads as that project. With no project named it reports that project, and naming any other project returns no partner fields. Under an agency's client project, provider_name and the prices are blank and billed_by names the agency instead.

See the Field Catalog API for filters and the rest of the response.

Build an audience or export

Use a partner field like any other field, in an audience filter or select, or in an export's field list. In an export, partner fields can only be exported from an audience that already carries that dataset.

Only the partner columns you name in select are delivered, after the audience's own columns. Select all (*) never adds partner columns. A partner field used only in a filter is joined and charged but not delivered.

A request that uses a partner field is refused when:

An export write that would deliver a dataset that is not enabled or not accepted is also refused with 409 and partner_price_not_accepted. The datasets to enable or accept are listed in partners. An export field that its audience does not carry is refused with a validation error naming the field. The same error applies to an export field that is not a column of the dataset.

Accept the price (in the dashboard, or with a key as described above) and enable the dataset in the dashboard, then retry the request.

List audiences

On list audiences:

• It is available on email and HEM lists only. Any other list type returns 400 with "Partner data is available on email and HEM lists only."
• A matched list joins partner data on the person each value matches, so a value that matches no one never carries partner columns. A values list joins on the value itself: a HEM, or the SHA-256 of a plaintext email.
• A filter on a partner field keeps only the list values that match it.

Dataset audiences

A matched dataset joins partner data on the person each row matches. A values dataset joins partner data on the row's email hash. A row with no match, or no email, carries no partner data.

Check the cost first

GET /api/v1/audiences/{id}/download with dry_run=true returns the base charge and, in partner_charges, one line per dataset the audience uses:

partner_charges is an empty list when the audience uses no partner data. If the charges cannot be priced, it is null and partner_charges_error is set. Retry the request. See downloadAudience.

Read the catalog

The datasets Delivr offers, with the price in force, are available without authentication:

curl -s https://api.delivr.ai/api/v1/public/partner-datasets

{
  "datasets": [
    {
      "partner_name": "<Dataset> (<Provider>)",
      "slug": "<slug>",
      "grain": "person",
      "cpm_usd": "<USD per 1,000 records>",
      "effective_from": "<RFC 3339 time>",
      "next_cpm_usd": "<present only when a change is scheduled>",
      "next_effective_from": "<present only when a change is scheduled>"
    }
  ]
}

A dataset appears here only when it is offered to customers and has a price in force, so the list can be empty. See listPartnerDatasets.

If you supply data

Organizations registered as data partners have a Partner Portal at https://app.delivr.ai/{org_id}/partner, with your deliveries and their acceptance decisions, and your compliance terms. Earnings shows your monthly statements and is visible to members who can view the organization's billing.

Related

• Field Catalog API
• Building filters
• Rate limits and metering