> ## Documentation Index
> Fetch the complete documentation index at: https://docs.puntego.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Amplitude

> Use selected Behavioral Cohorts in Puntego Audiences and send privacy-bounded product outcomes over HTTP V2.

Puntego connects to Amplitude in two independent directions:

* Outbound HTTP V2 delivery sends bounded runtime and verified Guide outcome events.
* Inbound Behavioral Cohorts adds selected membership and scalar user properties to Audiences.

Puntego accepts only the Amplitude US or EU region, never an arbitrary provider host. API and Secret
Keys are encrypted, write-only, and owned by one workspace.

## Connect outbound outcomes

1. In **Dashboard → Settings → Integrations → Amplitude**, choose the matching Amplitude data region.
2. Enter the project API key and save with delivery paused.
3. Choose pseudonymous identity, or explicitly opt into customer external ID when it must join the
   same Amplitude `user_id` as the host product.
4. Use **Send synthetic event** only when you intend to write one labeled integration event.
5. Enable the runtime and Guide topics after its delivery receipt is accepted.

Captured event properties, action inputs, selectors, reasons, model output, and action results are
not copied. Puntego assembles each payload just before dispatch and does not store it in the outbox.
Every delivery uses one immutable Amplitude `insert_id` for all safe retries.

<Warning>
  An accepted receipt means Amplitude HTTP V2 ingested the request. It does not independently prove
  that a later chart, cohort, or downstream workflow changed.
</Warning>

## Import Behavioral Cohorts

Behavioral Cohorts generally requires an Amplitude Growth or Enterprise plan and the project's
Secret Key.

1. Enter the write-only Secret Key and enable Behavioral Cohort sync.
2. Run **Test read-only access**. This reads catalog and usage endpoints and does not create an
   event.
3. Run **Sync cohorts** once to discover the catalog.
4. Select up to 20 cohorts and enter up to 12 exact scalar user-property names.
5. Save and sync again.

Puntego maps exact Amplitude `user_id` values to Puntego customer external IDs. It does not guess by
email or name. Approved values become:

* `customer.traits.amplitude.cohorts`
* `customer.traits.amplitude.<property>`

Objects, arrays, conflicts, and unmatched identities are quarantined. The previous Audience
projection remains active until every selected cohort succeeds, so a partial sync never becomes
live.

Puntego's inline import is intentionally bounded to 4 MiB and 10,000 members per cohort response.
Redirected large-cohort files fail closed and are not followed. Reduce or split those cohorts before
retrying.

See Amplitude's official [HTTP V2](https://amplitude.com/docs/apis/analytics/http-v2),
[Behavioral Cohorts](https://amplitude.com/docs/apis/analytics/behavioral-cohorts), and
[authentication](https://amplitude.com/docs/apis/authentication) documentation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.