--- schema_version: "1" id: 1a7b8522086d2e7a01ae2a7aa132d8037277bda8643bfb7d661f8fbe168e2719 title: Content - Expression (Connect API) collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/marketing-cloud/mc-core/references/generated-api-specs/mc-next-expression.md canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-next-expression source_site: developer.salesforce.com content_type: documentation content_hash: db66430e7661e48eabd15dda85d6f7b57482d157b0d02fafdb656794139d1f6e products: - Marketing Cloud Next - Marketing Cloud --- Content - Expression (Connect API) # Content - Expression (Connect API) Create and manage expressions in Marketing Cloud Next. Expressions define conditional logic for content personalization and dynamic behavior. This table lists the expression-related use cases that the API supports. | Supported Use Case | HTTP Verb | URI | | --- | --- | --- | | Create expression content | [POST](/docs/marketing/marketing-cloud-growth/references/mc-next-expression?meta=createExpression) | /services/data/{apiVersion}/connect/cms/contents | | Get expression content | [GET](/docs/marketing/marketing-cloud-growth/references/mc-next-expression?meta=getExpression) | /services/data/{apiVersion}/connect/cms/contents/{contentId} | | Update an expression content variant | [PUT](/docs/marketing/marketing-cloud-growth/references/mc-next-expression?meta=updateContentVariant) | /services/data/{apiVersion}/connect/cms/contents/variants/{variantId} | | Delete an expression content variant | [DELETE](/docs/marketing/marketing-cloud-growth/references/mc-next-expression?meta=deleteContentVariant) | /services/data/{apiVersion}/connect/cms/contents/variants/{variantId} | Expressions define conditional logic for content personalization and dynamic behavior. They use a multi-level expression model with groups, rules, criteria, and sort configuration. ### API Structure Expression content uses the request structure shown in this example: ```json { "contentSpaceOrFolderId": "0Zuxx00000003M5CAI", "contentType": "sfdc_cms__expression", "contentBody": { "expression": { "definition": "sfdc_cms__multiLevelExpression", "label": "My Expression", "sfdcExpressionKey": "myExpression", "expressionGroups": [...] } } } ``` ### Expression Groups Each expression group references a data resource and optionally applies filtering rules and sorting. Groups can reference other groups using merge-field syntax (for example, `{!group0.Name__c}`). Group names must be unique within an expression (enforced by schema). ### Expression Rules Rules define filter criteria using one of three evaluation modes: * **AllCriteriaMatch** — All criteria must be true (AND logic). * **AnyCriterionMatches** — Any criterion can be true (OR logic). * **CustomLogicMatches** — Custom formula like `1 AND 2 AND (3 OR 4)`. ### Data Providers Expressions are used within the `sfdc_unifiedmarketing__common` and `sfdc_cms__email` modules. ### Content Properties The `Content` object has the properties shown in this table. | Property | Type | Description | | --- | --- | --- | | `sfdc_cms:title` | string | Required. The name of the expression. | | `expression` | object | Required. An object that defines the expression. | | `sfdc_cms:description` | string | A description of the expression. | | `lightning:dataProviders` | list | Data provider configurations for expression evaluation. | The `expression` object has these properties. | Property | Type | Description | | --- | --- | --- | | `definition` | string | An identifier for the expression definition, such as `sfdc_cms__multiLevelExpression`. | | `label` | string | A display label for the expression. | | `sfdcExpressionKey` | string | A unique key used to refer to this expression in merge fields. | | `default` | string | A default value when the expression resolves to no results. | | `selectionIndex` | number or string | The index of the value to select from the result set. | | `customFormula` | string | A custom logic formula, such as `1 AND 2 AND (3 OR 4)`. | | `expressionGroups` | list | Required. An array of expression groups with resource, rule, and sort configurations. | ### Handlebars Expression Support Expression values support Handlebars-based personalization. See [Handlebars for Marketing Cloud Next](/docs/marketing/handlebars-for-marketing-cloud-next/references/mcn-handlebars-references/mcn-handlebars-about.html). **Version:** 1.0.0 ## Servers * `https://{subdomain}.my.salesforce.com` * `subdomain (default (no default)) The unique API subdomain for your Salesforce org.` ## Tags ### Expression Operations for managing expression content. Expressions are used within the sfdc\_unifiedmarketing\_\_common and sfdc\_cms\_\_email modules. ## Operations ### POST Create expression content `POST /services/data/{apiVersion}/connect/cms/contents` Operation ID: `createExpression`. Tags: Expression. Creates an expression content item. #### Request body (required) Media type: `application/json`. Schema: `ExpressionRequest`. _Example: simpleExpression_ Simple expression with one group referencing a data graph resource. ``` { "contentSpaceOrFolderId": "0Zuxx00000003M5CAI", "contentType": "sfdc_cms__expression", "contentBody": { "expression": { "definition": "sfdc_cms__multiLevelExpression", "label": "Sales Order Filter", "sfdcExpressionKey": "salesOrderFilter", "default": "", "expressionGroups": [ { "name": "group0", "resource": "{!$dataGraph.Sales_Order_Product__dlm}", "expressionRule": { "name": "rule0", "description": "", "criteriaType": "AllCriteriaMatch", "expressionCriteria": [ { "resource": "Name__c", "operator": "CONTAINS", "value": "premium", "criterionNumber": 1 }, { "resource": "DataSourceObject__c", "operator": "IS_NOT_NULL", "value": "", "criterionNumber": 2 } ] }, "expressionSort": { "orderBy": "Name__c", "sortOrder": "ASC" } } ] } } } ``` _Example: multiGroupExpression_ Multi-group expression with chained references. ``` { "contentSpaceOrFolderId": "0Zuxx00000003M5CAI", "contentType": "sfdc_cms__expression", "contentBody": { "expression": { "definition": "sfdc_cms__multiLevelExpression", "label": "Customer Segmentation", "sfdcExpressionKey": "customerSegment", "default": "", "expressionGroups": [ { "name": "group0", "resource": "{!$dataGraph.Sales_Order_Product__dlm}", "expressionRule": { "name": "rule0", "criteriaType": "AllCriteriaMatch", "expressionCriteria": [ { "resource": "Name__c", "operator": "CONTAINS", "value": "aaaa", "criterionNumber": 1 }, { "resource": "DataSourceObject__c", "operator": "IS_NOT_NULL", "value": "", "criterionNumber": 2 } ] }, "expressionSort": { "orderBy": "Name__c", "sortOrder": "ASC" } }, { "name": "group1", "resource": "{!group0.Name__c}" } ] } } } ``` _Example: withSelectionIndex_ Expression group with selectionIndex. ``` { "contentSpaceOrFolderId": "0Zuxx00000003M5CAI", "contentType": "sfdc_cms__expression", "contentBody": { "expression": { "definition": "sfdc_cms__multiLevelExpression", "label": "First Match", "sfdcExpressionKey": "firstMatch", "default": "N/A", "expressionGroups": [ { "name": "group0", "resource": "{!$dataGraph.Product__dlm}", "selectionIndex": 0, "expressionRule": { "name": "rule0", "criteriaType": "AnyCriterionMatches", "expressionCriteria": [ { "resource": "Status__c", "operator": "EQUALS", "value": "Active", "criterionNumber": 1 } ] } } ] } } } ``` _Example: customLogicExpression_ Expression with custom formula logic. ``` { "contentSpaceOrFolderId": "0Zuxx00000003M5CAI", "contentType": "sfdc_cms__expression", "contentBody": { "expression": { "definition": "sfdc_cms__multiLevelExpression", "label": "Complex Filter", "sfdcExpressionKey": "complexFilter", "default": "", "expressionGroups": [ { "name": "group0", "resource": "{!$dataGraph.Contact__dlm}", "expressionRule": { "name": "rule0", "criteriaType": "CustomLogicMatches", "customFormula": "1 AND 2 AND (3 OR 4)", "expressionCriteria": [ { "resource": "Region__c", "operator": "EQUALS", "value": "AMER", "criterionNumber": 1 }, { "resource": "Tier__c", "operator": "EQUALS", "value": "Gold", "criterionNumber": 2 }, { "resource": "Revenue__c", "operator": "GREATER_THAN", "value": 100000, "criterionNumber": 3 }, { "resource": "Employees__c", "operator": "GREATER_THAN", "value": 500, "criterionNumber": 4 } ] } } ] } } } ``` #### Responses * **201** Expression created successfully. Media type: `application/json`. Schema: `ExpressionResponse`. _Example: complete_ Complete response. ``` { "apiName": "MCJUR5WKNRHZFP7NAUQOMMNJ7CI4", "contentBody": { "expression": { "definition": "sfdc_cms__multiLevelExpression", "label": "Sales Order Filter", "sfdcExpressionKey": "salesOrderFilter", "default": "", "expressionGroups": [ { "name": "group0", "resource": "{!$dataGraph.Sales_Order_Product__dlm}", "expressionRule": { "name": "rule0", "description": "", "criteriaType": "AllCriteriaMatch", "expressionCriteria": [ { "resource": "Name__c", "operator": "CONTAINS", "value": "premium", "criterionNumber": 1 }, { "resource": "DataSourceObject__c", "operator": "IS_NOT_NULL", "value": "", "criterionNumber": 2 } ] }, "expressionSort": { "orderBy": "Name__c", "sortOrder": "ASC" } } ] } }, "contentFqn": "marketing--Default_Content_Workspace.sfdc_cms__expression--MCJUR5WKNRHZFP7NAUQOMMNJ7CI4", "contentKey": "MCJUR5WKNRHZFP7NAUQOMMNJ7CI4", "contentSpace": { "id": "0ZuSB000002FYzW0AW", "resourceUrl": "/services/data/v65.0/connect/cms/spaces/0ZuSB000002FYzW" }, "contentType": { "fullyQualifiedName": "sfdc_cms__expression" }, "createdBy": { "id": "005SB00000eaki1YAA", "name": "Admin User", "resourceUrl": "/services/data/v65.0/chatter/users/005SB00000eaki1YAA" }, "createdDate": "2026-06-16T20:34:56.000Z", "externalId": null, "folder": { "id": "9PuSB000002KUDo0AO", "resourceUrl": "/services/data/v65.0/connect/cms/folders/9PuSB000002KUDo0AO" }, "isPublished": false, "language": "en_US", "lastModifiedBy": { "id": "005SB00000eaki1YAA", "name": "Admin User", "resourceUrl": "/services/data/v65.0/chatter/users/005SB00000eaki1YAA" }, "lastModifiedDate": "2026-06-16T20:34:56.000Z", "managedContentId": "20YSB000004SkOz2AK", "managedContentVariantId": "9PsSB0000045XAj0AM", "managedContentVersionId": "5OUSB000004K7np4AC", "status": { "label": "Draft", "status": "Draft" }, "title": "Content Item", "urlName": "content-item", "versionNumber": "1.1" } ``` * **400** Invalid request body. Media type: `application/json`. Schema: `Error`. _Example: missingExpression_ Missing required expression field. ``` { "error": "VALIDATION_ERROR", "message": "Required field 'expression' is missing", "details": [ { "field": "contentBody.expression", "message": "This field is required" } ] } ``` _Example: missingExpressionGroups_ Missing required expressionGroups. ``` { "error": "VALIDATION_ERROR", "message": "Required field 'expressionGroups' is missing", "details": [ { "field": "contentBody.expression.expressionGroups", "message": "This field is required" } ] } ``` _Example: missingResource_ Missing required resource on expression group. ``` { "error": "VALIDATION_ERROR", "message": "Required field 'resource' is missing", "details": [ { "field": "contentBody.expression.expressionGroups[0].resource", "message": "This field is required" } ] } ``` _Example: duplicateGroupName_ Duplicate group names. ``` { "error": "VALIDATION_ERROR", "message": "Expression group names must be unique", "details": [ { "field": "contentBody.expression.expressionGroups", "message": "Duplicate group name 'group0'" } ] } ``` * **401** Unauthorized. Media type: `application/json`. Schema: `Error`. _Example: response_ Example response. ``` { "error": "UNAUTHORIZED", "message": "Authentication credentials are missing or invalid" } ``` * **403** Forbidden. Media type: `application/json`. Schema: `Error`. _Example: response_ Example response. ``` { "error": "FORBIDDEN", "message": "Insufficient permissions to create expression content" } ``` * **500** Internal server error. Media type: `application/json`. Schema: `Error`. _Example: response_ Example response. ``` { "error": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred while processing the request" } ``` * **503** Service unavailable. Media type: `application/json`. Schema: `Error`. _Example: response_ Example response. ``` { "error": "SERVICE_UNAVAILABLE", "message": "The service is temporarily unavailable. Please try again later" } ``` ### GET Get expression by ID `GET /services/data/{apiVersion}/connect/cms/contents/{contentId}` Operation ID: `getExpression`. Tags: Expression. Retrieves an expression content item. #### Parameters * `contentId` (path, string, required) Example: `20Y6g000000001GEAQ`. #### Responses * **200** Expression details. Media type: `application/json`. Schema: `ExpressionResponse`. _Example complete: same as POST /services/data/{apiVersion}/connect/cms/contents 201 response._ Complete response. _Example: complete_ Complete response. * **404** Expression not found. Media type: `application/json`. Schema: `Error`. _Example: response_ Example response. ``` { "error": "NOT_FOUND", "message": "Expression with ID '20Y6g000000001GEAQ' not found" } ``` ### PUT Update expression variant `PUT /services/data/{apiVersion}/connect/cms/contents/variants/{variantId}` Operation ID: `updateContentVariant`. Tags: Content Lifecycle. Updates an expression content item by creating a variant. Content updates operate on the content variant (the `managedContentVariantId` value from the create response), not on the content item ID. #### Parameters * `variantId` (path, string, required) The `managedContentVariantId` returned in the original creation request. Example: `9PsSB000004Cw170AC`. #### Request body (required) Media type: `application/json`. Schema: `object`. * `contentBody` (_object_, required) The full content body of the variant. Must contain either an `sfdc_cms:block` or a `rawHtml` block but can't contain both. _Example: complete_ Complete request. ``` { "contentBody": { "sfdc_cms:title": "Updated Content Item" } } ``` #### Responses * **200** Variant updated successfully. Media type: `application/json`. Schema: `object`. _Example: complete_ Complete response. ``` {} ``` * **400** Invalid request body. * **404** Variant not found. ### DELETE Delete expression variant `DELETE /services/data/{apiVersion}/connect/cms/contents/variants/{variantId}` Operation ID: `deleteContentVariant`. Tags: Content Lifecycle. Deletes an expression content item by deleting its variant. Content deletions operate on the content variant (the `managedContentVariantId` value returned when the expression was created), not on the content item ID. #### Parameters * `variantId` (path, string, required) The `managedContentVariantId` value that was returned when the expression was created. Example: `9PsSB000004Cw170AC`. #### Responses * **204** Variant deleted successfully (no content). * **404** Variant not found. ## Schemas ### ExpressionRequest * `contentSpaceOrFolderId` (_string_, required) The ID of the content space or folder. * `contentType` (_string_, required) Allowed values: `sfdc_cms__expression`. * `contentBody` (_ExpressionBody_, required) ### ExpressionResponse Response structure returned when creating or retrieving expression content. This envelope is standard across all CMS content types. * `apiName` (_string_) System-generated API name for the content item. * `contentBody` (_ExpressionBody_) * `contentFqn` (_string_, nullable) Fully qualified name including workspace and content type. * `contentKey` (_string_) 28-character alphanumeric content key used for cross-references. * `contentSpace` (_object_) * `id` (_string_) * `resourceUrl` (_string_) * `contentType` (_object_) * `fullyQualifiedName` (_string_) * `createdBy` (_object_) * `id` (_string_) * `name` (_string_) * `resourceUrl` (_string_) * `createdDate` (_string (date-time)_) * `externalId` (_string_, nullable) External identifier if set. * `folder` (_object_) * `id` (_string_) * `resourceUrl` (_string_) * `isPublished` (_boolean_) * `language` (_string_) * `lastModifiedBy` (_object_) * `id` (_string_) * `name` (_string_) * `resourceUrl` (_string_) * `lastModifiedDate` (_string (date-time)_) * `managedContentId` (_string_) The Salesforce record ID for the managed content item. * `managedContentVariantId` (_string_) The variant ID for this content version. * `managedContentVersionId` (_string_) The version ID for this specific content version. * `status` (_object_) * `label` (_string_) * `status` (_string_) Allowed values: `Draft`, `Published`. * `title` (_string_) The display title of the content. * `urlName` (_string_) URL-friendly slug auto-generated from title. * `versionNumber` (_string_) Content version number. ### Error * `error` (_string_, required) * `message` (_string_, required) * `details` (_array of object_) * `field` (_string_) * `message` (_string_) ### ExpressionBody The content body for expression content. The top-level `expression` property is required and contains all expression configuration. * `expression` (_Expression_, required) * `sfdc_cms:description` (_string_) Description of the expression. Maximum length: 255. * `lightning:dataProviders` (_array of DataProvider_) Data provider configurations for expression evaluation. ### Expression Expression configuration containing evaluation logic. The expression object wraps all groups, the definition identifier, a label, and an expression key. * `expressionGroups` (_array of ExpressionGroup_, required) Array of expression groups. Each group references a data resource and optionally applies filtering rules and sorting. Group names must be unique. * `definition` (_string_) Expression definition identifier. * `label` (_string_) Display label for the expression. * `sfdcExpressionKey` (_string_) Unique key used to reference this expression in merge fields. * `default` (_string_) Default value when the expression resolves to no results. ### DataProvider The data provider configuration for evaluating the expression. * `sfdcExpressionKey` (_string_) The expression key prefix used in resource references. * `definition` (_string_) The data provider definition. * `attributes` (_object_) Configuration attributes for the data provider. ### ExpressionGroup An expression group that references a data resource and optionally filters/sorts results. Groups can chain references to other groups using merge-field syntax: * Direct data source: `{!$dataGraph.Sales_Order_Product__dlm}`. * Reference to another group's field: `{!group0.Name__c}`. Group names must be unique within the expression (enforced by schema). * `name` (_string_) Unique name for the expression group (used for inter-group references). * `resource` (_string_, required) Data resource reference. Can be: * A data graph reference: `{!$dataGraph.ObjectName__dlm}`. * A reference to another group's field: `{!groupName.FieldName__c}`. * `expressionRule` (_ExpressionRule_) * `expressionSort` (_ExpressionSort_) * `selectionIndex` (_number | string_) Index of the value to be selected from the result set. Can be a number or a merge-field string matching the pattern `{!variableName}`. One of: `number`, `string`. * _string_ Type: `string`. Pattern: ^\\{!\[a-zA-Z\]+\\}$. ### ExpressionRule Defines filter criteria for an expression group. Criteria are combined using the specified `criteriaType` logic. * `name` (_string_) Rule name identifier. * `description` (_string_) Human-readable rule description. * `criteriaType` (_string_) Determines how criteria in the expression are combined: * `AllCriteriaMatch` — All criteria must be true (AND). * `AnyCriterionMatches` — Any criterion can be true (OR). * `CustomLogicMatches` — Use custom formula. Allowed values: `AllCriteriaMatch`, `AnyCriterionMatches`, `CustomLogicMatches`. * `expressionCriteria` (_array of ExpressionCriterion_, required) List of criteria to evaluate. * `customFormula` (_string_) Custom formula for combining criteria (only used with `CustomLogicMatches`). References criteria by their `criterionNumber`. ### ExpressionSort The sort configuration for an expression group's result set. * `orderBy` (_string_, required) Field to sort by. * `sortOrder` (_string_, required) Sort direction. Allowed values: `ASC`, `DESC`. * `index` (_number_, deprecated) The index of the selected value. This property is deprecated. Use `selectionIndex` on the expression group. ### ExpressionCriterion A single filter criterion within an expression rule. * `resource` (_string_, required) The field or resource path to evaluate. For example, this property can reference the API name of a field. * `operator` (_string_, required) The comparison operator. Possible values: `EQUALS`, `NOT_EQUALS`, `CONTAINS`, `NOT_CONTAINS`, `STARTS_WITH`, `ENDS_WITH`, `GREATER_THAN`, `LESS_THAN`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN_OR_EQUAL`, `IS_NULL`, `IS_NOT_NULL`, `IN`, and `NOT_IN`. * `value` (_string | number | boolean | array of any_, required) The value to compare against. The type depends on the operator and field. One of: `string`, `number`, `boolean`, `array of any`. * `criterionNumber` (_number_) The ordinal position of this criterion in the rule. Used in custom formulas. Minimum: 1. Maximum: 100.