Segment is a customer data platform (CDP) that collects behavioral event data from websites, mobile apps, and servers and routes it to downstream destinations for analytics, marketing, advertising, and data warehousing. It standardizes event collection around a common specification of Identify, Track, Page, Screen, Group, and Alias calls, so a single stream of customer data can feed many tools without separate instrumentation for each. The Segment HTTP Tracking API accepts analytics data from any website or application, and Segment then routes that data to the destinations configured in the workspace.
Product Type: Customer Data Platform
Integration Type: Starter Kit
Event Source Type: Web, Mobile Browser, and Mobile App
Event Scope: Full-Funnel Events
- Sends Identify, Page, Screen, and Track events to Segment's HTTP Tracking API from the server side, without a client-side Segment tag.
- Forwards common context fields (page, campaign, device, app, OS, locale, IP, and user agent) when provided.
- Sends anonymousId and userId with every event so Segment can associate activity with a user.
- Delivers events in batches to Segment's batch endpoint, reducing the number of outbound requests.
- Lets one event stream feed every downstream destination connected to the Segment source.
- Events are authenticated with the Write Key from your Segment HTTP API source and land in the source that key belongs to.
- Events go to Segment's Oregon region by default. To send to Dublin (Regional Segment, Business plans), set
HOST to events.eu1.segmentapis.com.
- Every event needs a
userId, an anonymousId, or both. Events with neither are rejected.
- Every event needs a valid
type (identify, page, screen, or track), and every Track event needs an event name.
properties accepts any fields, but revenue, currency, and value are reserved by Segment and should only be used for their intended purpose.- Timestamps must be ISO-8601 in UTC. Include
timestamp when sending historical events.
- Segment removes duplicate events using
messageId, which must be unique and under 100 characters.
- Size limits are 32 KB per event, and 500 KB or 2,500 events per batch. This integration sends up to 100 events per batch.
- Oversized or invalid payloads return a
400 error.
- IP addresses are sent as IPv4 only.
- Segment recommends staying under 1,000 requests per second per workspace.
- Events reaching Segment does not mean they reach downstream destinations. Confirm each destination accepts server-side data and is set up correctly.
- A
200 response from Segment does not guarantee that the batch, or the events within it, were accepted. Always verify delivery in the Segment Debugger.
- Group and Alias calls are not supported by this starter kit.
- Device-mode (client-side) destination features available through Segment's native libraries are not available, since events are delivered server-side.
- Source Write Key: In your Segment workspace, go to Connections, then Sources, and click Add Source. Search for and add the HTTP API source, then open the source's Settings tab, select API Keys, and copy the Write Key.
- Workspace Region: Confirm whether your Segment workspace processes data in the US (Oregon) or EU (Dublin) region. This integration defaults to Oregon.
- From the integration library, add a Segment integration. Then, fill out the Connection Parameters:
| Connection Parameter | Description |
|---|
WRITEKEY | Segment HTTP API source Write Key, used to generate the HTTP Basic Auth header. |
HOST | Segment API host. Defaults to api.segment.io (Oregon). Use events.eu1.segmentapis.com for Dublin. |
- MetaRouter provides all of the event mappings that Segment integrations typically require. You may add custom events, parameters, or mappings in accordance with Segment's API documentation.
- In the Pipelines tab, add your Segment integration.
- Select the correct integration revision.
- Click Add Integration and finalize deployment.
Global mappings will be applied to all events. If your parameter names do not match the Expected Inputs provided, you will need to overwrite the Inputs provided with your own.
| Output Key | Description | Expected Input |
|---|
type Required | String: Event method name; must be identify, page, screen, or track on every batch item. | type |
messageId | String: Unique event identifier used by Segment for deduplication; keep under 100 characters. | messageId |
anonymousId Required | String: Anonymous user identifier; one of anonymousId or userId must be present. | anonymousId |
userId Required | String: Known user identifier; one of anonymousId or userId must be present. | userId |
receivedAt | String: Time the event was received, in ISO-8601 format and UTC. | receivedAt |
timestamp | String: Time the event occurred, in ISO-8601 format and UTC. | timestamp |
sentAt | String: Time the event was sent, in ISO-8601 format and UTC. | sentAt |
context.library | Object: Name and version of the library that collected the event. | context.library |
context.ip | String: IPv4 address of the user. | context.ip |
context.locale | String: Locale of the user. | context.locale |
context.page | Object: Page details such as path, referrer, search, title, and URL. | context.page |
context.userAgent | String: User agent of the browser or device. | context.userAgent |
context.traits | Object: User traits attached to the event context. | traits |
context.app | Object: App details such as name, version, and build. | context.app |
context.campaign | Object: Campaign details such as name, source, medium, term, and content. | context.campaign |
context.device | Object: Device details such as ID, advertising ID, type, manufacturer, and model. | context.device |
context.network | Object: Network details such as carrier and connection type. | context.network |
context.os | Object: Operating system name and version. | context.os |
context.screen | Object: Screen dimensions and density. | context.screen |
context.timezone | String: Timezone of the user. | context.timezone |
context.groupId | String: Group or account identifier associated with the user. | context.groupId |
context.userAgentData | Object: Structured user agent client hints. | context.userAgentData |
| Output Key | Description | Expected Input |
|---|
traits | Object: Free-form user traits, such as email or name. | traits |
| Output Key | Description | Expected Input |
|---|
name | String: Name of the page. | properties.name |
properties | Object: Free-form page properties, such as path, title, url, and referrer. | properties |
| Output Key | Description | Expected Input |
|---|
name | String: Name of the app screen. | properties.name |
properties | Object: Free-form screen properties. | properties |
| Output Key | Description | Expected Input |
|---|
event Required | String: Track event name. | Enrichment – 'Products Searched' |
properties | Object: Free-form Track event properties; reserved names keep their Segment meaning. | properties |
| Output Key | Description | Expected Input |
|---|
event Required | String: Track event name. | Enrichment – 'Product List Viewed' |
properties | Object: Free-form Track event properties, including the products array. | properties |
| Output Key | Description | Expected Input |
|---|
event Required | String: Track event name. | Enrichment – 'Product Clicked' |
properties | Object: Free-form Track event properties; reserved names keep their Segment meaning. | properties |
| Output Key | Description | Expected Input |
|---|
event Required | String: Track event name. | Enrichment – 'Product Viewed' |
properties | Object: Free-form Track event properties; reserved names keep their Segment meaning. | properties |
| Output Key | Description | Expected Input |
|---|
event Required | String: Track event name. | Enrichment – 'Product Added' |
properties | Object: Free-form Track event properties; reserved names keep their Segment meaning. | properties |
| Output Key | Description | Expected Input |
|---|
event Required | String: Track event name. | Enrichment – 'Product Removed' |
properties | Object: Free-form Track event properties; reserved names keep their Segment meaning. | properties |
| Output Key | Description | Expected Input |
|---|
event Required | String: Track event name. | Enrichment – 'Product Added To Wishlist' |
properties | Object: Free-form Track event properties; reserved names keep their Segment meaning. | properties |
| Output Key | Description | Expected Input |
|---|
event Required | String: Track event name. | Enrichment – 'Cart Viewed' |
properties | Object: Free-form Track event properties, including cart_id and the products array. | properties |
| Output Key | Description | Expected Input |
|---|
event Required | String: Track event name. | Enrichment – 'Checkout Started' |
properties | Object: Free-form Track event properties; reserved names keep their Segment meaning. | properties |
| Output Key | Description | Expected Input |
|---|
event Required | String: Track event name. | Enrichment – 'Coupon Entered' |
properties | Object: Free-form Track event properties; reserved names keep their Segment meaning. | properties |
| Output Key | Description | Expected Input |
|---|
event Required | String: Track event name. | Enrichment – 'Payment Info Entered' |
properties | Object: Free-form Track event properties; reserved names keep their Segment meaning. | properties |
| Output Key | Description | Expected Input |
|---|
event Required | String: Track event name. | Enrichment – 'Promotion Viewed' |
properties | Object: Free-form Track event properties; reserved names keep their Segment meaning. | properties |
| Output Key | Description | Expected Input |
|---|
event Required | String: Track event name. | Enrichment – 'Promotion Clicked' |
properties | Object: Free-form Track event properties; reserved names keep their Segment meaning. | properties |
| Output Key | Description | Expected Input |
|---|
event Required | String: Track event name. | Enrichment – 'Order Completed' |
properties | Object: Free-form order properties (order ID, revenue, tax, shipping, discount, coupon, products); revenue is reserved. | properties |
| Output Key | Description | Expected Input |
|---|
event Required | String: Track event name. | Enrichment – 'Order Updated' |
properties | Object: Free-form Track event properties; reserved names keep their Segment meaning. | properties |
| Output Key | Description | Expected Input |
|---|
event Required | String: Track event name, sent to Segment as Order Cancelled. | Enrichment – 'Order Cancelled' |
properties | Object: Free-form Track event properties; reserved names keep their Segment meaning. | properties |
| Output Key | Description | Expected Input |
|---|
event Required | String: Track event name. | Enrichment – 'Order Refunded' |
properties | Object: Free-form Track event properties; reserved names keep their Segment meaning. | properties |
These identifiers must be mapped to Segment in order for successful user matching to occur. Without these IDs, any events sent to Segment may not be accurately reflected in reporting.
| Attribute | Example | Sync Injector Required? |
|---|
anonymousId Required | ce576487-95f9-4262-9315-2c7942b061c8 | No |
userId Required | 019mr8mf4r | No |
messageId Recommended | 022bb90c-bbac-11e4-8dfc-aa07a5b093db | No |
traits.email | [email protected] | No |
context.ip | 24.5.68.47 | No |
context.userAgent | Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 | No |
context.device.advertisingId | 38400000-8cf0-11bd-b23e-10b96e40000d | No |
Use the Debugger tab on your Segment HTTP API source to confirm events are arriving. The Debugger shows each incoming event with its type, name, and full payload, so you can check that identifiers, properties, and context fields are mapped as expected. Because Segment can return a 200 response even when events are rejected, the Debugger is the most reliable way to confirm events were accepted.
To confirm events are reaching your connected destinations, open each destination in Segment and review its Event Delivery dashboard, which shows delivered events and any failures by error type.
