Push membership updates batch

post

{instance_base_url}/intg/external-segments/v1.0/{integration_id}/membership-updates

Sends batches of segment membership changes.

Request body is a JSON object with emitted_at, sync_type, and an updates array of membership changes. Segments must be registered via POST …/v1.0/…/segments before membership updates are accepted.

Request restrictions

Do not send both join and leave for the same segment and the same customer ID in one request. Processing order is not guaranteed; the outcome is non-deterministic.

Response semantics

200 OK: every customer ID in the request was processed successfully
207 Multi-Status: partial success; see the 207 response for processing error codes and retry vs non-retry guidance

Rate limiting

Two limits apply to every membership update request per workspace (respect both).

Request rate: at most one request per second per workspace. Checked first. A second request within one second returns 429 Too Many Requests with Retry-After: 1, even when the batch is small.
Customer ID allowance: a shared per-workspace budget for customer IDs in updates. Refills at 1,000 IDs/s, up to 10,000 at a time. Each join and leave entry counts every ID in customer_ids toward the budget. Exceeding the remaining allowance returns 429 with Retry-After set to when capacity is available.

Each request may include at most 10,000 customer identifiers in total across all updates entries. The raw JSON request body must not exceed 22 MiB (23,068,672 bytes). Split larger syncs across multiple requests and stay within all limits above.

Honor Retry-After (seconds) before retrying a 429 response.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

integration_id

uuid

required

Integration identifier embedded in the endpoint URL provided at setup

Body Params

JSON object with emitted_at, sync_type, and an updates array. At most 10,000 customer identifiers in total across all updates entries per request. Raw body size must not exceed 22 MiB (23,068,672 bytes).

Membership update request. Do not include both join and leave for the same segment and the same customer ID in updates. Processing order is not guaranteed and the result is non-deterministic.

emitted_at

int64

required

1 to 999999999999

Unix timestamp in seconds when the source system emitted this batch. Must be a positive integer. Values above 999999999999 are rejected (typically indicates a millisecond timestamp sent by mistake).

sync_type

string

enum

required

Declares whether this batch is the first membership load for the affected segment(s) or an incremental update. Used for tracking and processing semantics; applies to all entries in updates.

initial: use when pushing membership for a segment for the first time after POST …/segments. Send the complete current membership with action: join only (leave is not used on initial load). Large memberships may require multiple initial requests until the full snapshot is sent.
delta: use for all subsequent membership changes after the initial load. Send join and/or leave entries for adds and removals since the last sync.

Allowed:

updates

array of objects

required

length ≥ 1

Membership changes to process. Each entry applies one action to one segment. Do not list the same customer ID under both join and leave for the same segment in this array. Validation error messages refer to entries as updates[N].… where N is the zero-based index in this array.

updates*

segment

object

required

Segment reference in a membership update: the id from POST …/segments.

action

string

enum

required

Membership change to apply for all customer IDs in customer_ids for this segment. Do not send both join and leave for the same segment and customer in one request.

Allowed:

customer_ids

array of strings

required

length ≥ 1

Customer identifiers in the field mapped at integration setup. Depending on the integration configuration, identifiers with no matching Bloomreach profile are either upserted (a new profile is created) or ignored.

Each identifier must not exceed 256 bytes, must contain at least one alphanumeric character, and must not be the literal null or undefined.

An identifier that breaks any of these does not fail the request: it is reported on its own as invalid_customer_id in a 207 response while every other identifier is processed. The size limit is measured in bytes, so multi-byte characters count more than once.

customer_ids*

Responses

502

Bad gateway. The request did not reach the API application. The response body may not be JSON. Retry later without parsing the body.

503

Service temporarily unavailable. The request did not reach the API application. The response body may not be JSON. Retry later without parsing the body.

504

Gateway timeout. Processing did not complete in time. Retry later.

Language

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

Push membership updates batch

Request restrictions

Response semantics

Rate limiting

Processing errors

Retryable

Non-retryable

200All customer IDs processed successfully

Processing errors

Retryable

Non-retryable

400Invalid payload (malformed body or validation failure). Field paths in message use the updates[N].… prefix where N is the zero-based index in the updates array. Top-level fields (for example emitted_at, sync_type) appear without that prefix.

401Missing or invalid access key

403Integration disabled or not authorized for this instance

404Integration not found

405HTTP method not allowed (only POST is supported on these endpoints)

413Request body exceeds the maximum allowed size of 22 MiB (23,068,672 bytes) for membership update batches.

429Rate limit exceeded. For membership updates this may be the one request per second cap per workspace (Retry-After: 1) or exhaustion of the shared customer-ID allowance. Retry only after the number of seconds in Retry-After.

500Internal server error