Description
Update an existing external segment. By default the segment's members are replaced by the members in the request, but individual members can also be added or removed with the action field, without sending the full membership.
In case update fails or is aborted, the segment is left exactly as it was. If there is no mapping for a member being imported, then this particular member is skipped.
The maximum number of members in the segment is 2 000 000.
-
The user must be authenticated and have write permissions to the segment's siteGroup.
-
This API is not compatible with execution as a persisted request, as it is designed to support uploading relatively large numbers of segment members in server-to-server integration scenarios, while persisted requests are designed to support integrations with unauthenticated clients, primarily browsers.
Request
The request object has the following fields.
|
Name |
Type |
Required |
Description |
|---|---|---|---|
|
|
String |
Yes |
Identifier for the external segment to be updated. NB. |
|
|
String |
No |
What to do with the members in the request: |
|
|
Boolean |
No |
Ignore invalid users without interrupting the request. The default value is |
|
|
Array of Objects |
Yes |
Array of |
The member object has the the following fields:
|
Name |
Type |
Required |
Description |
|---|---|---|---|
|
|
String |
Yes |
The type of user identifier. Type can be cx or a customer prefix. |
|
|
String |
Yes |
Identifier for the member. |
Actions
|
|
Effect |
|---|---|
|
|
Every existing member is replaced by the members in the request. This is the default, and the behaviour of requests that do not specify an action. |
|
|
The members in the request are added to the segment. Members already in the segment are left alone, and a member that is already there is not added twice. |
|
|
The members in the request are removed from the segment. Every other member is left alone, and removing a member that is not in the segment does nothing. |
With add and remove, an empty members array leaves the segment unchanged.
action and ignoreInvalid may appear in either order, but both must come after segmentId and before members.
Validation
ignoreInvalid behaves the same way for every action. A member is invalid when its type is not one the caller may import under, or when its id is not a well formed identifier of that type. With ignoreInvalid set to true such members are skipped and the rest of the request is applied; otherwise the request is rejected and the segment is left unchanged.
A member that is valid but that does not resolve to a known user is skipped rather than rejected, whatever the action, and whatever the value of ignoreInvalid.
Removing members by an external identifier
Segment members are stored by the identity they resolve to, not by the identifier they were sent as. A removal therefore matches on the identity the identifier resolves to at the time of the removal. If a user's identities have since been merged or changed, a removal sent with the identifier the member was added under may match nobody, or may match more users than intended. Removing by cx identifiers avoids this, since they resolve to exactly one user.
Limits
|
Limit |
Value |
When it is exceeded |
|---|---|---|
|
Members in a segment |
2 000 000 |
An |
|
Members in one |
100 000 |
The request is rejected. Send the membership as a |
|
|
Once every 30 minutes |
The request is rejected. Collect the changes and send them in one request instead. |
The interval on add and remove is counted from the previous update of that segment, whatever its action. A rejected request has changed nothing and can be retried once the interval has passed. replace is not subject to it.
Partial updates are not a real time mechanism. Segment membership is resolved against user identities, imported, and fed to the rest of the platform, which takes several seconds on its own. Use add and remove to avoid resending a membership that has barely changed, not to reflect a change immediately.
Response
The response for a successful query is an empty object: {}
Errors
|
Status |
Meaning |
|---|---|
|
400 |
The request is malformed, |
|
403 |
The user does not have write permission for the segment's siteGroup. |
|
429 |
An |
Examples
$ python cx.py /segment/data/update '{"segmentId":"8nop087ng0iq", "members":[{"type":"exp", "id":"user2"}, {"type":"exp", "id":"user4"}]}'
{}
$ python cx.py /segment/data/update '{"segmentId":"8nop087ng0iq", "members":[]}'
{}
# Add users to a segment without replacing the members already in it
$ python cx.py /segment/data/update '{"segmentId":"8nop087ng0iq", "action":"add", "members":[{"type":"exp", "id":"user5"}, {"type":"exp", "id":"user6"}]}'
{}
# Remove a single user, for instance once they have completed a survey
$ python cx.py /segment/data/update '{"segmentId":"8nop087ng0iq", "action":"remove", "members":[{"type":"cx", "id":"user123"}]}'
{}
# Update only the 'user1'
$ python cx.py /segment/data/update '{"segmentId":"8nop087ng0iq", "ignoreInvalid":"true", "members":[{"type":"exp", "id":"user1"}, {"type":"wrongPrefix", "id":"user2"}]}'
{}
# Error: ignoreInvalid is not defined but there is an invalid user
$ python cx.py /segment/data/update '{"segmentId":"8nop087ng0iq" "members":[{"type":"exp", "id":"user1"}, {"type":"wrongPrefix", "id":"user2"}]}'