--- schema_version: "1" id: 760e8162741b0ba79828de6e36441282d0f1a0deaee67d04250d9349052debe7 title: Segments (Data Cloud 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-connect-segments.md canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-connect-segments source_site: developer.salesforce.com content_type: documentation content_hash: c5ae7d8c27565856696d604b2becc430da1f3ace480f1dfd4e64175db531cb09 products: - Marketing Cloud Next - Marketing Cloud --- Segments (Data Cloud Connect API) # Segments (Data Cloud Connect API) Manage and modify segments in Marketing Cloud Next synchronously using Connect API. This table lists the segment-related use cases that Connect API supports. | Supported Use Case | HTTP Verb | URI | | --- | --- | --- | | Get segments | [GET](/docs/marketing/marketing-cloud-growth/references/mc-connect-segments?meta=getSegments) | /services/data/{apiVersion}/ssot/segments | | Get segment details | [GET](/docs/marketing/marketing-cloud-growth/references/mc-connect-segments?meta=getSegmentDetails) | /services/data/{apiVersion}/ssot/segments/{segmentApiName} | | Get segment members | [GET](/docs/marketing/marketing-cloud-growth/references/mc-connect-segments?meta=getSegmentMembers) | /services/data/{apiVersion}/ssot/segments/{segmentApiName}/members | | Delete a segment | [DELETE](/docs/marketing/marketing-cloud-growth/references/mc-connect-segments?meta=deleteSegment) | /services/data/{apiVersion}/ssot/segments/{segmentApiName} | | Publish a segment | [POST](/docs/marketing/marketing-cloud-growth/references/mc-connect-segments?meta=publishSegment) | /services/data/{apiVersion}/ssot/segments/{segmentId}/actions/publish | **Version:** v68.0 ## Servers * `https://{subdomain}.my.salesforce.com` * `subdomain (default (no default)) The unique API subdomain for your Salesforce org.` ## Operations ### GET Retrieve a list of segments in your org. `GET /services/data/{apiVersion}/ssot/segments` Operation ID: `getSegments`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to Connect API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `batchSize` (query, number (integer)) The number of items to return. The minimum value is 1 and the maximum is 200. The default value is 20. * `dataspace` (query, string) The name of the dataspace to perform the action in. You must have permission to access this dataspace. The default value is equal to the default dataspace. * `offset` (query, number (integer)) The number of rows to skip in the result set. For example, to skip the first 20 values, specify an offset of 20. * `orderBy` (query, string) The order to sort the result set in, such as `Name ASC` or `MarketSegmentType DESC`. The default value is `id ASC`. #### Responses * **200** This response indicates that the API accepted your request to retrieve a list of segments. Media type: `application/json`. Schema: `segmentsGetResponseBody`. _Example_ ``` { "batchSize": 20, "offset": 0, "orderByExpression": "[Name asc]", "segments": [ { "apiName": "Running_Shoe_Promo_Audience", "displayName": "Running Shoe Promo Audience", "marketSegmentDefinitionId": "3HX1Q000000HxyZWAS", "marketSegmentId": "1sg1Q000000HxyZQAS", "publishInterval": "NO_REFRESH", "publishStatus": "SUCCESS", "segmentMembershipTable": "Individual_Unified_SMH_1234567890123__dlm", "segmentOnId": "0gj1Q000000PQ3xYZG", "segmentStatus": "ACTIVE", "segmentType": "UI" } ] } ``` * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that your authorization token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "message": "Session expired or invalid", "errorCode": "INVALID_SESSION_ID" } ] ``` ### GET Retrieve more information about a segment in your org. `GET /services/data/{apiVersion}/ssot/segments/{segmentApiName}` Operation ID: `getSegmentDetails`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to Connect API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `segmentApiName` (path, string, required) The API name of the target segment. #### Responses * **200** This response indicates that the API accepted your request to retrieve details about a segment. Media type: `application/json`. Schema: `segmentsGetDetailsResponseBody`. _Example_ ``` { "segments": [ { "apiName": "My_New_Segment", "dataSpace": "default", "displayName": "My New Segment", "marketSegmentDefinitionId": "3HX1Q000000HuaIWAS", "marketSegmentId": "1sg1Q000000HudAQAS", "publishInterval": "NO_REFRESH", "publishStatus": "SUCCESS", "segmentMembershipDmo": { "historyTable": "Individual_Unified_SMH_1704835405687__dlm", "latestTable": "Individual_Unified_SM_1704835403879__dlm" }, "segmentMembershipTable": "Individual_Unified_SMH_1704835405687__dlm", "segmentOnApiName": "UnifiedIndividual__dlm", "segmentOnId": "0gj1Q000000PQ3dQAG", "segmentStatus": "ACTIVE", "segmentType": "UI" } ] } ``` * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that your authorization token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "message": "Session expired or invalid", "errorCode": "INVALID_SESSION_ID" } ] ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that your request included the correct segment name or ID. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "errorCode": "ITEM_NOT_FOUND", "message": "Segment not found: 2023_Top_Customers_Campaign" } ] ``` ### DELETE Delete a segment. `DELETE /services/data/{apiVersion}/ssot/segments/{segmentApiName}` Operation ID: `deleteSegment`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to Connect API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `segmentApiName` (path, string, required) The API name of the target segment. #### Responses * **204** Indicates that the API accepted your request to delete the segment. The response contains no content. * **400** This response indicates that the API wasn’t able to process your request. This error can occur if you specify an incorrect field name or parameter. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "message": "We couldn’t delete this segment. Update the segment type to Dbt or Lookalike and try again.", "errorCode": "DELETE_NOT_ALLOWED" } ] ``` * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that your authorization token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "message": "Session expired or invalid", "errorCode": "INVALID_SESSION_ID" } ] ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that your request included the correct segment name or ID. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "errorCode": "ITEM_NOT_FOUND", "message": "Segment not found: 2023_Top_Customers_Campaign" } ] ``` ### GET Retrieve a list of segment members. `GET /services/data/{apiVersion}/ssot/segments/{segmentApiName}/members` Operation ID: `getSegmentMembers`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to Connect API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `segmentApiName` (path, string, required) The API name of the target segment. * `fields` (query, string) A list of field names to return in the result set. Separate each item with a comma, for example, `Id__c, Delta_Type__C`. The default value is `Id__c`. * `filters` (query, string) A set of expressions that filter fields based on their values, such as `[Delta_Type__C in('new') AND timestamp__C > '2023-04-02']`. * `limit` (query, number (integer)) The maximum number of rows to return in the result. The minimum value is 1 and the maximum is 1000. The default is 100. * `offset` (query, number (integer)) The number of rows to skip in the result set. For example, to skip the first 20 values, specify an offset of 20. * `orderBy` (query, string) The order to sort the result set in, such as `Name ASC` or `MarketSegmentType DESC`. The default value is `id ASC`. #### Responses * **200** This response indicates that the API accepted your request to retrieve a list of segment members. Media type: `application/json`. Schema: `segmentsGetMembersResponseBody`. _Example_ ``` { "data": [ { "deltaType": "new", "id": "1175a1b5c71d8cc748449c309bd57965", "snapshotType": "F", "timestamp": "2024-01-23T18:25:02.924Z", "versionStamp": "2024-01-22T18:29:11.841Z" }, { "deltaType": "new", "id": "16a53160ecf58f10640bf1dfd72c042a", "snapshotType": "F", "timestamp": "2024-01-23T18:25:02.924Z", "versionStamp": "2024-01-22T18:29:11.841Z" }, { "deltaType": "new", "id": "3446954495e5c51aaa3c5286538a5406", "snapshotType": "F", "timestamp": "2024-01-23T18:25:02.924Z", "versionStamp": "2024-01-22T18:29:11.841Z" } ], "endTime": "2024-01-24T22:02:59.000Z", "filter": "Delta_Type__c in ( new , existing )", "limit": 100, "offSet": 0, "orderBy": "Id__c asc", "rowCount": 3, "startTime": "2024-01-24T22:02:59.000Z", "totalCount": 3 } ``` * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that your authorization token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "message": "Session expired or invalid", "errorCode": "INVALID_SESSION_ID" } ] ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that your request included the correct segment name or ID. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "errorCode": "ITEM_NOT_FOUND", "message": "Segment not found: 2023_Top_Customers_Campaign" } ] ``` ### POST Publish a segment. `POST /services/data/{apiVersion}/ssot/segments/segmentId/actions/publish` Operation ID: `publishSegment`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to Connect API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `segmentId` (path, string, required) The ID of the segment to publish. #### Responses * **201** This response indicates that the API accepted your request to publish the segment. Media type: `application/json`. Schema: `segmentsPublishResponseBody`. _Example_ ``` { "errors": [ {} ], "jobId": "fa7ef500-1385-4892-919e-45e17f78da60", "partitionId": "1sg1Q000000Xy2z_af7f1fed-6086-4f4d-9301-a4c7dde7b032", "publishStatus": "PUBLISHING", "segmentId": "1sg1Q000000Hm2xYAC", "success": true } ``` * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that your authorization token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "message": "Session expired or invalid", "errorCode": "INVALID_SESSION_ID" } ] ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that your request included the correct segment name or ID. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "errorCode": "ITEM_NOT_FOUND", "message": "Segment not found: 2023_Top_Customers_Campaign" } ] ``` ## Schemas ### segmentsGetResponseBody * `batchSize` (_number (integer)_) The number of results to return in a request. * `offset` (_number (integer)_) The offset for retrieving results. For example, if the batch of results begins with the 21st value in the result set, this value is `21`. * `orderByExpression` (_string_) An expression that defines the order that results are returned in. * `segments` (_array of object_) * `apiName` (_string_) The API name of the segment. * `displayName` (_string_) The display name of the segment. * `marketSegmentDefinitionId` (_string_) The ID of the market segment definition. * `marketSegmentId` (_string_) The ID of the market segment. * `publishInterval` (_string_) The time interval at which the segment is refreshed. * `publishStatus` (_string_) The publish status of the segment. * `segmentMembershipTable` (_string_) The name of the segment membership table. * `segmentOnId` (_string_) The ID of the data model object (DMO) segment. * `segmentStatus` (_string_) The status of the segment. * `segmentType` (_string_) A description of the segment type. ### httpErrorResponseBody Array of `object`. * `errorcode` (_string_) The error message. * `message` (_string_) A detailed error message. ### segmentsGetDetailsResponseBody * `segment` (_array of object_) * `apiName` (_string_) The API name of the segment. * `displayName` (_string_) The display name of the segment. * `marketSegmentDefinitionId` (_string_) The ID of the market segment definition. * `marketSegmentId` (_string_) The ID of the market segment. * `publishInterval` (_string_) The time interval at which the segment is refreshed. * `publishStatus` (_string_) The publish status of the segment. * `segmentMembershipTable` (_string_) The name of the segment membership table. * `segmentOnId` (_string_) The ID of the data model object (DMO) segment. * `segmentStatus` (_string_) The status of the segment. * `segmentType` (_string_) A description of the segment type. ### segmentsGetMembersResponseBody * `data` (_array of object_) * `deltaType` (_string_) The delta type. Allowed values: `new`, `existing`, `removed`. * `id` (_string_) The record ID for the segment member. * `snapshotType` (_string_) The type of snapshot. Allowed values: `full`, `incremental`. * `timestamp` (_string (date-time)_) The date and time that the contact was added to the segment. * `versionStamp` (_string (date-time)_) The date and time of the segment version. * `endTime` (_string (date-time)_) The end time for the query. * `filter` (_string_) An expression that defines fields to omit in the result set. * `limit` (_number (integer)_) The maximum number of segment members to return. * `offset` (_number (integer)_) The offset for retrieving results. For example, if the batch of results begins with the 21st member of the segment, this value is `21`. * `orderBy` (_string_) An expression that defines the order that results are returned in. * `rowCount` (_number (integer)_) The number of records returned in the current batch of results. * `startTime` (_string (date-time)_) The start time for the query. * `totalCount` (_number (integer)_) The total number of segment members. ### segmentsPublishResponseBody * `errors` (_array of object_) * `errorCode` (_string_) An error code. This property is only returned if the request resulted in an error. * `errorMessage` (_string_) A description of the error. This property is only returned if the request resulted in an error. * `jobId` (_string (uuid)_) A unique ID for the request to publish the segment. * `partitionId` (_string_) The ID of the segment partition. * `publishStatus` (_string_) A description of the status of the publish request. * `segmentId` (_string_) The unique ID of the segment. * `success` (_boolean_) Indicates whether the request to publish the segment was successful.