--- schema_version: "1" id: c63afe08f9df58c637ca05b19dc1d60c598f88d81fdf4fd35a8fcf92788ff5f2 title: Segments (REST 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-rest-segments.md canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-rest-segments source_site: developer.salesforce.com content_type: documentation content_hash: ee06ea2cd5b18bcd5dd820b488c3810690745ad83b471d03b452f975a3d915c6 products: - Marketing Cloud Next - Marketing Cloud --- Segments (REST API) # Segments (REST API) Manage and modify audience segments for Marketing Cloud. This table lists the segment-related use cases that REST API supports. | Supported Use Case | HTTP Verb | URI | | --- | --- | --- | | Delete a segment | [DELETE](/docs/marketing/marketing-cloud-core/references/mc-rest-segments?meta=deleteSegment) | /services/data/{apiVersion}/sobjects/MarketSegment/{segmentId} | | Get updated segments | [GET](/docs/marketing/marketing-cloud-core/references/mc-rest-segments?meta=getUpdatedSegments) | /services/data/{apiVersion}/sobjects/MarketSegment/updated/ | | Get deleted segments | [GET](/docs/marketing/marketing-cloud-core/references/mc-rest-segments?meta=getDeletedSegments) | /services/data/{apiVersion}/sobjects/MarketSegment/deleted/ | **Version:** v68.0 ## Servers * `https://{subdomain}.my.salesforce.com` * `subdomain (default N/A) The unique API subdomain for your Salesforce org.` ## Operations ### GET Retrieve information about a specific marketing segment. `GET /services/data/{apiVersion}/sobjects/MarketSegment/{segmentId}` Operation ID: `getSegment`. #### Parameters * `segmentId` (query, string, required) The record ID of the segment. #### Responses * **200** This response indicates that the API accepted your request to retrieve information about the specified segment. Media type: `application/json`. Schema: `getSegmentResponseBody`. _Example_ ``` { "attributes": { "type": "MarketSegment", "url": "/services/data/{apiVersion}/sobjects/MarketSegment/1sgSB0000007SNlYAM" }, "Id": "1sgSB0000007SNlYAM", "IsDeleted": false, "Name": "TestSegment", "CreatedDate": "2023-12-28T19:00:31.000+0000", "CreatedById": "005SB0000029wwTYAQ", "LastModifiedDate": "2023-12-28T19:02:52.000+0000", "LastModifiedById": "005SB0000029x8fYAA", "SystemModstamp": "2023-12-28T19:02:52.000+0000", "LastViewedDate": "2023-12-28T19:04:05.000+0000", "LastReferencedDate": "2023-12-28T19:04:05.000+0000", "Description": null, "IncludeCriteria": "{\"type\":\"TextComparison\",\"path\":null,\"joinPath\":null,\"subject\":{\"objectApiName\":\"ssot__Contact__dlm\",\"fieldApiName\":\"ssot__Gender__c\"},\"selfReference\":false,\"operator\":\"equal\",\"values\":[\"Male\"]}", "ExcludeCriteria": null, "PublishScheduleInterval": "12", "PublishScheduleStartDateTime": "2023-12-28T20:30:00.000+0000", "PublishScheduleEndDate": "2024-12-28", "LastPublishedEndDateTime": null, "NextPublishDateTime": null, "SegmentStatus": "ACTIVE", "LastSegmentStatusDateTime": "2023-12-28T19:02:51.000+0000", "LastSegmentStatusErrorCode": null, "LastSegmentMemberCount": 434, "LastSegmentRemainderCount": 566, "LastSegmentExcludedCount": 0, "PublishStatus": null, "LastPublishStatusDateTime": null, "LastPublishStatusErrorCode": null, "LastSegmentStatusErrorDetails": null, "DataSpaceId": "0vhSB0000002z2bYAA", "SegmentMembershipDataModelList": null, "MarketSegmentType": "UI", "SeedModelStatus": "INACTIVE", "LastSeedModelStatusDateTime": null, "LastSeedModelStatusErrorCode": null, "LastSeedModelRunDateTime": null, "LastSegmentTotalCount": 1000, "LastSegmentIncludedCount": 434, "PublishType": "STANDARD", "SegmentMembershipTable": null, "IsSeedSegment": false, "SeedSimilarityHighToMedium": null, "SeedSimilarityMediumToLow": null, "SeedSimilarity": null, "LastSegmentCountEndDateTime": "2023-12-28T19:02:52.000+0000" } ``` * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you've obtained an authorization token and that the 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 record ID for the segment. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "errorCode": "NOT_FOUND", "message": "The requested resource does not exist" } ] ``` ### DELETE Delete a segment `DELETE /services/data/{apiVersion}/sobjects/MarketSegment/{segmentId}` Operation ID: `deleteSegment`. #### Parameters * `segmentId` (query, string, required) The record ID of the segment. #### Responses * **204** Indicates that the API accepted your request to delete the segment. The response contains no content. * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you've obtained an authorization token and that the 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 record ID for the segment. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "errorCode": "NOT_FOUND", "message": "The requested resource does not exist" } ] ``` ### GET Get a list of segments that were modified within a specified range of dates. `GET /services/data/{apiVersion}/sobjects/MarketSegment/updated/` Operation ID: `getUpdatedSegments`. #### Parameters * `start` (query, string, required) The start date for the query. Express the date as an ISO 8601 timestamp string, such as `2023-08-05T00:00:00.000Z`. * `end` (query, string, required) The end date for the query. Express the date as an ISO 8601 timestamp string, such as `2023-08-05T00:00:00.000Z`. #### Responses * **200** This response indicates that the API accepted your request to retrieve information about segments that were modified or deleted in the specified date range. Media type: `application/json`. Schema: `getUpdatedSegmentResponseBody`. _Example_ ``` { "ids": [ "1sgOG000000015xYAA", "1sgOG000000016MYAQ", "1sgOG000000017jYAA" ], "latestDateCovered": "2023-11-17T00:00:00.000+0000" } ``` * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you've obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "message": "Session expired or invalid", "errorCode": "INVALID_SESSION_ID" } ] ``` ### GET Get a list of segments deleted in a date range `GET /services/data/{apiVersion}/sobjects/MarketSegment/deleted/` Operation ID: `getDeletedSegments`. Get a list of segments that were deleted within a specified range of dates. #### Parameters * `start` (query, string, required) The start date for the query. Express the date as an ISO 8601 timestamp string, such as `2023-08-05T00:00:00.000Z`. * `end` (query, string, required) The end date for the query. Express the date as an ISO 8601 timestamp string, such as `2023-08-05T00:00:00.000Z`. #### Responses * **200** This response indicates that the API accepted your request to retrieve information about segments that were modified or deleted in the specified date range. Media type: `application/json`. Schema: `getUpdatedSegmentResponseBody`. _Example_ ``` { "ids": [ "1sgOG000000015xYAA", "1sgOG000000016MYAQ", "1sgOG000000017jYAA" ], "latestDateCovered": "2023-11-17T00:00:00.000+0000" } ``` * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you've obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "message": "Session expired or invalid", "errorCode": "INVALID_SESSION_ID" } ] ``` ## Schemas ### getSegmentResponseBody * `attributes` (_object_) * `type` (_string_) * `url` (_string_) * `Id` (_string_) * `IsDeleted` (_boolean_) * `Name` (_string_) * `CreatedDate` (_string (date-time)_) * `CreatedById` (_string_) * `LastModifiedDate` (_string (date-time)_) * `LastModifiedById` (_string_) * `SystemModstamp` (_string (date-time)_) * `LastViewedDate` (_string (date-time)_) * `LastReferencedDate` (_string (date-time)_) * `Description` (_string_) * `IncludeCriteria` (_string_) * `ExcludeCriteria` (_string_) * `PublishScheduleInterval` (_string_) * `PublishScheduleStartDateTime` (_string (date-time)_) * `PublishScheduleEndDate` (_string_) * `LastPublishedEndDateTime` (_string (date-time)_) * `NextPublishDateTime` (_string (date-time)_) * `SegmentStatus` (_string_) * `LastSegmentStatusDateTime` (_string (date-time)_) * `LastSegmentStatusErrorCode` (_number (int)_) * `LastSegmentMemberCount` (_number (int)_) * `LastSegmentRemainderCount` (_number (int)_) * `LastSegmentExcludedCount` (_number (int)_) * `PublishStatus` (_string_) * `LastPublishStatusDateTime` (_string (date-time)_) * `LastPublishStatusErrorCode` (_string_) * `LastSegmentStatusErrorDetails` (_string_) * `DataSpaceId` (_string_) * `SegmentMembershipDataModelList` (_string_) * `MarketSegmentType` (_string_) * `SeedModelStatus` (_string_) * `LastSeedModelStatusDateTime` (_string (date-time)_) * `LastSeedModelStatusErrorCode` (_string_) * `LastSeedModelRunDateTime` (_string (date-time)_) * `LastSegmentTotalCount` (_number (int)_) * `LastSegmentIncludedCount` (_number (int)_) * `PublishType` (_string_) * `SegmentMembershipTable` (_string_) * `IsSeedSegment` (_boolean_) * `SeedSimilarityHighToMedium` (_string_) * `SeedSimilarityMediumToLow` (_string_) * `SeedSimilarity` (_string_) * `LastSegmentCountEndDateTime` (_string (date-time)_) ### httpErrorResponseBody Array of `object`. * `errorcode` (_string_) The error message. * `message` (_string_) A detailed error message. ### getUpdatedSegmentResponseBody * `ids` (_array of string_) Each item: Segment IDs that were modified between the `start` date and the `end` date. * `latestDateCovered` (_string_) The `end` date for the query. ### postSegmentRequestBody * `name` (_string_) Required. The name of the segment. * `description` (_string_) A description of the segment. * `includeCriteria` (_string_) The query to execute to determine members to include in the segment. * `excludeCriteria` (_string_) The query to execute to determine members to exclude from the segment. * `publishScheduleInterval` (_string_) The frequency with which the segment is published, in hours. Allowed values: `NO_REFRESH`, `1`, `2`, `4`, `6`, `12`, `24`. * `publishScheduleStartDateTime` (_string_) The date and time at which the segment is published, in ISO 8601 format. * `publishScheduleEndDate` (_string_) The date and time to stop publishing the segment, in ISO 8601 format. * `dataSpaceId` (_number_) * `publishType` (_string_) Allowed values: `STANDARD`, `RAPID`. * `isSeedSegment` (_boolean_) Required. If `true`, the segment can be used to create look-alike segments. _Example_ ``` { "name": "", "description": "", "includeCriteria": "Birthdate__c <= 1970-01-01T00:00:00.000Z AND ", "excludeCriteria": "", "publishScheduleInterval": "", "publishScheduleStartDateTime": "", "publishScheduleEndDate": "", "dataSpaceId": 0, "publishType": "STANDARD", "isSeedSegment": false } ```