Basic operations on segments using the Segmentation API

A market segment is the collection of contacts that you target in a marketing campaign. In some cases, you'll simply target all the contacts you have, but in most cases, you'll choose whom you want to target based on demographic or firmographic data and other considerations. More information: Working with segments.

The Segmentation API enables programmatic interaction with segment records. The Segmentation API leverages the standard Dynamics 365 API for manipulating entities or messages. More information: Dynamics 365 Web API. When you create a segment, the properties of the segment are stored in the msdyncrm_segment entity. You can browse the entity metadata information using @odata.context in the GET response.

Note

Before you perform operations, you should install the Dynamics 365 Marketing app.

This topic demonstrates how to perform a basic operation on the msdyncrm_segment entity. You need to pass the following mandatory fields to create a segment.

Display name Schema name Value Required
Name msdyncrm_segmentname Name of the segment. Yes.
Segment Type msdyncrm_segmenttype Type of segment. There are 3 types of segments:
- Static 192350001
- Dynamic 192350000
- Compound 192350002
Yes.
Status Reason statuscode Current status of the segment. These are the available status codes:
- Draft 192350000
- Live 192350001
- Stopped 192350002
- GoingLive 192350006
- Stopping 192350007
Yes.
Segment Query msdyncrm_segmentquery Query in the segmentation query. Yes (only for dynamic and compound segments).

To test the operations, you can use the Postman tool. More information: Use Postman with Web API.

CRUD operations on static segments

This section shows how to perform basic CRUD (create, update, retrieve, and delete) operations on static segments.

Create request

This request creates a new static segment with two contacts and statuscode set to “Draft”. The response header contains the URL to this newly created record (entity instance), which parenthetically includes the unique ID (segmentID) for this record.

Important

You need to replace OrgUrl with https://<add your environment name, like ‘myorg.crm’>.dynamics.com. You can also get the environment name from Settings -> Customizations -> Developer Resources.

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_segments
{
  "msdyncrm_segmentname": "StaticSegmentApi1",
  "msdyncrm_segmenttype": 192350001,
  "msdyncrm_segmentmemberids": "[\"crm1405f4ba-1ee9-e811-a99d-000d3a35f12f\",\"crm0604cdd1-1ee9-e811-a99d-000d3a35f12f\"]",
  "statuscode": 192350000
}

Important

The purpose of the crm prefix is to indicate the record identifier type unambiguously. This is required when you are using a legacy segmentation solution, which, by default, uses a different type of identifier.

Update request

With the update request, you update the statuscode of the static segment to Going Live (192350006). When the request is executed, it updates statuscode to “Live”.

PATCH {{OrgUrl}}/api/data/v9.0/msdyncrm_segments({{SegmentId}})
{
  "statuscode": 192350006
}

Retrieve request

With the retrieve request, you retrieve all the static segments that are in the Live state.

GET {{OrgUrl}}/api/data/v9.0/msdyncrm_segments?$filter=statuscode eq 192350001

You can also retrieve segments with specific properties.

GET {{OrgUrl}}/api/data/v9.0/msdyncrm_segments?$select=msdyncrm_segmentid,msdyncrm_segmentname,msdyncrm_segmentquery,msdyncrm_description

Delete request

With the delete request, you delete the created static segment.

DELETE {{OrgUrl}}/api/data/v9.0/msdyncrm_segments({{SegmentId}})

CRUD operations on dynamic segments

This section shows how to perform basic CRUD (create, update, retrieve, and delete) operations on dynamic segments. Dynamic segments are based on the segment query (msdyncrm_segmentquery). More information: Segment query definition.

Create request

This request creates a dynamic segment and sets statuscode to Going live.

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_segments
{
    "msdyncrm_segmentname": "MySegment2",
    "msdyncrm_segmentquery": "PROFILE(contact)",
    "msdyncrm_segmenttype": 192350000,
    "statuscode": 192350006
}

The following request creates a dynamic segment with a conditional segment query to retrieve only contacts that have the address1_city field set to NewYork or NewJersey.

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_segments
{
    "msdyncrm_segmentname": "MySegment2",
    "msdyncrm_segmentquery": "PROFILE(contact).FILTER((address1_city == 'NewYork' || address1_city == 'NewJersey'))",
    "msdyncrm_segmenttype": 192350000,
    "statuscode": 192350006
}

Update request

With the update request, you update the status of the dynamic segment to “Stop”.

PATCH {{OrgUrl}}/api/data/v9.0/msdyncrm_segments({{SegmentId}})
{
    "statuscode": 192350002
}

Retrieve request

With the retrieve request, you retrieve all the dynamic segments that are in the Stop state.

GET {{OrgUrl}}/api/data/v9.0/msdyncrm_segments?$filter=statuscode eq 192350002

Delete request

With the delete request, you delete the dynamic segment that is created.

DELETE {{OrgUrl}}/api/data/v9.0/msdyncrm_segments({{SegmentId}})

CRUD operations on compound segments

This section shows how to perform basic CRUD (create, update, retrieve, and delete) operations on compound segments.

Create request

This request creates a compound segment and sets statuscode to Going live.

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_segments
{
    "msdyncrm_segmentname": "my_compound_segment1",
    "msdyncrm_segmenttype": 192350002,
    "msdyncrm_segmentquery":"SEGMENT(segment1) UNION SEGMENT(segment2)",
    "statuscode": 192350006
}

Update request

With the update request, you update the status of the compound segment to Stopping.

PATCH {{OrgUrl}}/api/data/v9.0/msdyncrm_segments({{SegmentId}})
{
    "statuscode": 192350007
}

Retrieve request

With the retrieve request, you retrieve all the compound segments that are in the Stop state.

GET {{OrgUrl}}/api/data/v9.0/msdyncrm_segments?$filter=statuscode eq 192350002

Delete request

With the delete request, you delete the compound segment that is created.

DELETE {{OrgUrl}}/api/data/v9.0/msdyncrm_segments({{SegmentId}})

Include/exclude segment members

Segment members can be added to or removed from the segments. As these operations go beyond a simple add or remove they are referred to as Include/Exclude operations.

You can perform Include/exclude operations on segments through API by calling the following methods:

  • msdyncrm_IncludeMemberInSegment
  • msdyncrm_IncludeMembersInSegment
  • msdyncrm_ExcludeMemberFromSegment
  • msdyncrm_ExcludeMembersFromSegment

Including a contact record makes it a member of the segment whether it satisfies the segment query definition (msdyncrm_segmentquery) or not. Including a contact record that is already a member of the segment ensures that it is not removed when it doesn't match the segment query.

Excluding a contact record removes it from the segment and prevents it from being added again even if the record matches the segment query. A record can be excluded from a segment without previously being a member of the segment to prevent it from becoming a member.

Once a member is included, the action can be reversed by excluding it, thereby removing and preventing it from becoming a member. Similarly, excluding a member can be reversed by including it, thereby making it a member unconditionally.

Following are some of the important aspects that need to be considered while performing include/exclude operations on segment members:

Note

For this release, include/exclude operations are not supported for dynamic segments.

  • Compound segments must be in Live or Stopped state (not Draft state).
  • Only instances of entity type Contact can be included/excluded as members.
  • All included/excluded records should exist; otherwise, the request gets rejected.
  • The include/exclude feature is supported only by new segmentation.
  • Include/exclude member requests are processed asynchronously, independent of any recurring segment evaluations.
  • Any include/exclude operation resulting in an actual update to segment members is recorded in Segment Insights.
  • When including or excluding multiple records, use the plural endpoints for faster processing.
  • You can add up to 10,000 contacts to the msdyncrm_segmentmemberid field.

Add a segment member

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_IncludeMemberInSegment
{
  msdyncrm_segmentid: "59AC8BBF-57E7-E811-A9A9-000D3A35F403",
  msdyncrm_segmentmemberid: "B5672BDB-8899-43CB-9FA1-0AE4DC61DAD3"
}

Add multiple segment members

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_IncludeMembersInSegment
{
   msdyncrm_segmentid: "59AC8BBF-57E7-E811-A9A9-000D3A35F403",
   msdyncrm_segmentmemberids: "[\"B5672BDB-8899-43CB-9FA1-0AE4DC61DAD3\", \"694E1C8E-F704-4B23-9B07-E65DB1620E47\", \"A4A31E3D-DFCA-4765-8018-3BA7D5E376C7\"]"
}

Remove a segment member

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_ExcludeMemberFromSegment
{
    msdyncrm_segmentid: "59AC8BBF-57E7-E811-A9A9-000D3A35F403",
    msdyncrm_segmentmemberid: "B5672BDB-8899-43CB-9FA1-0AE4DC61DAD3"

Remove multiple segment members

Remove multiple segment members
POST {{OrgUrl}}/api/data/v9.0/msdyncrm_ExcludeMembersFromSegment
{
   msdyncrm_segmentid: "59AC8BBF-57E7-E811-A9A9-000D3A35F403",
   msdyncrm_segmentmemberids: "[\"B5672BDB-8899-43CB-9FA1-0AE4DC61DAD3\", \"694E1C8E-F704-4B23-9B07-E65DB1620E47\", \"A4A31E3D-DFCA-4765-8018-3BA7D5E376C7\"]" 
}

Retrieve segment members

GET {{OrgUrl}}/api/data/v9.0/contacts?fetchXml=fetch version="1.0" output-format="xml-platform" mapping="logical" returntotalrecordcount="true" page="1" count="5" no-lock="false">
    <entity name="contact">
        <attribute name="fullname"/>
        <attribute name="contactid"/>
        <order attribute="fullname" descending="false"/>
        <link-entity name="msdyncrm_segment" from="msdyncrm_segmentid" to="msdyncrm_segmentmemberid" alias="bb">
            <filter type="and">
                <condition attribute="msdyncrm_segmentid" operator="eq" uitype="msdyncrm_segment" value="bfc9d5d6-d6aa-e911-a859-000d3a3159df"/>
            </filter>
        </link-entity>
    </entity>
</fetch>

Validating segments

Prior to creating or modifying a segment, you can verify the new definition using a dedicated validation endpoint. The endpoint always returns an HTTP status OK message and an object with a property ValidationResult holding an array of errors.

In the case of a valid definition, the result array is empty. Otherwise, it contains records for the identified issues. Segment definition is validated on the creation of the record, and the status code set to Going Live.

Validation is intentionally skipped when a segment is created in Draft state. Also failed validation results in HTTP 400 with an error message in the response body.

Validating a valid segment definition

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_ValidateSegment
{
       "msdyncrm_segmentname":"NewSegment",
       "msdyncrm_segmentquery":"PROFILE(contact)",
       "msdyncrm_segmenttype":192350000,
       "statuscode":192350000
}

Response

{
…
    "ValidationResult": "[]"
}

Validating a invalid segment definition

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_ValidateSegment
{
       "msdyncrm_segmentname":"NewSegment",
       "msdyncrm_segmentquery":"PROFILE(UnknownEntity)",
       "msdyncrm_segmenttype":192350000,
       "statuscode":192350006
}

Response

{
…
    "ValidationResult": "[{\"ErrorCode\":\"SegmentDciValidator_SegmentInvalid\",\"FieldName\":\"msdyncrm_segmentquery\"}]"
}