Audience Leads

Audience leads are organization-owned participant profiles connected to one or more campaign audience lists through registrations. Scanly stores the current profile once and keeps list participation, consent state, and registration history as separate local records.

The audience data view uses this local model for participant administration, CSV import and export, sample data, broadcast recipients, ticket recipients, and automation mapping.

Current State

The following lead workflows run locally in Scanly:

• list and count participants for an audience list;
• create and edit participant profiles;
• manage participation in the selected and coupled audience lists;
• grant or revoke the consents visible through those lists;
• remove a participant from one audience list without deleting the profile;
• participant imports from CSV;
• resolve import duplicates automatically or with a merge editor;
• generate 20 configurable sample records for one audience list;
• CSV exports for participant, relation, and communication columns;
• resolve local recipients for broadcasts and ticket sends;
• resolve local lead data for automations.

All participant administration uses the organization-owned lead profile and its campaign-specific audience-list registrations.

Core Concepts

Local Data Model

The local model separates the current participant profile from list-specific history:

A lead can therefore participate in several lists without duplicating the canonical profile. The audience table still shows one row per lead. When more than one active registration exists for the same lead and list, the newest active registration is used for the row.

Participant and registration counters intentionally describe different values:

• Participants counts distinct leads with an active registration.
• Registrations counts the active registration records.

Open Audience Data

Open a campaign and go to Audience. Select an audience list and open Audience data.

The table supports:

• selecting the audience list whose participants should be displayed;
• filtering by creation date;
• sorting by id, creation date, update date, or email;
• ascending and descending order;
• paginated loading;
• showing, hiding, and reordering columns;
• formatting column previews and CSV output;
• fullscreen mode;
• adding, editing, and removing participants;
• importing, exporting, and generating sample data.

Inputs from the selected root list and its coupled lists form the available personal-data columns. Relation and communication columns are available for the table configuration and export without becoming part of the stored personal data.

Add A Participant

Select Add participant from the audience table actions.

The form is built from the current local list configuration:

1. Inputs from the root list and all resolved coupled lists are merged.
2. The root list is always selected and cannot be removed.
3. Coupled lists start selected but can be deselected.
4. Required fields are validated from the merged audience-list schema.
5. Required consents must be granted when one of their source lists is selected.
6. The lead, registrations, and active consent states are stored together.

After the local write succeeds, Scanly publishes a lead.created automation event containing the local lead id, root-list id, personal data, and granted consent ids.

Example API payload:

{
  "inputData": {
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com"
  },
  "selectedParticipationListIds": [
    "root-audience-list-id",
    "coupled-audience-list-id"
  ],
  "grantedConsentIds": ["organization-consent-id"]
}

Edit A Participant

Open the row actions and select Edit participant.

The form loads the current profile, active registrations, and active consents that are visible through the selected root list. Saving can update:

• personal-data values;
• participation in coupled audience lists;
• granted and revoked consent states.

The root-list participation remains required. Personal-data fields that are not part of the current merged form are retained instead of being removed. Existing email data is also retained when the current form does not resolve a replacement email.

After a successful local write, Scanly publishes a lead.updated automation event.

Remove A Participant From A List

Open the row actions and select Remove from list.

This action does not delete the lead. It marks active registrations for the selected campaign and root list as unsubscribed. The canonical profile, consents, and registrations in other audience lists remain available.

Coupled Lists And Consents

The participant form uses one merged context for the root list and every reachable coupled list.

• The same input key is represented once in the merged form.
• Each input and consent keeps the ids of the lists from which it originates.
• Participation determines which list registrations are active.
• A required consent applies when at least one of its source lists is selected.
• Consents from unrelated lists are not shown or changed through this form.

This keeps one organization-owned lead profile while allowing the same person to participate in several related lists.

CSV Import

Select Import from the audience table actions.

Use Download template to create a CSV header from the current merged input schema. Uploaded headers are matched against an input’s visible label and its technical key. Header matching ignores capitalization, spaces, punctuation, and accents.

Example headers:

First name,Last name,E-Mail,Company
Ada,Lovelace,ada@example.com,Analytical Engines

Unknown columns are ignored. The complete file is rejected when it contains a duplicate header or when several headers map to the same audience-list input. Individual rows are skipped when required fields are missing or a value cannot be converted to the configured input type.

Important CSV value rules:

Merge Criteria

Merge criteria identify duplicate participants. Only required form fields can be selected.

• One selected field is matched on its own.
• Several selected fields are matched as one combined key.
• The email input is selected by default when it is required.
• Otherwise, the first required input is used as the default.

Duplicate matching is organization-wide. An existing lead can therefore be added to the selected audience list without creating another canonical profile.

Import Stages

The import runs in two stages:

1. Duplicate rows inside the uploaded CSV are compared and merged first.
2. The reduced CSV is compared with existing local organization leads.

The merge editor shows the old value, incoming value, and final merged value for each conflicting field. CSV-internal conflicts may require more than one pass until the reduced file no longer contains duplicates.

Duplicate Strategies

Successful CSV rows are registered with the root list and its resolved coupled lists. The merged form’s consent records are stored as active. New participants publish lead.created; changed or newly linked existing participants publish lead.updated.

The result separates:

• Created: new canonical lead profiles;
• Added: rows successfully connected to the current audience-list context;
• Skipped: empty, invalid, unchanged, or failed rows.

Generate Sample Data

Select Create sample data for the current audience list.

1. Choose a compatible generator for every writable input.
2. Confirm Create 20 records.
3. Scanly validates the generated values through the normal local input schema.
4. Twenty local leads are added to the selected root list.

Examples include names, addresses, email addresses, phone numbers, dates, numbers, selections, colors, and image URLs. Select and multi-select generators use the options configured for their input.

Optional fields have a 50% chance of remaining empty in each generated record. Required state is read from the input-to-audience-list configuration used by the form. Required consents directly assigned to the selected root list are granted.

Sample records intentionally join only the selected root list and do not publish automation events. They are ordinary local records after creation and can be edited, exported, or removed like other participants.

CSV Export

Select the columns shown in the audience table and choose Export.

Available export groups:

Fixed column labels are localized. Personal-data labels come from the configured inputs.

The following output transformations are available where they match the column type:

• anonymize or replace empty values;
• trim, lowercase, uppercase, or normalize whitespace;
• format dates and booleans;
• join repeated relation values into one CSV cell.

Without a join rule, repeated relation values can create additional physical CSV rows for the same lead. Scalar values are written only to the first row. The export uses the selected sorting and date filters and includes a UTF-8 byte-order mark for spreadsheet applications.

Registration And Consent States

Registration states:

Consent states:

Only verified, verified-duplicate, and signed-up registrations are treated as active by participant lists and recipient consumers.

Local Consumers

The local read service provides one shared source for downstream features:

• mail and push broadcasts load local audience-list recipients and deduplicate them by normalized email;
• ticket sends load local recipients, apply configured mappings, validate the result, and deduplicate by email;
• automation mapping loads the current local profile and merges it with runtime event input data;
• audience-list overviews and removal decisions use local participant and registration counts.

This gives participant administration, communication, ticketing, and automations one consistent source for audience-list data.

API Overview

All endpoints are campaign- and audience-list-scoped and require campaign access.

Participant administration:

GET    /api/v1/campaigns/:campaignId/audience-lists/:audienceListId/leads
GET    /api/v1/campaigns/:campaignId/audience-lists/:audienceListId/leads/counts
GET    /api/v1/campaigns/:campaignId/audience-lists/:audienceListId/leads/form-state
POST   /api/v1/campaigns/:campaignId/audience-lists/:audienceListId/leads
GET    /api/v1/campaigns/:campaignId/audience-lists/:audienceListId/leads/:leadId/form-state
PATCH  /api/v1/campaigns/:campaignId/audience-lists/:audienceListId/leads/:leadId
DELETE /api/v1/campaigns/:campaignId/audience-lists/:audienceListId/leads/:leadId

Sample data and export:

POST /api/v1/campaigns/:campaignId/audience-lists/:audienceListId/leads/example-data
GET  /api/v1/campaigns/:campaignId/audience-lists/:audienceListId/leads/export

CSV import:

POST /api/v1/campaigns/:campaignId/audience-lists/:audienceListId/leads/import
POST /api/v1/campaigns/:campaignId/audience-lists/:audienceListId/leads/import/csv-internal/preview
POST /api/v1/campaigns/:campaignId/audience-lists/:audienceListId/leads/import/csv-internal/resolve
POST /api/v1/campaigns/:campaignId/audience-lists/:audienceListId/leads/import/manual/preview
POST /api/v1/campaigns/:campaignId/audience-lists/:audienceListId/leads/import/manual/resolve

Import endpoints use multipart form data. The file field is named file. mergeCriteria and manual resolutions are JSON-encoded form values.