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, resolves the Key (creating it only on your own contract — see Managed credentials), creates the Sub-Key (with an optional CPM), then delivers membership as a TSV file over SFTP with a companion .fin marker file.

Prerequisites

What you need depends on whose Active Agent seat you deliver through. Use managed credentials is on by default, so unless you turn it off, only the first list applies.

On the platform-managed seat — the platform supplies the account, network and credentials, and you supply:

• The Attribute ID and Attribute Key of the attribute your platform operator provisioned for you (see Managed credentials)

On your own Active Agent contract (managed credentials off):

• 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 an API 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)

Managed credentials

When the platform operates a shared Active Agent DMP seat, an Active Agent destination shows a Use managed credentials toggle, on by default. With it on, the seat’s SFTP import bucket, network id, and the API + SFTP credentials are all supplied by the platform at run time — you only name the attribute your audiences land under. The credential and shared-seat configuration fields below are hidden while the toggle is on, and are neither required nor stored on your destination; the platform overlays its own values on every sync, journey send, and connection test.

The attribute must already exist

The managed seat is the platform operator’s own Active Agent account, shared with other customers, so Zeotap never creates a tagging attribute (Key) in it. Your destination references an attribute the operator provisioned for you:

• Attribute ID is required — ask your platform operator for the id of the attribute assigned to your workspace. Saving the destination without it is rejected, and a run that reaches delivery without one fails rather than creating anything.
• Attribute Key must be that same attribute’s key. It forms the delivered tag {Attribute Key}.{Sub-Key}, and while Zeotap checks the key is well-formed, it cannot check that the key and the id name the same attribute. If they disagree the sync still reports success while membership does not land where you expect, so copy both values from your operator rather than typing the key by hand.
• The Key-creation settings (Attribute Name, Mode, Attribute Operation, Expires in Days, Max History Entries, Min Seconds Between Tags) are hidden while the toggle is on. They only ever applied at creation time, and the managed seat creates nothing.

Sub-Keys (segments) are still created for you beneath that attribute — that is how each audience becomes a targeting peculiarity.

The billing type is fixed on the managed seat

The operator’s account is not an Active Agent admin user, and Active Agent lets non-admin accounts create only DEFAULT targeting peculiarities — every other type is rejected with Only admin users are allowed to modify peculiarities that are not of type DEFAULT. Billing Type is therefore hidden while managed credentials are on, and every segment is created as DEFAULT.

This is applied when the segment is created, not merely in the form, so a destination saved before the field was hidden (the old default was FIRST_PARTY_PERCENTAGE_BILLING) is corrected automatically rather than failing. A useful side effect: DEFAULT is a CPM-bearing type, so your CPM now takes effect — percentage billing ignored it.

Turn the toggle off to integrate your own Active Agent contract: the credential and configuration fields reappear — the four credential fields plus API Base URL, Network ID, SFTP Host and SFTP Import Path become required, the rest stay optional — Zeotap uses exactly what you enter, and it will create the Key for you when you leave Attribute ID blank.

If the platform has no managed seat configured, the toggle is not shown and you always supply your own credentials.

Authentication

Active Agent needs two credential sets: the API credentials used to obtain an API token for creating the Key and Sub-Key, and the SFTP import credentials used to deliver the membership file. These fields are only shown — and only required — when Use managed credentials is off.

* Required only when Use managed credentials is off — otherwise supplied by the platform’s shared seat.

Zeotap calls POST {API Base URL}/auth with the API username and password, reads the token from the response, and sends it as an Authorization: <token> header on every subsequent API request. Note the token is passed without a Bearer prefix — Active Agent’s API rejects the prefixed form with 401 Unauthorized.

Configuration

The shared-seat fields — API Base URL, Network ID, SFTP Host, SFTP Port, and SFTP Import Path — are hidden and platform-supplied while Use managed credentials is on. The Key-creation settings (Mode, Attribute Operation, expiry, history, throttling) are hidden too, because the managed seat never creates a Key.

* Required only when Use managed credentials is off — otherwise supplied by the platform’s shared seat.

† Applied only when Zeotap creates the Key, so shown only when Use managed credentials is off.

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.

† Applied only when Zeotap creates the Key, so shown only when Use managed credentials is off.

‡ Required when Use managed credentials is on; optional on your own Active Agent contract.

Re-running a sync reuses its segment

A sync creates its segment the first time it runs and reuses it on every run after that — refreshes are delivered by the membership file, not by re-creating the segment. Active Agent allows only one segment per Sub-Key (and one per display name) within an attribute, so Zeotap checks what already exists before creating anything.

If another segment under the same attribute already uses your Segment Name, Zeotap appends the Sub-Key to make it unique rather than failing the sync — worth knowing on the platform-managed seat, where the attribute is shared and two customers can pick the same audience name. Your Sub-Key is never changed: it identifies the segment your membership is delivered into.

Segment names and Sub-Keys are adapted automatically

Active Agent accepts only letters, digits and underscore in a segment’s display name, up to 64 characters. Your Segment Name is rarely written with that in mind — in particular, turning on use the connected audience’s name fills it with the audience’s own name, which is free text.

Zeotap therefore maps the name onto the allowed characters when it creates the segment rather than failing the sync: runs of disallowed characters collapse into a single underscore, leading and trailing underscores are dropped, and the result is capped at 64 characters. Test Kairion – Q3 2026 (DE) is created as Test_Kairion_Q3_2026_DE. If nothing usable remains — a name written entirely in a non-Latin script, for example — the Sub-Key is used as the display name. The run log records the original and the adapted name.

The Sub-Key is adapted the same way, capped at its own 32-character limit: high intent is created and tagged as high_intent. It is adapted rather than rejected because a Sub-Key can come from a column, where retyping every value is not an option. The tag Zeotap delivers uses the adapted value, so the segment it creates and the segment it writes into are always the same one.

Because the Sub-Key identifies the segment, one case is refused rather than adapted: if two different Sub-Keys would collapse onto the same value — high intent and high-intent both becoming high_intent — the run fails naming both, since silently merging two audiences into one segment is not something a later check would reveal. A Sub-Key with no letters, digits or underscore at all is reported too, as there is nothing left to name a segment with.

The Attribute Key is never adapted. It must match an attribute that already exists in Active Agent, so rewriting it would point the sync at a different attribute — an invalid one is rejected when you save. Segment descriptions have no charset restriction and are truncated to Active Agent’s 255-character limit.

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 can be used both from audience syncs and from standard model syncs (reverse ETL). A model sync delivers segment membership the same way an audience sync does: each row’s identifiers are tagged with {Attribute Key}.{Sub-Key} in the TSV.

• Insert, Upsert, and Update write each delivered row’s tag into the TSV add column, granting membership. Active Agent tags identifiers idempotently, so re-delivering an existing member is harmless.
• Mirror routes rows that left the model’s output to the remove column and everything else to the add column, keeping segment membership aligned with the model.
• Snapshot is not supported — membership is maintained incrementally; use Mirror to keep a segment in step with a model.

Model syncs must map at least one supported identifier column (see Required Mapping Fields) — rows whose mapped identifier columns are all empty are reported as row errors and skipped. The Sub-Key, segment fields, and CPM can be fixed on the destination, overridden per sync, or taken from a column exactly as with audience syncs.

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

2. Resolve the Key and create the Sub-Key. If an Attribute ID is supplied it is used as-is. Otherwise — only possible on your own Active Agent contract, since managed destinations must supply one — 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. The error names which credential set was used, and that decides the fix:

• “this destination’s own Active Agent credentials” — the destination is not using the platform-managed seat (the toggle is off, or the destination predates it). Correct the API username and password on the destination, or turn Use managed credentials on to deliver through the platform’s seat instead.
• “the platform-managed Active Agent seat credentials” — nothing on your destination can fix this; report it to your platform operator, whose seat credentials need rotating.

Also verify 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)

This applies to your own Active Agent contract only — the managed seat never creates a 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.

Segment creation fails with “Only admin users…”

Only admin users are allowed to modify peculiarities that are not of type DEFAULT means the Active Agent account creating the segment is not an admin user, and Active Agent restricts non-admin accounts to the DEFAULT billing type. This cannot happen on the platform-managed seat, which always sends DEFAULT. On your own Active Agent contract, set Billing Type to DEFAULT, or ask Active Agent to grant your account admin rights if you need FIRST_PARTY_PERCENTAGE_BILLING or FIRST_PARTY_FLAT_BILLING.

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

On your own Active Agent contract, 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), and confirm the account may write to that directory. On the platform-managed seat all of those are supplied by the platform, so an SFTP failure is not something you can fix from the destination — report it to your platform operator.

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.

Attribute ID is required when using platform-managed credentials

The destination (or the sync overriding it) delivers through the platform’s shared Active Agent seat but names no existing attribute. Zeotap will not create a tagging attribute in the operator’s account, so ask your platform operator for the Attribute ID provisioned for your workspace and enter it — together with that attribute’s Attribute Key.

Membership is delivered but the segment stays empty

Check that the Attribute Key is the key of the attribute your Attribute ID names — Zeotap cannot verify the pair, and a tag naming an attribute that does not exist does not take effect, so a mismatch produces a successful sync with no membership. Pre-create the key and sub-key in Active Agent / ADITION if you are on your own contract; on the managed seat, confirm both values with your platform operator.

Row missing a supported identifier

The row carries no non-empty value in any of maid, aaid, idfa, idfv, email, id5, netid, utiq, adition_cookie, or adition_id. A row needs only one of them — an empty column is simply skipped as long as another identifier is present. The error lists the columns the row actually carried (row columns: [...]), so compare that list against the identifier names: if your identifier column appears there, its values are empty for those rows; if it doesn’t, the mapping isn’t producing the canonical field name. Ensure your model output or field mapping exposes at least one supported identifier column with non-empty values for every row.