Registers an external segment on the integration.

Send the segment display name (e.g. Tier Gold). Optionally send external_url (a link to this segment on your platform) and set the segment lifetime via expiration or permanent. Bloomreach returns a server-generated id and bloomreach_url (a link to this segment in Marketing, for example in your admin UI or audit logs).

URLs

• external_url (request, optional): deep link on your platform. When provided, Bloomreach uses it in the UI so users can open the segment in your system.
• bloomreach_url (response, server-generated): deep link in Marketing for this registered segment. Your systems can store or display it so users can open the segment in Bloomreach.

Expiration

Segment lifetime is determined as follows (mutually exclusive: do not send both expiration and permanent: true):

• permanent: true: the segment does not expire; expiration must not be sent
• expiration omitted and permanent not set: expiration defaults to 30 days from registration; the computed timestamp is returned in the 201 response
• expiration provided: Unix timestamp in seconds when the segment registration expires; must be a positive integer greater than the request time

The expiration returned in the 201 response reflects the value at registration time. It may be changed later in Marketing. Do not treat it as the source of truth for when to stop membership updates. Continue sending updates until the API returns segment_expired.

Sending both expiration and permanent: true returns 400 Bad Request.

⚠️

Important

Expiration isn't enforced: Marketing doesn't automatically enforce the expiration value. You need to manually delete the properties that store external segment information.

Segment name

Send the segment display name as used in your system. Bloomreach normalizes it before registration. If the input contains a zero byte, dot (.), or dollar sign ($), each occurrence is replaced with __ as part of that normalization. You do not need to strip or escape these characters before sending the request. Different display names can normalize to the same value and return 409 Conflict.

If the name is not valid after normalization (for example whitespace-only, empty after normalization, or not accepted as a segment identifier in Marketing), the API returns 400 Bad Request with invalid_segment_name.

If a segment with the same normalized name is already registered on this integration, the API returns 409 Conflict. This duplicate-name check is a temporary restriction and may be relaxed in a future API version.

Call this endpoint before pushing membership updates for a new segment.