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, has its own price, and 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.

Available datasets

The live list, with each dataset's current price, is in the Data partners page of the dashboard and 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.
• 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. 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. Open Data partners in the project navigation, 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.

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.

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. 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.

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, with the datasets to enable or accept listed in partners. An export field that its audience does not carry, or that is not a column of the dataset, is refused with a validation error naming the field.

Accept a price and enable a dataset in the dashboard, then retry the request.

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. 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