Customer Segment Service

Download OpenAPI specification:Download

The Customer Segment Service allows you to define segments for different customers so that you can prepare customer specific marketing campaigns, or prepare personalized content for different customers in each segment

Key Features:

Manage customer segmentation for different purposes
Assign customers to segments based on some quantitative characteristics, for example demographic, geographic, behavioral, or other.

Key Benefits:

Use customer segments to create marketing campaigns targeted towards a specific audience, for instance, the gold segment or the Bosch segment (product-specific).
Determine the appropriate customers easily within the corresponding customer segment and provide relevant personalized content.

Segments

Manage segments

Creating a customer segment

Preview Creates a new customer segment.

Required scopes

customersegment.segment_manage - required to create a customer segment

SecurityOAuth2

Request

path Parameters

tenant

required

string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: Always write the tenant name in lowercase.

header Parameters

Content-Language

string

The Content-Language request HTTP header defines language(s) of the payload.

Example: en

Request Body schema: application/json

id	string Unique identifier of the customer segment. It will be auto-generated if not provided.
required	object Localized name of the customer segment.
	object Localized description of the customer segment.
	object Determines the time frame in which the customer segment is valid.
status	string Determines whether the customer segment is active or not. If not provided the value is set to `INACTIVE` Enum: "ACTIVE" "INACTIVE"
siteCode required	string Determines for which site the customer segment is available.
	object A key-value map of additional attributes.
	object (MetadataCreate)

Responses

201

Customer segment was successfully created.

400

Bad request due to validation, incorrect parameters, etc.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

409

Conflict

post/{tenant}/segments

Request samples

application/json

{"id": "628cd20c6e8b2432b6346ca6",
"name": {"en": "Golden Segment"
},
"description": {"en": "Golden Segment"
},
"validity": {"from": "2024-04-17T08:00:00.000Z",
"to": "2025-04-17T08:00:00.000Z"
},
"status": "ACTIVE",
"siteCode": "main"
}

Response samples

201
400
401
403
409

application/json

{"id": "628cd20c6e8b2432b6346ca6"
}

Retrieving all customer segments

Preview Retrieves all customer segments.

Required scopes

customersegment.segment_read - allows you to retrieve all customer segments
customersegment.segment_read_own - allows customers to retrieve customer segments which they are assigned to

SecurityOAuth2

Request

path Parameters

tenant

required

string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: Always write the tenant name in lowercase.

query Parameters

q	string A standard query parameter is used to search for specific values. See: Standard practises - Query parameter
pageSize	string The number of documents to be retrieved per page.
pageNumber	string The page number to be retrieved. The size of the pages should be specified by the pageSize parameter.
sort	string List of properties used to sort the results, separated by colons.
fields	string Fields to be returned in the response.

header Parameters

X-Total-Count	boolean Flag indicating whether the total number of retrieved results should be returned.
Accept-Language	string The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, the default system language is assumed. It can be a priority list working as a fallback mechanism.

Responses

200

Customer segments were successfully retrieved.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

get/{tenant}/segments

Request samples

Response samples

200
401
403

application/json

[{"id": "628cd20c6e8b2432b6346ca6",
"name": {"en": "Golden Segment"
},
"description": {"en": "Golden Segment"
},
"validity": {"from": "2024-04-17T08:00:00.000Z",
"to": "2025-04-17T08:00:00.000Z"
},
"status": "ACTIVE",
"siteCode": "main",
"metadata": {"createdAt": "2024-05-14T12:00:00.000Z",
"modifiedAt": "2024-05-14T12:00:00.000Z",
"version": 1
}
},
{"id": "61ge81e13562e22001h6cf456",
"name": {"en": "Platinum Segment"
},
"description": {"en": "Platinum Segment"
},
"validity": {"from": "2024-07-20T08:00:00.000Z",
"to": "2025-07-20T08:00:00.000Z"
},
"status": "INACTIVE",
"siteCode": "main",
"metadata": {"createdAt": "2024-05-14T12:00:00.000Z",
"modifiedAt": "2024-05-14T12:00:00.000Z",
"version": 1
}
}
]

Searching with parameters for customer segments

Preview Returns all customer segments that match provided criteria.

Required scopes

customersegment.segment_read - allows you to retrieve all customer segments
customersegment.segment_read_own - allows customers to retrieve customer segments which they are assigned to

SecurityOAuth2

Request

path Parameters

tenant

required

string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: Always write the tenant name in lowercase.

query Parameters

pageSize	string The number of documents to be retrieved per page.
pageNumber	string The page number to be retrieved. The size of the pages should be specified by the pageSize parameter.
sort	string List of properties used to sort the results, separated by colons.
fields	string Fields to be returned in the response.

header Parameters

X-Total-Count	boolean Flag indicating whether the total number of retrieved results should be returned.
Accept-Language	string The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, the default system language is assumed. It can be a priority list working as a fallback mechanism.

Request Body schema: application/json

q	string A standard query parameter is used to search for specific values. See: Standard practises - Query parameter

Responses

200

Customer segments were successfully retrieved.

400

Bad request due to validation, incorrect parameters, etc.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

post/{tenant}/segments/search

Request samples

application/json

{"q": "siteCode:main"
}

Response samples

200
400
401
403

application/json

[{"id": "628cd20c6e8b2432b6346ca6",
"name": {"en": "Golden Segment"
},
"description": {"en": "Golden Segment"
},
"validity": {"from": "2024-04-17T08:00:00.000Z",
"to": "2025-04-17T08:00:00.000Z"
},
"status": "ACTIVE",
"siteCode": "main",
"metadata": {"createdAt": "2024-05-14T12:00:00.000Z",
"modifiedAt": "2024-05-14T12:00:00.000Z",
"version": 1
}
},
{"id": "61ge81e13562e22001h6cf456",
"name": {"en": "Platinum Segment"
},
"description": {"en": "Platinum Segment"
},
"validity": {"from": "2024-07-20T08:00:00.000Z",
"to": "2025-07-20T08:00:00.000Z"
},
"status": "INACTIVE",
"siteCode": "main",
"metadata": {"createdAt": "2024-05-14T12:00:00.000Z",
"modifiedAt": "2024-05-14T12:00:00.000Z",
"version": 1
}
}
]

Retrieving a customer segment

Preview Retrieves segment with specified ID.

Required scopes

customersegment.segment_read - allows you to retrieve a customer segment

SecurityOAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: Always write the tenant name in lowercase.
segmentId required	string Unique identifier of the customer segment.

query Parameters

fields

string

Fields to be returned in the response.

header Parameters

Accept-Language

string

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, the default system language is assumed. It can be a priority list working as a fallback mechanism.

Responses

200

Customer segment successfully retrieved.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

404

Resource not found

get/{tenant}/segments/{segmentId}

Request samples

Response samples

200
401
403
404

application/json

{"id": "628cd20c6e8b2432b6346ca6",
"name": {"en": "Golden Segment"
},
"description": {"en": "Golden Segment"
},
"validity": {"from": "2024-04-17T08:00:00.000Z",
"to": "2025-04-17T08:00:00.000Z"
},
"status": "ACTIVE",
"siteCode": "main",
"metadata": {"createdAt": "2024-05-14T12:00:00.000Z",
"modifiedAt": "2024-05-14T12:00:00.000Z",
"version": 1
}
}

Updating a customer segment

Preview Performs UPSERT operation. If a segment with specified ID exists in the system, then it is updated. If it doesn't exist, a new customer segment is created.

Required scopes

customersegment.segment_manage - required to update a customer segment

SecurityOAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: Always write the tenant name in lowercase.
segmentId required	string Unique identifier of the customer segment.

header Parameters

Content-Language

string

The Content-Language request HTTP header defines language(s) of the payload.

Example: en

Request Body schema: application/json

required	object Localized name of the customer segment.
	object Localized description of the customer segment.
	object Determines the time frame in which the customer segment is valid.
status	string Determines whether the customer segment is active or not. If not provided the value is set to `INACTIVE` Enum: "ACTIVE" "INACTIVE"
siteCode required	string Determines for which site the customer segment is available.
	object A key-value map of additional attributes.
	object (MetadataUpdate)

Responses

201

Customer segment wasn't found. A new customer segment was successfully created.

204

Customer segment was successfully updated.

400

Bad request due to validation, incorrect parameters, etc.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

409

Conflict

put/{tenant}/segments/{segmentId}

Request samples

application/json

{"name": {"en": "Golden Segment"
},
"description": {"en": "Golden Segment"
},
"validity": {"from": "2024-04-17T08:00:00.000Z",
"to": "2025-04-17T08:00:00.000Z"
},
"status": "ACTIVE",
"siteCode": "main",
"metadata": {"version": 1
}
}

Response samples

201
400
401
403
409

application/json

{"id": "628cd20c6e8b2432b6346ca6"
}

Patching a customer segment

Preview Performs partial update of a segment.

The patch request consists of set of operation, that should be defined according to RFC-6902 standard.

Required scopes

customersegment.segment_manage - required to update a customer segment

SecurityOAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: Always write the tenant name in lowercase.
segmentId required	string Unique identifier of the customer segment.

header Parameters

Content-Language

string

The Content-Language request HTTP header defines language(s) of the payload.

Example: en

Request Body schema: application/json

Array

op required	string Indicates an operation which should be done on a return. Available operations: `add` `remove` and `replace` Enum: "add" "remove" "replace"
path required	string Indicates a path for which the value should be applied. For example:`/mixins/additionalAttributes/externalId`, `/name`, `/status`
	object or string or number Indicates a value that should be changed or added. The value can be of a primitive type, like string, number, boolean or it can be an object or an array.

Responses

204

Customer segment was successfully updated.

400

Bad request due to validation, incorrect parameters, etc.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

404

Resource not found

patch/{tenant}/segments/{segmentId}

Request samples

application/json

[{"op": "replace",
"path": "/status",
"value": "INACTIVE"
}
]

Response samples

400
401
403
404

application/json

{"code": 400,
"status": "Bad Request",
"message": "Validation problem with request body."
}

Deleting a customer segment

Preview Removes segment with specified ID.

Important: If you want to delete a segment that has items or customers assigned to it, you need to set the forceDelete query parameter to true. In this case, all items and customers assignments will be deleted as well.

Required scopes

customersegment.segment_manage - required to delete a customer segment

SecurityOAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: Always write the tenant name in lowercase.
segmentId required	string Unique identifier of the customer segment.

query Parameters

forceDelete

boolean

Default: false

If set to true and the segment has items or customers assigned to it, both the segment and the segment assignments will be deleted.
If set to false or not specified and the segment has items or customers assigned to it, the endpoint will respond with the 400 error.

Responses

204

Customer segment was successfully deleted.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

delete/{tenant}/segments/{segmentId}

Request samples

Response samples

401
403

application/json

{"fault": {"faultstring": "Invalid access token",
"detail": {"errorcode": "oauth.v2.InvalidAccessToken"
}
}
}

Creating customer segments in bulk

Preview Creates multiple customer segments.

Required scopes

customersegment.segment_manage - required to create customer segments

SecurityOAuth2

Request

path Parameters

tenant

required

string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: Always write the tenant name in lowercase.

header Parameters

Content-Language

string

The Content-Language request HTTP header defines language(s) of the payload.

Example: en

Request Body schema: application/json

Array

id	string Unique identifier of the customer segment. It will be auto-generated if not provided.
required	object Localized name of the customer segment.
	object Localized description of the customer segment.
	object Determines the time frame in which the customer segment is valid.
status	string Determines whether the customer segment is active or not. If not provided the value is set to `INACTIVE` Enum: "ACTIVE" "INACTIVE"
siteCode required	string Determines for which site the customer segment is available.
	object A key-value map of additional attributes.
	object (MetadataCreate)

Responses

207

Multi-status response.

400

Bad request due to validation, incorrect parameters, etc.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

post/{tenant}/segments/bulk

Request samples

application/json

[{"id": "628cd20c6e8b2432b6346ca6",
"name": {"en": "Golden Segment"
},
"description": {"en": "Golden Segment"
},
"validity": {"from": "2024-04-17T08:00:00.000Z",
"to": "2025-04-17T08:00:00.000Z"
},
"status": "ACTIVE",
"siteCode": "main"
},
{"id": "61ge81e13562e22001h6cf456",
"name": {"en": "Platinum Segment"
},
"description": {"en": "Platinum Segment"
},
"validity": {"from": "2024-07-20T08:00:00.000Z",
"to": "2025-07-20T08:00:00.000Z"
},
"status": "INACTIVE",
"siteCode": "main"
}
]

Response samples

207
400
401
403

application/json

[{"index": 1,
"id": "628cd20c6e8b2432b6346ca6",
"code": 201,
"status": "Created"
},
{"index": 2,
"code": 400,
"status": "Bad Request",
"message": "Validation problem with request body."
}
]

Updating customer segments in bulk

Preview Performs UPSERT operation for multiple customer segments. If a segment with specified ID exists in the system, then it is updated. If it doesn't exist, a new customer segment is created.

Required scopes

customersegment.segment_manage - required to update customer segments

SecurityOAuth2

Request

path Parameters

tenant

required

string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: Always write the tenant name in lowercase.

header Parameters

Content-Language

string

The Content-Language request HTTP header defines language(s) of the payload.

Example: en

Request Body schema: application/json

Array

id	string Unique identifier of the customer segment.
required	object Localized name of the customer segment.
	object Localized description of the customer segment.
	object Determines the time frame in which the customer segment is valid.
status	string Determines whether the customer segment is active or not. If not provided the value is set to `INACTIVE` Enum: "ACTIVE" "INACTIVE"
siteCode required	string Determines for which site the customer segment is available.
	object A key-value map of additional attributes.
	object (MetadataUpdate)

Responses

207

Multi-status response.

400

Bad request due to validation, incorrect parameters, etc.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

put/{tenant}/segments/bulk

Request samples

application/json

[{"allOf": [{"id": "628cd20c6e8b2432b6346ca6"
},
{"name": {"en": "Golden Segment"
},
"description": {"en": "Golden Segment"
},
"validity": {"from": "2024-04-17T08:00:00.000Z",
"to": "2025-04-17T08:00:00.000Z"
},
"status": "ACTIVE",
"siteCode": "main",
"metadata": {"version": 1
}
}
]
},
{"id": "61ge81e13562e22001h6cf456",
"name": {"en": "Platinum Segment"
},
"description": {"en": "Platinum Segment"
},
"validity": {"from": "2024-07-20T08:00:00.000Z",
"to": "2025-07-20T08:00:00.000Z"
},
"status": "INACTIVE",
"siteCode": "main",
"metadata": {"version": 2
}
}
]

Response samples

207
400
401
403

application/json

[{"index": 1,
"id": "628cd20c6e8b2432b6346ca6",
"code": 204,
"status": "OK"
},
{"index": 2,
"code": 400,
"status": "Bad Request",
"message": "Validation problem with request body."
}
]

Deleting customer segments in bulk

Preview Removes multiple customer segments.

The IDs of customer segments for deletion should be defined in the request body as an array of strings.

Example: `["firstId", "secondId", "thirdId"]`

Important: If you want to delete a segment that has items or customers assigned to it, you need to set the forceDelete query parameter to true. In this case, all items and customers assignments will be deleted as well.

Required scopes

customersegment.segment_manage - required to delete customer segments

SecurityOAuth2

Request

path Parameters

tenant

required

string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: Always write the tenant name in lowercase.

query Parameters

forceDelete

boolean

Default: false

If set to true and the segment has items or customers assigned to it, both the segment and the segment assignments will be deleted.
If set to false or not specified and the segment has items or customers assigned to it, the endpoint will respond with the 400 error.

Responses

207

Multi-status response.

400

Bad request due to validation, incorrect parameters, etc.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

delete/{tenant}/segments/bulk

Request samples

Response samples

207
400
401
403

application/json

[{"index": 1,
"id": "628cd20c6e8b2432b6346ca6",
"code": 204,
"status": "OK"
},
{"index": 2,
"id": "61ge81e13562e22001h6cf456",
"code": 204,
"status": "OK"
}
]

Customers Assignments

Manage customer assignments to segments

Retrieving all customer segment customers

Preview Retrieves all customer assignments for a given customer segment.

Required scopes

customersegment.segment_read - allows you to retrieve customer segment customers
customersegment.segment_read_own - allows customers to retrieve their own assignments to a customer segment

SecurityOAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: Always write the tenant name in lowercase.
segmentId required	string Unique identifier of the customer segment.

query Parameters

q	string A standard query parameter is used to search for specific values. See: Standard practises - Query parameter
pageSize	string The number of documents to be retrieved per page.
pageNumber	string The page number to be retrieved. The size of the pages should be specified by the pageSize parameter.
sort	string List of properties used to sort the results, separated by colons.
fields	string Fields to be returned in the response.

header Parameters

X-Total-Count

boolean

Flag indicating whether the total number of retrieved results should be returned.

Responses

200

Customer segment customers were successfully retrieved.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

get/{tenant}/segments/{segmentId}/customers

Request samples

Response samples

200
401
403

application/json

[{"customer": {"id": "98029737",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@email.com"
},
"legalEntity": {"id": "660af2af69babe3cf6e40771",
"name": "SomeCompany"
},
"assignmentType": "MANUAL",
"metadata": {"createdAt": "2024-10-12T12:00:00.000Z",
"modifiedAt": "2024-10-12T12:00:00.000Z",
"version": 1
}
},
{"customer": {"customerId": "18249883",
"firstName": "Jack",
"lastName": "Smith",
"email": "jack.smith@email.com"
},
"legalEntity": {"id": "448gh29h1d0b5453g6346df6",
"department": "AnotherCompany"
},
"assignmentType": "MANUAL",
"metadata": {"createdAt": "2024-10-16T12:00:00.000Z",
"modifiedAt": "2024-10-16T12:00:00.000Z",
"version": 1
}
}
]

Searching with parameters for customer assignments

Preview Returns all customer assignments that match provided criteria.

Required scopes

customersegment.segment_read - allows you to retrieve customer segment customers
customersegment.segment_read_own - allows customers to retrieve their own assignments to a customer segment

SecurityOAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: Always write the tenant name in lowercase.
segmentId required	string Unique identifier of the customer segment.

query Parameters

pageSize	string The number of documents to be retrieved per page.
pageNumber	string The page number to be retrieved. The size of the pages should be specified by the pageSize parameter.
sort	string List of properties used to sort the results, separated by colons.
fields	string Fields to be returned in the response.

header Parameters

X-Total-Count

boolean

Flag indicating whether the total number of retrieved results should be returned.

Request Body schema: application/json

q	string A standard query parameter is used to search for specific values. See: Standard practises - Query parameter

Responses

200

Customer segment customers were successfully retrieved.

400

Bad request due to validation, incorrect parameters, etc.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

post/{tenant}/segments/{segmentId}/customers/search

Request samples

application/json

{"q": "assignmentType:MANUAL"
}

Response samples

200
400
401
403

application/json

[{"customer": {"id": "98029737",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@email.com"
},
"legalEntity": {"id": "660af2af69babe3cf6e40771",
"name": "SomeCompany"
},
"assignmentType": "MANUAL",
"metadata": {"createdAt": "2024-10-12T12:00:00.000Z",
"modifiedAt": "2024-10-12T12:00:00.000Z",
"version": 1
}
},
{"customer": {"customerId": "18249883",
"firstName": "Jack",
"lastName": "Smith",
"email": "jack.smith@email.com"
},
"legalEntity": {"id": "448gh29h1d0b5453g6346df6",
"department": "AnotherCompany"
},
"assignmentType": "MANUAL",
"metadata": {"createdAt": "2024-10-16T12:00:00.000Z",
"modifiedAt": "2024-10-16T12:00:00.000Z",
"version": 1
}
}
]

Retrieving a customer segment customer

Preview Retrieves a customer with specified customerId and companyId assigned to a customer segment.

Required scopes

customersegment.segment_read - allows you to retrieve a customer segment customer

SecurityOAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: Always write the tenant name in lowercase.
segmentId required	string Unique identifier of the customer segment.
customerId required	string Unique identifier of the customer which is added to a customer segment.
legalEntityId required	string Unique identifier of the legal entity which customer is assigned to.

query Parameters

fields

string

Fields to be returned in the response.

Responses

200

Customer segment customer was successfully retrieved.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

404

Resource not found

get/{tenant}/segments/{segmentId}/customers/{customerId}/{legalEntityId}

Request samples

Response samples

200
401
403
404

application/json

{"customer": {"id": "98029737",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@email.com"
},
"legalEntity": {"id": "660af2af69babe3cf6e40771",
"name": "SomeCompany"
},
"assignmentType": "MANUAL",
"metadata": {"createdAt": "2024-10-12T12:00:00.000Z",
"modifiedAt": "2024-10-12T12:00:00.000Z",
"version": 1
}
}

Updating a customer segment customer

Preview Performs UPSERT operation. Updates a customer assigned to a customer segment. A new customer assignment is created if it's not present in the system.

Required scopes

customersegment.segment_manage - required to add and modify customer assignments

SecurityOAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: Always write the tenant name in lowercase.
segmentId required	string Unique identifier of the customer segment.
customerId required	string Unique identifier of the customer which is added to a customer segment.
legalEntityId required	string Unique identifier of the legal entity which customer is assigned to.

Request Body schema: application/json

mixins	object A key-value map of additional attributes.
	object (MetadataUpdate)

Responses

201

A new customer assigment was successfully created.

204

Customer assignment was successfully updated.

400

Bad request due to validation, incorrect parameters, etc.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

409

Conflict

put/{tenant}/segments/{segmentId}/customers/{customerId}/{legalEntityId}

Request samples

application/json

{"mixins": {"someAdditionalAttribute": "someValue"
},
"metadata": {"mixins": {"someAdditionalAttribute": "https://res.cloudinary.com/saas-ag/raw/upload/v1600077014/schemata/additionalAttribute.json"
},
"version": 2
}
}

Response samples

400
401
403
409

application/json

{"code": 400,
"status": "Bad Request",
"message": "Validation problem with request body."
}

Removing a customer from customer segment

Preview Removes customer assignment.

Required scopes

customersegment.segment_manage - required to delete customer assignments

SecurityOAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: Always write the tenant name in lowercase.
segmentId required	string Unique identifier of the customer segment.
customerId required	string Unique identifier of the customer which is added to a customer segment.
legalEntityId required	string Unique identifier of the legal entity which customer is assigned to.

Responses

204

Customer assignment was successfully removed.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

delete/{tenant}/segments/{segmentId}/customers/{customerId}/{legalEntityId}

Request samples

Response samples

401
403

application/json

{"fault": {"faultstring": "Invalid access token",
"detail": {"errorcode": "oauth.v2.InvalidAccessToken"
}
}
}

Updating customer segment customers in bulk

Preview Performs UPSERT operation. Updates multiple customer assignments to a customer segment.

Required scopes

customersegment.segment_manage - required to add and modify customer assignments

SecurityOAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: Always write the tenant name in lowercase.
segmentId required	string Unique identifier of the customer segment.

Request Body schema: application/json

Array

customerId	any Unique identifier of an existing customer.
legalEntityId	any Unique identifier of an existing legal entity.
mixins	object A key-value map of additional attributes.
	object (MetadataUpdate)

Responses

207

Multi-status response.

400

Bad request due to validation, incorrect parameters, etc.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

put/{tenant}/segments/{segmentId}/customers/bulk

Request samples

application/json

[{"allOf": [{"customerId": "98029737"
},
{"legalEntityId": "660af2af69babe3cf6e40771"
},
{"mixins": {"someAdditionalAttribute": "someValue"
},
"metadata": {"mixins": {"someAdditionalAttribute": "https://res.cloudinary.com/saas-ag/raw/upload/v1600077014/schemata/additionalAttribute.json"
},
"version": 2
}
}
]
},
{"customerId": "18249883",
"legalEntityId": "628cd20c6e8b2432b6346ca6",
"metadata": {"version": 1
}
}
]

Response samples

207
400
401
403

application/json

[{"index": 1,
"code": 204,
"status": "OK"
},
{"index": 2,
"code": 400,
"status": "Bad Request",
"message": "Validation problem with request body."
}
]

Removing customers from customer segment in bulk

Preview Removes multiple customer assignments to a customer segment.

The request body for this endpoint is array of objects with `customerId` and `legalEntityId` fields.

Example: `[{"customerId": "firstCustomerId", "legalEntityId": "firstLegalEntityId"}, {"customerId": "secondCustomerId", "legalEntityId": "secondLegalEntityId"}, {"customerId": "thirdCustomerId", "legalEntityId": "thirdLegalEntityId"}]`

Required scopes

customersegment.segment_manage - required to delete customer assignments

SecurityOAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: Always write the tenant name in lowercase.
segmentId required	string Unique identifier of the customer segment.

Responses

207

Multi-status response.

400

Bad request due to validation, incorrect parameters, etc.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

delete/{tenant}/segments/{segmentId}/customers/bulk

Request samples

Response samples

207
400
401
403

application/json

[{"index": 1,
"code": 204,
"status": "OK"
},
{"index": 2,
"code": 204,
"status": "OK"
}
]

Items Assignments

Manage item assignments to segments

Retrieving all item assignments for a customer segment

Preview Retrieves all item assignments for a given customer segment.

Required scopes

customersegment.segment_read - allows you to retrieve all item assignments

SecurityOAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: Always write the tenant name in lowercase.
segmentId required	string Unique identifier of the customer segment.

query Parameters

q	string A standard query parameter is used to search for specific values. See: Standard practises - Query parameter
pageSize	string The number of documents to be retrieved per page.
pageNumber	string The page number to be retrieved. The size of the pages should be specified by the pageSize parameter.
sort	string List of properties used to sort the results, separated by colons.
fields	string Fields to be returned in the response.

header Parameters

X-Total-Count	boolean Flag indicating whether the total number of retrieved results should be returned.
Accept-Language	string The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, the default system language is assumed. It can be a priority list working as a fallback mechanism.

Responses

200

Customer segment assignments were successfully retrieved.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

get/{tenant}/segments/{segmentId}/items

Request samples

Response samples

200
401
403

application/json

[{"item": {"id": "12468504",
"code": "123",
"name": {"en": "Hammer"
}
},
"type": "PRODUCT",
"metadata": {"createdAt": "2024-10-12T12:00:00.000Z",
"modifiedAt": "2024-10-12T12:00:00.000Z",
"version": 1
}
},
{"item": {"id": "12849186",
"code": "456",
"name": {"en": "Screwdriver"
}
},
"type": "PRODUCT",
"metadata": {"createdAt": "2024-10-12T12:00:00.000Z",
"modifiedAt": "2024-10-12T12:00:00.000Z",
"version": 1
}
}
]

Returns all item assignments for a customer segment

Preview Retrieves all item assignments for a given customer segment.

Required scopes

customersegment.segment_read - allows you to retrieve all item assignments

SecurityOAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: Always write the tenant name in lowercase.
segmentId required	string Unique identifier of the customer segment.

query Parameters

pageSize	string The number of documents to be retrieved per page.
pageNumber	string The page number to be retrieved. The size of the pages should be specified by the pageSize parameter.
sort	string List of properties used to sort the results, separated by colons.
fields	string Fields to be returned in the response.

header Parameters

X-Total-Count	boolean Flag indicating whether the total number of retrieved results should be returned.
Accept-Language	string The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, the default system language is assumed. It can be a priority list working as a fallback mechanism.

Request Body schema: application/json

q	string A standard query parameter is used to search for specific values. See: Standard practises - Query parameter

Responses

200

Customer segment assignments were successfully retrieved.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

post/{tenant}/segments/{segmentId}/items/search

Request samples

application/json

{"q": "type:PRODUCT"
}

Response samples

200
401
403

application/json

[{"item": {"id": "12468504",
"code": "123",
"name": {"en": "Hammer"
}
},
"type": "PRODUCT",
"metadata": {"createdAt": "2024-10-12T12:00:00.000Z",
"modifiedAt": "2024-10-12T12:00:00.000Z",
"version": 1
}
},
{"item": {"id": "12849186",
"code": "456",
"name": {"en": "Screwdriver"
}
},
"type": "PRODUCT",
"metadata": {"createdAt": "2024-10-12T12:00:00.000Z",
"modifiedAt": "2024-10-12T12:00:00.000Z",
"version": 1
}
}
]

Retrieving an item assignment

Preview Retrieves an item assignment by specified ID for a given customer segment.

Required scopes

customersegment.segment_read - allows you to retrieve an item assignment

SecurityOAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: Always write the tenant name in lowercase.
segmentId required	string Unique identifier of the customer segment.
type required	string Determines whether item is a product or category.
itemId required	string Unique identifier of an item which will be assigned to a customer segment.

query Parameters

fields

string

Fields to be returned in the response.

header Parameters

Accept-Language

string

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, the default system language is assumed. It can be a priority list working as a fallback mechanism.

Responses

200

Customer segment item assignment was successfully retrieved.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

404

Resource not found

get/{tenant}/segments/{segmentId}/items/{type}/{itemId}

Request samples

Response samples

200
401
403
404

application/json

{"item": {"id": "12468504",
"code": "123",
"name": {"en": "Hammer"
}
},
"type": "PRODUCT",
"metadata": {"createdAt": "2024-10-12T12:00:00.000Z",
"modifiedAt": "2024-10-12T12:00:00.000Z",
"version": 1
}
}

Updating an item assignment

Preview Performs UPSERT operation. Updates an item assignment to a customer segment. A new item assignment is created if it's not present in the system.

Required scopes

customersegment.segment_manage - required to add and modify item assignments

SecurityOAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: Always write the tenant name in lowercase.
segmentId required	string Unique identifier of the customer segment.
type required	string Determines whether item is a product or category.
itemId required	string Unique identifier of an item which will be assigned to a customer segment.

Request Body schema: application/json

mixins	object A key-value map of additional attributes.
	object (MetadataUpdate)

Responses

201

A new assigment was successfully created.

204

Item assignment was successfully updated.

400

Bad request due to validation, incorrect parameters, etc.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

409

Conflict

put/{tenant}/segments/{segmentId}/items/{type}/{itemId}

Request samples

application/json

{"mixins": {"someAdditionalAttribute": "someValue"
},
"metadata": {"mixins": {"someAdditionalAttribute": "https://res.cloudinary.com/saas-ag/raw/upload/v1600077014/schemata/additionalAttribute.json"
},
"version": 1
}
}

Response samples

400
401
403
409

application/json

{"code": 400,
"status": "Bad Request",
"message": "Validation problem with request body."
}

Removing an assignment

Preview Removes an item assignment.

Required scopes

customersegment.segment_manage - required to delete item assignments

SecurityOAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: Always write the tenant name in lowercase.
segmentId required	string Unique identifier of the customer segment.
type required	string Determines whether item is a product or category.
itemId required	string Unique identifier of an item which will be assigned to a customer segment.

Responses

204

Item assignment was successfully removed.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

delete/{tenant}/segments/{segmentId}/items/{type}/{itemId}

Request samples

Response samples

401
403

application/json

{"fault": {"faultstring": "Invalid access token",
"detail": {"errorcode": "oauth.v2.InvalidAccessToken"
}
}
}

Updating item assignments to a customer segment in bulk

Preview Performs UPSERT operation. Updates multiple item assignments to a customer segments.

Required scopes

customersegment.segment_manage - required to add and modify item assignments

SecurityOAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: Always write the tenant name in lowercase.
segmentId required	string Unique identifier of the customer segment.
type required	string Determines whether item is a product or category.

Request Body schema: application/json

Array

id required	any Unique identifier of an existing product/category (itemId).
mixins	object A key-value map of additional attributes.
	object (MetadataUpdate)

Responses

207

Multi-status response.

400

Bad request due to validation, incorrect parameters, etc.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

put/{tenant}/segments/{segmentId}/items/{type}/bulk

Request samples

application/json

[{"allOf": [{"id": "12468504"
},
{"mixins": {"someAdditionalAttribute": "someValue"
},
"metadata": {"mixins": {"someAdditionalAttribute": "https://res.cloudinary.com/saas-ag/raw/upload/v1600077014/schemata/additionalAttribute.json"
},
"version": 1
}
}
]
},
{"id": "12849186",
"metadata": {"version": 2
}
}
]

Response samples

207
400
401
403

application/json

[{"index": 1,
"code": 204,
"status": "OK"
},
{"index": 2,
"code": 400,
"status": "Bad Request",
"message": "Validation problem with request body."
}
]

Deleting item assignments to a customer segment in bulk

Preview Removes multiple customer segments item assignments.

The IDs of items should be defined in the request body as an array of strings.

Example: `["firstItemId", "secondItemId", "thirdItemId"]`

Required scopes

customersegment.segment_manage - required to delete item assignments

SecurityOAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: Always write the tenant name in lowercase.
segmentId required	string Unique identifier of the customer segment.
type required	string Determines whether item is a product or category.

Responses

207

Multi-status response.

400

Bad request due to validation, incorrect parameters, etc.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

delete/{tenant}/segments/{segmentId}/items/{type}/bulk

Request samples

Response samples

207
400
401
403

application/json

[{"index": 1,
"code": 204,
"status": "OK"
},
{"index": 2,
"code": 204,
"status": "OK"
}
]

Customer Segment Service

Segments

Creating a customer segment

Required scopes

path Parameters

header Parameters

Request Body schema: application/json

Retrieving all customer segments

Required scopes

path Parameters

query Parameters

header Parameters

Searching with parameters for customer segments

Required scopes

path Parameters

query Parameters

header Parameters

Request Body schema: application/json

Retrieving a customer segment

Required scopes

path Parameters

query Parameters

header Parameters

Updating a customer segment

Required scopes

path Parameters

header Parameters

Request Body schema: application/json

Patching a customer segment

Required scopes

path Parameters

header Parameters

Request Body schema: application/json

Deleting a customer segment

Required scopes

path Parameters

query Parameters

Creating customer segments in bulk

Required scopes

path Parameters

header Parameters

Request Body schema: application/json

Updating customer segments in bulk

Required scopes

path Parameters

header Parameters

Request Body schema: application/json

Deleting customer segments in bulk

The IDs of customer segments for deletion should be defined in the request body as an array of strings.

Example: ["firstId", "secondId", "thirdId"]

Required scopes

path Parameters

query Parameters

Customers Assignments

Retrieving all customer segment customers

Required scopes

path Parameters

query Parameters

header Parameters

Searching with parameters for customer assignments

Required scopes

path Parameters

query Parameters

header Parameters

Request Body schema: application/json

Retrieving a customer segment customer

Required scopes

path Parameters

query Parameters

Updating a customer segment customer

Required scopes

path Parameters

Request Body schema: application/json

Removing a customer from customer segment

Required scopes

path Parameters

Updating customer segment customers in bulk

Required scopes

path Parameters

Request Body schema: application/json

Example: `["firstId", "secondId", "thirdId"]`

The request body for this endpoint is array of objects with `customerId` and `legalEntityId` fields.

Example: `[{"customerId": "firstCustomerId", "legalEntityId": "firstLegalEntityId"}, {"customerId": "secondCustomerId", "legalEntityId": "secondLegalEntityId"}, {"customerId": "thirdCustomerId", "legalEntityId": "thirdLegalEntityId"}]`

Example: `["firstItemId", "secondItemId", "thirdItemId"]`