Connected Datasets: use your customer file as an audience source

A Connected Dataset is a file of your own customer records that you upload once and keep at the organization level. You can then use it as the source of truth for an audience, instead of building the audience from filters. Datasets are managed in the dashboard at https://app.delivr.ai/{org_id}/datasets.

Connected Datasets are enabled per organization. If you do not see Datasets in your organization, contact your account manager.

flowchart LR
    A[Upload customer file] --> B[Import: rows kept, rows rejected]
    B --> C[Build audience from dataset]
    C --> D[Deliver to S3, email, Slack, HubSpot or Salesforce]
    B -.->|optional, org admin| E[Contribute to identity resolution]

    style A fill:#3b82f6,color:#fff
    style B fill:#6366f1,color:#fff
    style C fill:#6366f1,color:#fff
    style D fill:#22c55e,color:#fff

Your data stays in your organization

Records you upload are stored for your organization and never resold. Unless an organization admin opts a dataset into identity resolution contribution (see Contribute to identity resolution), the records are never merged into Delivr's cross-customer identity graph or shared with another organization. They are used only to match and build your own audiences.

Prepare the file

Upload a CSV, TSV or Excel (.xlsx) file. The first row must be a header row naming each column. For an Excel workbook, put the data on the first sheet. Legacy .xls files are not supported: save the sheet as .xlsx, or export it as a CSV.

Requirement	Detail
`customer_key` column	Required. Your own record ID for each row. It is carried on every result so you can join the output back to your systems. It must be unique: if a value repeats, the first row is kept and later rows are rejected.
An identifier column	Required: at least one of `email`, `phone`, `hem` or `domain`. `hem` is a pre-hashed email (MD5, SHA-1 or SHA-256).
Optional match columns	`first_name`, `last_name`, `address` (street line 1) and `zip`. These help match people and do not count as the required identifier.
Any other column	Kept as an attribute of your dataset. Spaces around a value are trimmed, and an empty value is stored as empty (null).

Limits:

File size: 1 GiB, or 200 MiB for .xlsx.
Rows: 10,000,000 data rows.
Columns: 150.
Every column needs a header, and two headers that become the same name after normalization (for example Work Email and work_email) are refused.

After you choose a file, the dashboard suggests how each column maps to a role: customer key, one of the identifier columns above, or attribute. Columns named exactly like the reserved names are recognized automatically, ignoring case. For other headers, check the suggestion and change it before you start the import. The dashboard also offers a starter CSV you can download from the import dialog.

Import a file

Open Datasets in the organization navigation and create a dataset, or open an existing one.
Select Import a file, choose your file and confirm the column mapping.

Each import builds a new version of the dataset. The dataset page shows the result of the latest import.

Rows kept and rows rejected

Rows imported is the number of rows kept in the new version.
Rejected rows are left out of the version. The page shows the count and a sample of the first rejected rows with the row number and the reason. A row is rejected when it has a different number of columns than the header, when its customer_key is empty, or when its customer_key repeats an earlier row.
A row with no usable identifier is not rejected. It is kept, and it shows up in the usable identifier counts below.

An import fails, and builds no version, if the file has no valid data rows, or if it breaks the file rules above (for example, no customer_key column or no identifier column). The dashboard shows the reason.

Usable identifiers

For each identifier, the page shows how many rows have a value Delivr can use, for example 4,210 of 5,000 rows usable, and how many rows had a value at all. A value is usable when it can be normalized: a well-formed email address, a phone number that parses, a hex hash of 32, 40 or 64 characters for hem, a bare hostname for domain.

This is a check of your file. It is not a match against Delivr contacts. How many people match is shown once you build an audience from the dataset.

Build an audience from a dataset

In the audience builder, choose a dataset as the source. Only datasets with at least one built version appear. Then choose how the dataset is used:

Mode	What the audience contains
Use as uploaded (values)	The identifiers derived from your rows. Nothing is looked up against the Delivr contact database, so no contacts or identifiers are added.
Match and enrich (matched)	One row per record in your dataset, with your customer key and identifiers, plus the matched person (their hashed emails, Delivr person ID and mobile phones) and a `match_method` column showing how the match was made: `email`, `phone` or `name_address`. Your other columns are not included. Records that cannot be matched are kept, not dropped.

You also choose which version the audience reads:

Follow the current version: each rebuild uses whatever version is current, so the audience picks up your next import.
Pin to the current version: the audience keeps rebuilding from the version that is current today, so a later import does not change who is in it.

Intent targeting is not available for a dataset source, because the people come from your dataset rather than from a filter.

Where a dataset audience can be delivered

A dataset audience contains your own records, so it can go only to destinations that return them to your organization.

Destination	Values mode	Matched mode
Amazon S3	Yes	Yes
Email	Yes	Yes
Slack	Yes	Yes
HubSpot	No	Yes, with the setting below
Salesforce	No	Yes
DelivrDSP	No	No
Data marketplace	No	No

Delivery is refused when you save the export and again when it runs. Other destinations on the same export still deliver.

Values mode is refused at HubSpot and Salesforce because its rows carry only your dataset's columns and no matched person, so they cannot map to CRM records. Build the audience in matched mode, or deliver it to S3, email or Slack.

HubSpot and matched mode

Matched output carries hashed emails, not plain-text email addresses. HubSpot's default way to match existing contacts is by email, so for a dataset audience, set the HubSpot export mapping to deduplicate on the Delivr person ID instead. Map the Delivr person ID (profile_pid_all) to the HubSpot property delivr_master_id, and select delivr_master_id as the field used to match existing contacts.

Contribute to identity resolution

You can optionally let a dataset improve Delivr's cross-customer identity resolution. This is off by default and is decided per dataset.

Only an organization admin can turn it on or off.
It is available after the dataset's first import.
Opting in takes two steps: a disclosure, then typing the dataset name to confirm.
Only the dataset's identifiers (emails, phone numbers, hashed emails and domains) are shared. Your other columns are never shared, and nothing is resold.
It cannot be undone. Shared identifiers merge into the resolution graph and cannot be individually recalled.
Stop contributing halts future sharing only. Identifiers already contributed stay in the resolution graph, and contribution cannot be turned back on for that dataset.
Later imports into a contributing dataset are shared too, and the import dialog says so.

Deleting a dataset makes it unavailable: it no longer appears in Datasets or as an audience source, and audiences that use it stop resolving against it. Identifiers it already contributed to identity resolution remain.