> ## 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.

# Segment

> Use Segment traits in Puntego Audiences and send privacy-bounded product outcomes through the Tracking API.

Puntego connects to Segment in both directions:

* Inbound Track, Identify, and Group endpoints observe approved traits and events.
* Outbound delivery sends bounded runtime and Guide outcome events through Segment's Tracking API.

The paths are independently enabled. Puntego never accepts an arbitrary provider host: the US and
EU choices map to Segment's official Tracking API origins.

## Connect inbound events

1. In **Dashboard → Settings → Integrations → Segment traits and outcomes**, create an inbound source key.
2. Copy it immediately. Puntego stores only its SHA-256 digest and cannot display it again.
3. Configure the displayed Track, Identify, and Group endpoints in the sending system.
4. Use HTTP Basic with the source key as username and an empty password. Include the colon when
   encoding the credential: `base64("source-key:")`.
5. Send representative messages, then select only the scalar traits the workspace needs.

Requests must be JSON and no larger than 32 KiB. Include a stable `messageId` under 100 characters.
Track also needs `event`; Group needs `groupId`; all messages need `userId` and/or `anonymousId`.
A repeated `messageId` is acknowledged as a duplicate without producing a second record.

Identify and Group write separate provider projections rather than overwriting first-party data:

* `customer.traits.segment.user.<trait>`
* `account.traits.segment.group.<trait>`

Selected Track properties remain analytics context under `segment.event.*`; Puntego does not imply
that an event property is current user or account state. Selections are prospective.

## Connect outbound outcomes

Create a dedicated HTTP source in Segment, choose the matching US or EU region in Puntego, and enter
its source Write Key. The key is encrypted and write-only. Keep delivery paused until **Test
credentials** and **Send test event** succeed.

Pseudonymous identity is the default and sends a tenant-keyed pseudonym. Customer external ID is an
explicit opt-in for joining outcomes to an existing Segment user. Runtime properties, action
inputs, selectors, reasons, model output, and action results are never included.

Outbound payloads are assembled immediately before dispatch and are not stored. A stable delivery
ID becomes Segment's `messageId`. Explicit rate limits and server errors use bounded retry; an
ambiguous network failure after dispatch is marked `unknown` and is not retried automatically.

<Warning>
  An `accepted` status means Segment's Tracking API returned `2xx`. It does not prove that every
  downstream Segment destination delivered or processed the event.
</Warning>

## Operate safely

* Rotate the inbound key if it may have been exposed; the prior key stops working immediately.
* Re-enter the Write Key when changing region.
* Use delivery diagnostics and the deterministic `messageId` before manually handling an `unknown`
  result.
* Operational exports omit credentials, raw provider message IDs, anonymous-ID hashes,
  idempotency keys, lease tokens, payloads, and provider response bodies.

See Segment's official [HTTP Tracking API](https://segment.com/docs/connections/sources/catalog/libraries/server/http-api/),
[common fields](https://segment.com/docs/connections/spec/common/),
[Track](https://segment.com/docs/connections/spec/track/),
[Identify](https://segment.com/docs/connections/spec/identify/), and
[Group](https://segment.com/docs/connections/spec/group/) documentation.


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