Studio integration

Studio API Endpoints

The Customer Management Framework Bundle provides a RESTful API for the Pimcore Studio interface, enabling management of customers, activities, segments, segment groups, automation rules, segment assignments, duplicates, filter definitions, deletions, newsletter queues, helper lookups, term segment builder definitions, API key settings, and GDPR data extraction. All endpoints are prefixed with /pimcore-studio/api/bundle/cmf and require appropriate permissions.

Activities

List Activities

Endpoint: GET /activities Operation ID: bundle_cmf_activities_list Permission: plugin_cmf_perm_activityview

Returns a paginated list of activity store entries, optionally filtered by type and modification timestamp.

Query Parameters:

• page (integer, optional, default 1): Page number (1-based)
• pageSize (integer, optional, default 100): Number of results per page
• type (string, optional): Filter by activity type (e.g. GenericActivity)
• modifiedSinceTimestamp (integer, optional, default 0): Only return activities modified after this Unix timestamp

Response: ActivityCollection object

Field	Type	Description
page	integer	Current page number
totalPages	integer	Total number of pages
timestamp	integer	Unix timestamp of the request
items	ActivityData[]	List of activities on this page

Each ActivityData item contains:

Field	Type	Description
id	integer	Activity store entry ID
customerId	integer	ID of the customer this activity belongs to
type	string	Activity type
implementationClass	string	Fully qualified implementation class name
activityDate	string|null	Activity date as Unix timestamp string
data	object	Additional activity fields (key-value pairs)

Example:

GET /activities?page=1&pageSize=50&type=GenericActivity&modifiedSinceTimestamp=1700000000

---

Get Activity

Endpoint: GET /activities/{id} Operation ID: bundle_cmf_activities_get Permission: plugin_cmf_perm_activityview

Retrieves a single activity entry by its store ID.

Path Parameter:

• id (integer): The activity store entry ID

Response: ActivityData object (see fields above)

Example:

GET /activities/1

---

Create Activity

Endpoint: POST /activities Operation ID: bundle_cmf_activities_create Permission: plugin_cmf_perm_customerview_admin

Creates a new activity entry and assigns it to a customer.

Request Body: CreateActivityParameters (JSON)

Field	Type	Required	Description
customerId	integer	yes	ID of the customer to assign this activity to
implementationClass	string	no	Fully qualified implementation class (default: GenericActivity)
data	object|null	no	Additional activity field values as key-value pairs

Response: ActivityData object (HTTP 201 Created)

Example:

POST /activities
{
    "customerId": 42,
    "implementationClass": "CustomerManagementFrameworkBundle\\Model\\Activity\\GenericActivity",
    "data": { "source": "web", "campaign": "spring-sale" }
}

---

Update Activity

Endpoint: PUT /activities/{id} Operation ID: bundle_cmf_activities_update Permission: plugin_cmf_perm_customerview_admin

Updates an existing activity entry's data fields.

Path Parameter:

• id (integer): The activity store entry ID

Request Body: UpdateActivityParameters (JSON)

Field	Type	Required	Description
data	object|null	no	Activity field values to update as key-value pairs

Response: ActivityData object

Example:

PUT /activities/1
{
    "data": { "campaign": "autumn-sale" }
}

---

Delete Activity

Endpoint: DELETE /activities/{id} Operation ID: bundle_cmf_activities_delete Permission: plugin_cmf_perm_customerview_admin

Deletes an activity entry from the activity store.

Path Parameter:

• id (integer): The activity store entry ID

Response: HTTP 200 OK (empty response)

Example:

DELETE /activities/1

---

Automation Rules

List Automation Rules

Endpoint: GET /automation-rules Operation ID: bundle_cmf_automation_rules_list Permission: plugin_cmf_perm_customer_automation_rules

Returns all action trigger automation rules, ordered by name.

Response: AutomationRuleCollection object

Field	Type	Description
items	AutomationRuleListItem[]	List of automation rules

Each AutomationRuleListItem contains:

Field	Type	Description
id	integer	Rule ID
name	string	Rule name
description	string	Rule description
active	boolean	Whether the rule is active

Example:

GET /automation-rules

---

Get Automation Rule

Endpoint: GET /automation-rules/{id} Operation ID: bundle_cmf_automation_rules_get Permission: plugin_cmf_perm_customer_automation_rules

Returns a single automation rule with its trigger, condition, and action definitions.

Path Parameter:

• id (integer): The automation rule ID

Response: AutomationRuleDetail object

Field	Type	Description
id	integer	Rule ID
name	string	Rule name
description	string	Rule description
active	boolean	Whether the rule is active
trigger	object[]	Trigger definitions
condition	object[]	Condition definitions
actions	object[]	Action definitions

Example:

GET /automation-rules/1

---

Create Automation Rule

Endpoint: POST /automation-rules Operation ID: bundle_cmf_automation_rules_create Permission: plugin_cmf_perm_customer_automation_rules

Creates a new action trigger automation rule with the given name.

Request Body: CreateAutomationRuleParameters (JSON)

Field	Type	Required	Description
name	string	yes	Rule name

Response: AutomationRuleDetail object

Example:

POST /automation-rules
{
    "name": "New Welcome Rule"
}

---

Update Automation Rule

Endpoint: PUT /automation-rules/{id} Operation ID: bundle_cmf_automation_rules_update Permission: plugin_cmf_perm_customer_automation_rules

Updates an existing automation rule with settings, triggers, conditions, and actions.

Path Parameter:

• id (integer): The automation rule ID

Request Body: UpdateAutomationRuleParameters (JSON)

Field	Type	Required	Description
settings	object	yes	Rule settings with name (string), description (string), and active (boolean)
trigger	object[]	yes	Trigger definitions
conditions	object[]	yes	Condition definitions
actions	object[]	yes	Action definitions

Response: AutomationRuleDetail object

Example:

PUT /automation-rules/1
{
    "settings": {
        "name": "Updated Rule",
        "description": "Sends welcome email",
        "active": true
    },
    "trigger": [{ "eventName": "plugin.cmf.customer-save-manager.post-save" }],
    "conditions": [],
    "actions": [{ "actionDelay": 0 }]
}

---

Delete Automation Rule

Endpoint: DELETE /automation-rules/{id} Operation ID: bundle_cmf_automation_rules_delete Permission: plugin_cmf_perm_customer_automation_rules

Deletes an existing automation rule by ID.

Path Parameter:

• id (integer): The automation rule ID

Response: HTTP 200 OK (empty response)

Example:

DELETE /automation-rules/1

---

Customers

List Customers

Endpoint: GET /customers Operation ID: bundle_cmf_customers_list Permission: plugin_cmf_perm_customerview

Returns a paginated list of customers, optionally filtered by modification timestamp and segment membership.

Query Parameters:

• page (integer, optional, default 1): Page number (1-based)
• pageSize (integer, optional, default 25): Number of results per page
• modificationTimestamp (integer, optional, default 0): Only return customers modified after this Unix timestamp
• includeActivities (boolean, optional, default false): Include the customer's activity list in the response
• segments[] (array of integers, optional): Filter by segment IDs (repeatable: segments[]=1&segments[]=2)

Response: CustomerCollection object

Field	Type	Description
page	integer	Current page number
totalPages	integer	Total number of pages
timestamp	integer	Unix timestamp of the request
items	CustomerData[]	List of customers on this page

Each CustomerData item contains:

Field	Type	Description
id	integer	Customer object ID
active	boolean	Whether the customer is active
email	string	Customer email address
segments	integer[]	Segment IDs assigned to this customer
activities	object[]|null	Activity data (only present when includeActivities=true)
data	object	All raw CMF fields returned by cmfToArray()

Example:

GET /customers?page=1&pageSize=25&segments[]=1&segments[]=5&includeActivities=false

---

Get Customer

Endpoint: GET /customers/{id} Operation ID: bundle_cmf_customers_get Permission: plugin_cmf_perm_customerview

Retrieves a single customer by their Pimcore object ID.

Path Parameter:

• id (integer): The customer's Pimcore object ID

Query Parameters:

• includeActivities (boolean, optional, default false): Include the customer's activity list in the response

Response: CustomerData object (see fields above)

Example:

GET /customers/42?includeActivities=true

---

Create Customer

Endpoint: POST /customers Operation ID: bundle_cmf_customers_create Permission: plugin_cmf_perm_customerview_admin

Creates a new customer object.

Request Body: CreateCustomerParameters (JSON)

Field	Type	Required	Description
email	string	yes	Customer email address
active	boolean|null	no	Whether the customer should be active
data	object|null	no	Additional customer field values as key-value pairs

Response: CustomerData object (HTTP 201 Created)

Example:

POST /customers
{
    "email": "jane@example.com",
    "active": true,
    "data": { "firstname": "Jane", "lastname": "Doe" }
}

---

Update Customer

Endpoint: PUT /customers/{id} Operation ID: bundle_cmf_customers_update Permission: plugin_cmf_perm_customerview_admin

Updates an existing customer's fields.

Path Parameter:

• id (integer): The customer's Pimcore object ID

Request Body: UpdateCustomerParameters (JSON)

Field	Type	Required	Description
email	string|null	no	Updated email address
active	boolean|null	no	Updated active status
data	object|null	no	Additional customer field values as key-value pairs

Response: CustomerData object

Example:

PUT /customers/42
{
    "email": "jane.new@example.com",
    "active": false
}

---

Delete Customer

Endpoint: DELETE /customers/{id} Operation ID: bundle_cmf_customers_delete Permission: plugin_cmf_perm_customerview_admin

Deletes a customer object.

Path Parameter:

• id (integer): The customer's Pimcore object ID

Response: HTTP 200 OK (empty response)

Example:

DELETE /customers/42

---

Deletions

List Deletions

Endpoint: GET /deletions Operation ID: bundle_cmf_deletions_list Permission: plugin_cmf_perm_activityview

Returns the list of recorded entity deletions, optionally filtered by type and timestamp.

Query Parameters:

• type (string, optional): Filter by deleted entity type
• deletionsSinceTimestamp (integer, optional, default 0): Only return deletions recorded after this Unix timestamp

Response: DeletionCollection object

Field	Type	Description
timestamp	integer	Unix timestamp of the request
items	DeletionData[]	List of deletion entries

Each DeletionData item contains:

Field	Type	Description
id	integer	Deleted entity ID
type	string	Type of the deleted entity
deletionDate	integer	Unix timestamp when the entity was deleted

Example:

GET /deletions?type=order&deletionsSinceTimestamp=1700000000

---

Duplicates

Decline Potential Duplicate

Endpoint: POST /duplicates/{id}/decline Operation ID: bundle_cmf_duplicates_decline Permission: plugin_cmf_perm_customerview

Marks a potential duplicate entry as declined, preventing it from appearing in future duplicate checks.

Path Parameter:

• id (integer): The potential duplicate entry ID

Response: HTTP 200 OK (empty response)

Example:

POST /duplicates/123/decline

---

Filter Definitions

Create Filter Definition

Endpoint: POST /filter-definitions Operation ID: bundle_cmf_filter_definitions_create Permission: plugin_cmf_perm_customerview

Creates a new customer view filter definition owned by the current user.

Request Body: CreateFilterDefinitionParameters (JSON)

Field	Type	Required	Description
name	string	yes	Filter definition name
definition	object	no	Filter definition configuration (default {})
allowedUserIds	integer[]	no	Allowed user and role IDs (default [])
showSegments	string[]	no	Segment group IDs to show (default [])
readOnly	boolean	no	Whether the filter is read-only (default false)
shortcutAvailable	boolean	no	Whether the filter is available as a shortcut (default false)

Response: FilterDefinitionDetail object

Each FilterDefinitionDetail contains:

Field	Type	Description
id	integer	Filter definition ID
ownerId	integer	Owner user ID
name	string	Filter definition name
definition	object	Filter definition configuration
allowedUserIds	integer[]	Allowed user and role IDs
showSegments	string[]	Segment group IDs to show
readOnly	boolean	Whether the filter is read-only
shortcutAvailable	boolean	Whether the filter is available as a shortcut
creationDate	string|null	Creation date
modificationDate	string|null	Modification date

Example:

POST /filter-definitions
{
    "name": "My Filter",
    "definition": { "column": "email", "operator": "contains", "value": "@example.com" },
    "readOnly": false,
    "shortcutAvailable": true
}

---

Update Filter Definition

Endpoint: PUT /filter-definitions/{id} Operation ID: bundle_cmf_filter_definitions_update Permission: plugin_cmf_perm_customerview

Updates an existing customer view filter definition. Requires update permission on the filter.

Path Parameter:

• id (integer): The filter definition ID

Request Body: UpdateFilterDefinitionParameters (JSON)

Field	Type	Required	Description
name	string	yes	Filter definition name
definition	object	no	Filter definition configuration (default {})
allowedUserIds	integer[]	no	Allowed user and role IDs (default [])
showSegments	string[]	no	Segment group IDs to show (default [])
readOnly	boolean	no	Whether the filter is read-only (default false)
shortcutAvailable	boolean	no	Whether the filter is available as a shortcut (default false)

Response: FilterDefinitionDetail object (see fields above)

Example:

PUT /filter-definitions/1
{
    "name": "Updated Filter",
    "definition": { "column": "lastname", "operator": "equals", "value": "Doe" }
}

---

Share Filter Definition

Endpoint: PUT /filter-definitions/{id}/share Operation ID: bundle_cmf_filter_definitions_share Permission: plugin_cmf_perm_customerview

Adds the specified user IDs to the allowed users list of a filter definition. Requires share permission on the filter.

Path Parameter:

• id (integer): The filter definition ID

Request Body: ShareFilterDefinitionParameters (JSON)

Field	Type	Required	Description
allowedUserIds	integer[]	yes	User and role IDs to share the filter with

Response: FilterDefinitionDetail object (see fields above)

Example:

PUT /filter-definitions/1/share
{
    "allowedUserIds": [3, 4, 5]
}

---

Delete Filter Definition

Endpoint: DELETE /filter-definitions/{id} Operation ID: bundle_cmf_filter_definitions_delete Permission: plugin_cmf_perm_customerview

Deletes an existing customer view filter definition. Requires update permission on the filter.

Path Parameter:

• id (integer): The filter definition ID

Response: HTTP 200 OK (empty response)

Example:

DELETE /filter-definitions/1

---

Helpers

Get Activity Types

Endpoint: GET /helper/activity-types Operation ID: bundle_cmf_helper_activity_types Permission: plugin_cmf_perm_customerview

Returns all available activity types configured in the system.

Response: ActivityTypeCollection object

Field	Type	Description
items	ActivityTypeData[]	List of available activity types

Each ActivityTypeData contains:

Field	Type	Description
type	string	Activity type identifier (e.g. order, GenericActivity)

Example:

GET /helper/activity-types

---

Get Customer Fields

Endpoint: GET /helper/customer-fields Operation ID: bundle_cmf_helper_customer_field_list Permission: plugin_cmf_perm_customerview

Returns all fields defined on the customer data object class.

Response: CustomerFieldCollection object

Field	Type	Description
items	CustomerFieldData[]	List of customer fields

Each CustomerFieldData contains:

Field	Type	Description
name	string	Field name (e.g. firstname)
title	string	Field title (e.g. First Name)

Example:

GET /helper/customer-fields

---

Get Grouped Segments

Endpoint: GET /helper/grouped-segments Operation ID: bundle_cmf_helper_grouped_segments Permission: plugin_cmf_perm_customerview

Returns all segments grouped by their segment group, useful for building segment filter UIs.

Response: GroupedSegmentCollection object

Field	Type	Description
items	GroupedSegmentData[]	List of segments with their group information

Each GroupedSegmentData contains:

Field	Type	Description
id	integer	Segment ID
name	string	Segment name
groupId	integer	Segment group ID
groupName	string	Segment group name

Example:

GET /helper/grouped-segments

---

Get Newsletter Filter Flags

Endpoint: GET /helper/newsletter-filter-flags Operation ID: bundle_cmf_helper_newsletter_filter_flags Permission: plugin_cmf_perm_customerview

Returns the list of possible newsletter opt-in/opt-out filter flags configured on the customer class.

Response: NewsletterFilterFlagCollection object

Field	Type	Description
items	NewsletterFilterFlagData[]	List of newsletter filter flag fields

Each NewsletterFilterFlagData contains:

Field	Type	Description
name	string	Field name (e.g. newsletterActive)
label	string	Field label (e.g. Newsletter Active)

Example:

GET /helper/newsletter-filter-flags

---

Newsletter

Get Newsletter Queue Size

Endpoint: GET /newsletter/queue-size Operation ID: bundle_cmf_newsletter_queue_size Permission: plugin_cmf_perm_customerview_admin

Returns the current number of items in the newsletter queue.

Response: QueueSize object

Field	Type	Description
size	integer	Number of items currently in the newsletter queue

Example:

GET /newsletter/queue-size

---

Enqueue All Customers for Newsletter

Endpoint: POST /newsletter/enqueue-all Operation ID: bundle_cmf_newsletter_enqueue_all Permission: plugin_cmf_perm_newsletter_enqueue_all_customers

Enqueues all eligible customers for newsletter processing. This triggers a bulk enqueue operation and returns the resulting queue size.

Response: QueueSize object (HTTP 201 Created)

Example:

POST /newsletter/enqueue-all

---

Segments

List Segments

Endpoint: GET /segments Operation ID: bundle_cmf_segments_list Permission: plugin_cmf_perm_customerview

Returns a paginated list of all segments.

Query Parameters:

• page (integer, optional, default 1): Page number (1-based)
• pageSize (integer, optional, default 100): Number of results per page

Response: SegmentCollection object

Field	Type	Description
page	integer	Current page number
totalPages	integer	Total number of pages
timestamp	integer	Unix timestamp of the request
items	SegmentData[]	List of segments on this page

Each SegmentData item contains:

Field	Type	Description
id	integer	Segment object ID
name	string	Segment name
calculated	boolean	Whether the segment is calculated (automatic)
reference	string|null	Segment reference string
group	integer|null	ID of the segment group this segment belongs to

Example:

GET /segments?page=1&pageSize=50

---

Get Segment

Endpoint: GET /segments/{id} Operation ID: bundle_cmf_segments_get Permission: plugin_cmf_perm_customerview

Retrieves a single segment by its Pimcore object ID.

Path Parameter:

• id (integer): The segment's Pimcore object ID

Response: SegmentData object (see fields above)

Example:

GET /segments/10

---

Create Segment

Endpoint: POST /segments Operation ID: bundle_cmf_segments_create Permission: plugin_cmf_perm_customerview_admin

Creates a new segment within a segment group.

Request Body: CreateSegmentParameters (JSON)

Field	Type	Required	Description
name	string	yes	Segment name
group	integer	yes	ID of the segment group to create the segment in
reference	string|null	no	Segment reference string
calculated	boolean|null	no	Whether the segment is calculated (automatic)
subFolder	string|null	no	Optional subfolder within the segment group

Response: SegmentData object (HTTP 201 Created)

Example:

POST /segments
{
    "name": "Gold Members",
    "group": 5,
    "reference": "gold-members",
    "calculated": false
}

---

Update Segment

Endpoint: PUT /segments/{id} Operation ID: bundle_cmf_segments_update Permission: plugin_cmf_perm_customerview_admin

Updates an existing segment.

Path Parameter:

• id (integer): The segment's Pimcore object ID

Request Body: UpdateSegmentParameters (JSON)

Field	Type	Required	Description
name	string|null	no	New segment name
reference	string|null	no	New segment reference string
calculated	boolean|null	no	Whether the segment is calculated (automatic)

Response: SegmentData object

Example:

PUT /segments/10
{
    "name": "Platinum Members",
    "reference": "platinum-members"
}

---

Delete Segment

Endpoint: DELETE /segments/{id} Operation ID: bundle_cmf_segments_delete Permission: plugin_cmf_perm_customerview_admin

Deletes a segment object.

Path Parameter:

• id (integer): The segment's Pimcore object ID

Response: HTTP 204 No Content

Example:

DELETE /segments/10

---

Segment Assignments

Assign Segments to Element

Endpoint: POST /segment-assignments/assign Operation ID: bundle_cmf_segment_assignments_assign Permission: plugin_cmf_perm_customerview

Assigns the given segments to an element (object, document, or asset), optionally breaking segment inheritance.

Request Body: AssignSegmentsParameters (JSON)

Field	Type	Required	Description
id	string	yes	Element ID
type	string	yes	Element type (object, document, or asset)
breaksInheritance	boolean	yes	Whether this element breaks segment inheritance
segmentIds	string[]	yes	Array of segment IDs to assign

Response: boolean (true on success, false on failure)

Example:

POST /segment-assignments/assign
{
    "id": "42",
    "type": "object",
    "breaksInheritance": false,
    "segmentIds": ["1", "2", "3"]
}

---

Get Assigned Segments

Endpoint: GET /segment-assignments/assigned Operation ID: bundle_cmf_segment_assignments_assigned Permission: plugin_cmf_perm_customerview

Returns all segments directly assigned to the given element.

Query Parameters:

• id (integer, required): Element ID
• type (string, required): Element type (object, document, or asset)

Response: SegmentAssignmentCollection object

Field	Type	Description
data	SegmentAssignmentItem[]	List of directly assigned segments

Each SegmentAssignmentItem contains:

Field	Type	Description
id	integer	Segment ID
type	string	Segment type (e.g. manual)
name	string	Segment name

Example:

GET /segment-assignments/assigned?id=42&type=object

---

Get Inheritable Segments

Endpoint: GET /segment-assignments/inheritable Operation ID: bundle_cmf_segment_assignments_inheritable Permission: plugin_cmf_perm_customerview

Returns all segments inherited from the parent of the given element, computed via the segment assignment tree.

Query Parameters:

• id (integer, required): Element ID
• type (string, required): Element type (object, document, or asset)

Response: SegmentAssignmentCollection object (see fields above)

Example:

GET /segment-assignments/inheritable?id=42&type=object

---

Check Breaks Inheritance

Endpoint: GET /segment-assignments/breaks-inheritance Operation ID: bundle_cmf_segment_assignments_breaks_inheritance Permission: plugin_cmf_perm_customerview

Returns whether the given element breaks segment inheritance from its parent elements.

Query Parameters:

• id (integer, required): Element ID
• type (string, required): Element type (object, document, or asset)

Response: BreaksInheritanceResponse object

Field	Type	Description
breaksInheritance	boolean|null	Whether the element breaks segment inheritance (null if no assignment exists)

Example:

GET /segment-assignments/breaks-inheritance?id=42&type=object

---

Segments of Customer

Update Segments of Customer

Endpoint: PUT /customers/{id}/segments Operation ID: bundle_cmf_segments_of_customer_update Permission: plugin_cmf_perm_customerview_admin

Adds and/or removes segments from a specific customer in a single atomic operation.

Path Parameter:

• id (integer): The customer's Pimcore object ID

Request Body: UpdateSegmentsOfCustomerParameters (JSON)

Field	Type	Required	Description
addSegmentIds	integer[]	no	Segment IDs to add to the customer (default [])
removeSegmentIds	integer[]	no	Segment IDs to remove from the customer (default [])

Response: SegmentsOfCustomerUpdated object

Field	Type	Description
customerId	integer	Customer object ID
addedSegmentIds	integer[]	Segment IDs that were added
removedSegmentIds	integer[]	Segment IDs that were removed

Example:

PUT /customers/42/segments
{
    "addSegmentIds": [1, 3],
    "removeSegmentIds": [2]
}

---

Segment Groups

List Segment Groups

Endpoint: GET /segment-groups Operation ID: bundle_cmf_segment_groups_list Permission: plugin_cmf_perm_customerview

Returns a paginated list of all segment groups.

Query Parameters:

• page (integer, optional, default 1): Page number (1-based)
• pageSize (integer, optional, default 100): Number of results per page

Response: SegmentGroupCollection object

Field	Type	Description
page	integer	Current page number
totalPages	integer	Total number of pages
timestamp	integer	Unix timestamp of the request
items	SegmentGroupData[]	List of segment groups on this page

Each SegmentGroupData item contains:

Field	Type	Description
id	integer	Segment group object ID
name	string	Segment group name
calculated	boolean	Whether the segment group is calculated (automatic)
reference	string|null	Segment group reference string

Example:

GET /segment-groups?page=1&pageSize=50

---

Get Segment Group

Endpoint: GET /segment-groups/{id} Operation ID: bundle_cmf_segment_groups_get Permission: plugin_cmf_perm_customerview

Retrieves a single segment group by its Pimcore object ID.

Path Parameter:

• id (integer): The segment group's Pimcore object ID

Response: SegmentGroupData object (see fields above)

Example:

GET /segment-groups/5

---

Create Segment Group

Endpoint: POST /segment-groups Operation ID: bundle_cmf_segment_groups_create Permission: plugin_cmf_perm_customerview_admin

Creates a new segment group.

Request Body: CreateSegmentGroupParameters (JSON)

Field	Type	Required	Description
name	string	yes	Segment group name
reference	string|null	no	Segment group reference string
calculated	boolean|null	no	Whether the segment group is calculated (automatic)

Response: SegmentGroupData object (HTTP 201 Created)

Example:

POST /segment-groups
{
    "name": "Customer Type",
    "reference": "customer-type",
    "calculated": false
}

---

Update Segment Group

Endpoint: PUT /segment-groups/{id} Operation ID: bundle_cmf_segment_groups_update Permission: plugin_cmf_perm_customerview_admin

Updates an existing segment group.

Path Parameter:

• id (integer): The segment group's Pimcore object ID

Request Body: UpdateSegmentGroupParameters (JSON)

Field	Type	Required	Description
name	string|null	no	New segment group name
reference	string|null	no	New segment group reference string

Response: SegmentGroupData object

Example:

PUT /segment-groups/5
{
    "name": "Loyalty Tier",
    "reference": "loyalty-tier"
}

---

Delete Segment Group

Endpoint: DELETE /segment-groups/{id} Operation ID: bundle_cmf_segment_groups_delete Permission: plugin_cmf_perm_customerview_admin

Deletes a segment group object.

Path Parameter:

• id (integer): The segment group's Pimcore object ID

Response: HTTP 204 No Content

Example:

DELETE /segment-groups/5

---

Settings

Get API Keys

Endpoint: GET /settings/api-keys Operation ID: bundle_cmf_settings_api_keys_get Permission: plugin_cmf_perm_customerview_admin

Returns all active Pimcore users together with their CMF webservice API keys.

Response: ApiKeyUserCollection object

Field	Type	Description
items	ApiKeyUser[]	List of users with their API keys

Each ApiKeyUser item contains:

Field	Type	Description
id	integer	Pimcore user ID
name	string	Username
firstname	string|null	First name
lastname	string|null	Last name
email	string|null	Email address
apiKey	string	CMF webservice API key (empty string if none assigned)

Example:

GET /settings/api-keys

---

Update API Key

Endpoint: PUT /settings/api-keys Operation ID: bundle_cmf_settings_api_keys_update Permission: plugin_cmf_perm_customerview_admin

Assigns or revokes the CMF webservice API key for a specific Pimcore user.

Request Body: UpdateApiKeyParameters (JSON)

Field	Type	Required	Description
userId	integer	yes	Pimcore user ID to assign the API key to
apiKey	string	yes	New API key value (pass empty string "" to revoke)

Response: ApiKeyUserCollection object (the updated full list)

Example:

PUT /settings/api-keys
{
    "userId": 1,
    "apiKey": "newSecret123"
}

---

Term Segment Builder Definitions

List Term Segment Builder Definitions

Endpoint: GET /term-segment-builder-definitions Operation ID: bundle_cmf_term_segment_builder_definitions_list Permission: plugin_cmf_perm_customerview

Returns all published term segment builder definitions.

Response: TermSegmentBuilderDefinitionCollection object

Field	Type	Description
items	TermSegmentBuilderDefinitionData[]	List of term segment builder definitions

Each TermSegmentBuilderDefinitionData contains:

Field	Type	Description
id	integer	Term segment builder definition object ID
name	string|null	Term segment builder definition name

Example:

GET /term-segment-builder-definitions

---

View Endpoints (HTML)

The following endpoints return server-rendered HTML pages (Twig templates) for embedding in the Pimcore Studio interface via iframes. They re-use the existing admin templates but inject a studioContext flag so that all navigation links (detail, back, sort, pagination) point to Studio routes instead of legacy admin routes.

All View endpoints return text/html responses.

Customer List View

Endpoint: GET /customers/view/list Operation ID: bundle_cmf_customers_view_list Permission: plugin_cmf_perm_customerview

Renders the customer list page with search, segment filters, pagination, sorting, and export controls.

Query Parameters:

• page (integer, optional, default 1): Page number (1-based)
• perPage (integer, optional, default 25): Number of results per page
• segmentId (integer, optional): Pre-filter by a specific segment ID
• filterDefinitionId (integer, optional): Load a saved filter definition by ID
• filter[search] (string, optional): Full-text search query
• filter[segments] (array, optional): Segment filter selections
• order[field] (string, optional): Sort by field name (e.g. order[id]=ASC)

Response: HTML page (text/html)

Example:

GET /customers/view/list?perPage=25&page=1
GET /customers/view/list?perPage=10&filter[search]=john&order[lastname]=ASC
GET /customers/view/list?segmentId=5

---

Customer Detail View

Endpoint: GET /customers/{id}/view/detail Operation ID: bundle_cmf_customers_view_detail Permission: plugin_cmf_perm_customerview

Renders the customer detail page showing all customer fields. Includes a back link to the customer list view.

Path Parameter:

• id (integer): The customer's Pimcore object ID

Response: HTML page (text/html)

Example:

GET /customers/1015/view/detail

---

Activity List View

Endpoint: GET /activities/view/list Operation ID: bundle_cmf_activities_view_list Permission: plugin_cmf_perm_activityview

Renders the activity list page for a specific customer, with pagination and type filtering. Each activity row links to the activity detail view.

Query Parameters:

• customerId (integer, required): The customer ID to show activities for
• type (string, optional): Filter by activity type
• page (integer, optional, default 1): Page number (1-based)

Response: HTML page (text/html)

Example:

GET /activities/view/list?customerId=1015
GET /activities/view/list?customerId=1015&type=login&page=2

---

Activity Detail View

Endpoint: GET /activities/{id}/view/detail Operation ID: bundle_cmf_activities_view_detail Permission: plugin_cmf_perm_activityview

Renders the activity detail page showing all activity data. Includes a back link to the activity list filtered by the originating customer.

Path Parameter:

• id (integer): The activity store entry ID

Query Parameters:

• customerId (integer, required): Customer ID for the back link to the activity list

Response: HTML page (text/html)

Example:

GET /activities/123/view/detail?customerId=1015

---

Duplicates List View

Endpoint: GET /duplicates/view/list Operation ID: bundle_cmf_duplicates_view_list Permission: plugin_cmf_perm_customerview

Renders the customer duplicates list page with search, pagination, and the ability to decline duplicate pairs. Supports toggling between active and declined duplicates. The decline action uses the Studio API endpoint POST /duplicates/{id}/decline via JavaScript when rendered in Studio context.

Query Parameters:

• page (integer, optional, default 1): Page number (1-based)
• perPage (integer, optional, default 50): Number of results per page
• declined (integer, optional, default 0): Show declined duplicates (1) or active duplicates (0)
• filter[search] (string, optional): Search query to filter duplicates

Response: HTML page (text/html)

Example:

GET /duplicates/view/list
GET /duplicates/view/list?declined=1&perPage=25
GET /duplicates/view/list?filter[search]=john

---

GDPR Data Provider

The CMF bundle registers a GDPR data provider (customers) with the StudioBackendBundle's GDPR framework. This integrates with the Studio's existing GDPR data extraction endpoints; no CMF-specific GDPR controllers are needed.

The CustomerDataProvider provides:

• Customer search by ID and email
• Customer data export including all customer fields
• Activity data for each customer

The provider is available at the Studio GDPR endpoints under the provider key customers.

---

Permissions

The Studio API uses the following permission constants (defined in PermissionConstants):

Constant	Value	Description
ACTIVITY_VIEW	plugin_cmf_perm_activityview	Read-only access to activities and deletions listing
CUSTOMER_VIEW	plugin_cmf_perm_customerview	Read-only access to customers, segments, segment groups, segment assignments, helpers, filter definitions, duplicates, and term segment builder definitions
CUSTOMER_VIEW_ADMIN	plugin_cmf_perm_customerview_admin	Write access: create, update, and delete customers, activities, segments, segment groups, segments-of-customer, newsletter queue, and settings
AUTOMATION_RULES	plugin_cmf_perm_customer_automation_rules	Full access to automation rules (list, get, create, update, delete)
NEWSLETTER_ENQUEUE	plugin_cmf_perm_newsletter_enqueue_all_customers	Permission to trigger bulk newsletter enqueue for all customers
GDPR_DATA_EXTRACTOR	gdpr_data_extractor	Access to GDPR data extraction endpoints

Common Response Codes

• 200 OK: Successful request (GET, PUT, DELETE, POST for some endpoints)
• 201 Created: Resource created successfully (POST endpoints for customers, segments, segment groups, activities, newsletter enqueue)
• 204 No Content: Resource deleted successfully (DELETE endpoints for segments, segment groups)
• 401 Unauthorized: Missing or invalid authentication
• 403 Forbidden: User lacks the required permission
• 404 Not Found: Resource not found (customer, segment, segment group, activity, automation rule, or filter definition does not exist)
• 409 Conflict: Duplicate resource (e.g. segment with the same reference already exists in the group)
• 422 Unprocessable Entity: Invalid input data (e.g. activity implementation class does not allow webservice updates)

Usage Examples

Managing Customers

1. List customers modified since a certain date:

   GET /customers?modificationTimestamp=1700000000&pageSize=50

2. Create a new customer:

   POST /customers
   { "email": "new@example.com", "active": true }

3. Get a customer with their activities:

   GET /customers/42?includeActivities=true

4. Update a customer's active status:

   PUT /customers/42
   { "active": false }

5. Delete a customer:

   DELETE /customers/42

Managing Segments

1. List all segments:

   GET /segments?page=1&pageSize=100

2. Create a segment inside a group:

   POST /segments
   { "name": "VIP", "group": 5, "reference": "vip" }

3. Add and remove segments from a customer atomically:

   PUT /customers/42/segments
   { "addSegmentIds": [10, 11], "removeSegmentIds": [9] }

Working with Activities

1. List recent activities for a specific type:

   GET /activities?type=GenericActivity&modifiedSinceTimestamp=1700000000

2. Create an activity for a customer:

   POST /activities
   { "customerId": 42, "data": { "source": "checkout" } }

3. List deletion records since a timestamp:

   GET /deletions?deletionsSinceTimestamp=1700000000

Automation Rules

1. List all automation rules:

   GET /automation-rules

2. Create a new automation rule:

   POST /automation-rules
   { "name": "Welcome Email Rule" }

3. Update a rule with triggers and actions:

   PUT /automation-rules/1
   {
       "settings": { "name": "Welcome Email", "description": "Sends email on save", "active": true },
       "trigger": [{ "eventName": "plugin.cmf.customer-save-manager.post-save" }],
       "conditions": [],
       "actions": [{ "actionDelay": 0 }]
   }

4. Delete an automation rule:

   DELETE /automation-rules/1

Segment Assignments

1. Assign segments to an object:

   POST /segment-assignments/assign
   { "id": "42", "type": "object", "breaksInheritance": false, "segmentIds": ["1", "2"] }

2. Get directly assigned segments:

   GET /segment-assignments/assigned?id=42&type=object

3. Check if element breaks inheritance:

   GET /segment-assignments/breaks-inheritance?id=42&type=object

4. Get inheritable segments from parent:

   GET /segment-assignments/inheritable?id=42&type=object

Filter Definitions

1. Create a filter definition:

   POST /filter-definitions
   { "name": "Active Customers", "readOnly": false }

2. Share a filter with other users:

   PUT /filter-definitions/1/share
   { "allowedUserIds": [3, 4, 5] }

3. Delete a filter definition:

   DELETE /filter-definitions/1

Duplicates

1. Decline a potential duplicate:

   POST /duplicates/123/decline

Newsletter Queue

1. Check the current queue size:

   GET /newsletter/queue-size

2. Enqueue all customers:

   POST /newsletter/enqueue-all

Helper Lookups

1. Get available activity types:

   GET /helper/activity-types

2. Get customer fields for filter building:

   GET /helper/customer-fields

3. Get segments grouped by segment group:

   GET /helper/grouped-segments

4. Get newsletter filter flag fields:

   GET /helper/newsletter-filter-flags

Managing API Keys

1. View all users and their API keys:

   GET /settings/api-keys

2. Assign an API key to a user:

   PUT /settings/api-keys
   { "userId": 1, "apiKey": "mySecretKey123" }

3. Revoke an API key:

   PUT /settings/api-keys
   { "userId": 1, "apiKey": "" }

Term Segment Builder Definitions

1. List all published definitions:

   GET /term-segment-builder-definitions