Active Agent (Virtual Minds)

Push audience segment membership into the Active Agent DMP by Virtual Minds. Active Agent organises data as a Key (a “tagging attribute” / folder) that contains one or more Sub-Keys (a “targeting peculiarity” / segment). Zeotap authenticates to the Active Agent REST API, creates or reuses the Key, creates the Sub-Key (with an optional CPM), then delivers membership as a TSV file over SFTP with a companion .fin marker file.

Prerequisites

• An Active Agent account with API access
• Your Network ID — provided on the Active Agent destination; the Key and Sub-Key are provisioned on this network
• Active Agent API username and password (used to obtain a Bearer token)
• SFTP import username and password provisioned by Active Agent (e.g. user nw_3350) for membership file delivery
• The SFTP host (default vztd3.adition.com) and import path (default /dmp_import)

Authentication

Active Agent needs two credential sets: the API credentials used to obtain a Bearer token for creating the Key and Sub-Key, and the SFTP import credentials used to deliver the membership file.

Zeotap calls POST {API Base URL}/auth with the API username and password, reads the Bearer token from the response, and sends it as an Authorization: Bearer <token> header on every subsequent API request.

Configuration

Target Settings

These fields are set when linking an audience and can be overridden per sync. Set a default CPM on the destination and override it per audience where needed.

Per-row segments

Every field in the table above except Attribute Key, Attribute ID and Attribute Name can be taken from a column of your data instead of being fixed for the whole sync. One sync then fans out into many Active Agent segments — useful when your audience already carries the segment each profile belongs to.

To set it up, open the sync’s Destination target overrides, switch the field from Fixed value to From column, and pick the column. The switch adds a row to the sync’s field mapping (destination field sub_key), so you can also see and edit the binding — including adding a transform — in the Map fields editor.

The fixed value you leave behind is not wasted: it becomes the fallback applied to rows whose column is empty.

How Zeotap delivers it:

• Each row’s tag becomes {Attribute Key}.{that row's Sub-Key}. The Key (folder) stays fixed for the sync — only the Sub-Key varies.
• The first row to name a Sub-Key creates its targeting peculiarity, using that row’s Segment Name, Segment Description, Billing Type, Billable and CPM. Later rows with the same Sub-Key reuse it untouched. A segment is created at most once per run.
• Segment Name defaults to the Sub-Key, and Segment Description to a generated line, if neither the column nor the fixed value supplies one — the API rejects both when blank.
• A Sub-Key that breaks Active Agent’s rules (max 32 characters, alphanumeric and underscore only) is reported against the row that carries it; the rest of the batch still ships.

Limiting how many segments a run can create

Because a new Sub-Key creates a segment, binding a high-cardinality column by mistake — a user id, say — would create one segment per profile. Max distinct values per run (default 500) caps this: if a run needs to create more distinct segments than the limit allows, it fails with an error naming the field and the offending value, and no further segments are created. Set it to 0 for no limit.

Mirror mode cannot express a move between segments. A profile that moves from segment A to segment B appears in the diff as a changed row carrying only its current segment, so it is added to B but never removed from A. Rows diffed as removed correctly carry their own tag into the remove column. Prefer Add and Remove sync modes when the Sub-Key comes from a column.

Supported Operations

Sync Modes

Active Agent is audience-only — standard data sync modes are not supported.

Audience Sync Modes

• Add writes each member identifier’s tag into the TSV add column, granting membership.
• Remove writes each member identifier’s tag into the TSV remove column, revoking membership.
• Mirror re-delivers the full snapshot; rows marked as removed in the diff go to the remove column, all others to the add column, so the segment reflects current membership.

Features

• Field Mapping: Yes — map your warehouse columns to maid, aaid, idfa, idfv, email, id5, netid, utiq, adition_cookie, adition_id, or id_type
• Schema Introspection: No

Required Mapping Fields

At least one identifier must be mapped for every sync:

Default Destination Fields

Each identifier carries a numeric ID-TYPE code that Zeotap fills into the TSV automatically (see ID-TYPE codes). Prefer the typed device fields (aaid / idfa / idfv) over the generic maid so the type is set for you.

ID-TYPE codes

Active Agent identifies each USER-ID by a numeric type code. Zeotap fills the TSV ID-TYPE column automatically when a row carries a single, unambiguous identifier type. Map id_type explicitly to send any other code, or to override the derived value.

If a row mixes identifier types (for example a generic maid alongside an id5), the values are still joined into the USER-ID but the ID-TYPE is left blank, because one numeric code cannot describe a heterogeneous list.

How It Works

The integration runs in three steps.

1. Authenticate. Zeotap calls POST {API Base URL}/auth with your API username and password and stores the returned Bearer token.

2. Create the Key and Sub-Key. If an Attribute ID is supplied it is reused; otherwise Zeotap creates the Key via POST /tagging-attributes (using the Attribute Key, name, mode, operation, and any TTL / history settings) and reads back the attribute id. It then creates the Sub-Key (segment) via POST /targeting-peculiarities/ with the segment name, description, billing type, and — for DEFAULT or FIRST_PARTY_FLAT_BILLING — the CPM in euro cents.

3. Deliver membership over SFTP. Zeotap builds a tab-separated file with one row per member:

   <USER-ID>	<TAGS-TO-ADD>	<TAGS-TO-REMOVE>	<ID-TYPE>

   • USER-ID — the mapped identifiers joined with commas in a canonical unstable→stable order: device ids (maid / aaid / idfa / idfv) first, then email and the universal ids (id5 / netid / utiq), then the stable adition_cookie / adition_id rightmost.
   • The tag is {Attribute Key}.{Sub-Key}. It lands in the add column for add/mirror syncs and the remove column for remove syncs (or mirror rows diffed as removed).
   • ID-TYPE — an explicitly mapped id_type if provided; otherwise the code auto-derived when the row carries a single, unambiguous identifier type (see ID-TYPE codes); otherwise blank. Rows that mix identifier types are left blank to avoid mislabeling.

   The file is uploaded to the SFTP import path, followed by an empty .fin marker file of the same base name that signals the upload is complete and ready to process.

Troubleshooting

Connection test fails at “Authenticate with the Active Agent API”

The API username or password is incorrect, or the API Base URL is wrong. Verify the credentials and that the base URL is https://api.active-agent.com/latest (or the value provided by Active Agent). The test does not check the SFTP credentials — those are validated at the first sync.

Sync fails creating the tagging attribute (Key)

The Attribute Key must be at most 32 characters, alphanumeric and underscore only, and start with a letter. Confirm the Network ID is correct and that your account may create attributes on it. To reuse an existing Key instead of creating one, set the Attribute ID target field.

Sync fails creating the targeting peculiarity (Sub-Key)

The Segment Description cannot be empty — the API rejects a blank description. Also confirm the Sub-Key (max 32 chars) and Segment Name (max 64 chars) use only alphanumeric and underscore characters.

CPM not reflected on the segment

CPM applies only to the DEFAULT and FIRST_PARTY_FLAT_BILLING billing types and is ignored for FIRST_PARTY_PERCENTAGE_BILLING. Set the Billing Type accordingly and ensure the CPM is provided in euro cents (an integer). If you set a CPM with percentage billing, it is skipped and a warning is logged.

SFTP upload fails

Verify the SFTP Import User and Password, the SFTP Host (default vztd3.adition.com), the port (default 22), and the import path (default /dmp_import). Confirm the account may write to that directory.

Membership does not appear in Active Agent

Active Agent processes the TSV only after the companion .fin marker file is present. Zeotap uploads both, but if the TSV lands without its marker (for example after a partial failure) the file is ignored. Re-run the sync to deliver a fresh file pair.

Row missing a supported identifier

The source row contains none of maid, aaid, idfa, idfv, email, id5, netid, utiq, adition_cookie, or adition_id. Ensure your warehouse query or field mapping exposes at least one supported identifier column for every row.