Edit

Share via


Basic operations on segments using API in outbound marketing

Note

Dynamics 365 Marketing and Dynamics 365 Customer Insights are now Customer Insights - Journeys and Customer Insights - Data. For more information, see Dynamics 365 Customer Insights FAQs

New Customer Insights - Journeys customers receive real-time journeys features only. For more information, see Default real-time journeys installation.

Important

This article only applies to outbound marketing, which is gradually being removed from Customer Insights - Journeys. To avoid interruptions, stop using outbound marketing and transition to real-time journeys. Learn more: Transition overview.

A marketing segment is a group of contacts you target in a marketing campaign. Sometimes, you target all your contacts, but usually, you choose who to target based on demographic, firmographic, or other data. More information: Working with segments.

The segmentation API lets you interact with segment records programmatically. It uses the standard Microsoft Dataverse Web API to work with entities or messages. More information: Use the Microsoft Dataverse Web API. When you create a segment, its properties are stored in the msdyncrm_segment entity. You can view the entity metadata by using @odata.context in the GET response.

Note

Before you do any actions, install Dynamics 365 Customer Insights - Journeys.

This article shows how to do basic actions on the msdyncrm_segment entity. Enter the following required 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 three types of segments:
- Static 192350001
- Dynamic 192350000
- Compound 192350002
Yes.
Status Reason statuscode Current status of the segment. The available status codes are:
- Draft 192350000
- Live 192350001
- Stopped 192350002
- GoingLive 192350006
- Stopping 192350007
Yes.
Segment Query msdyncrm_query Query in the segmentation query. Yes (only for dynamic and compound segments).

CRUD operations on static segments

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

Create request

This request creates a new static segment with two contacts and sets statuscode to Draft. The response header has the URL to the new record (entity instance), which includes the unique ID (segmentID) for this record.

Important

Replace OrgUrl with https://<add your environment name, like ‘myorg.crm’>.dynamics.com. 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 crm prefix shows the record identifier type clearly. Use it when you use a legacy segmentation solution, which by default uses a different type of identifier.

Update request

This request updates the statuscode of the static segment to Going Live (192350006). When you run the request, it sets statuscode to Live.

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

Retrieve request

This request gets all static segments that are in the Live state.

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

You can also get segments with specific properties.

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

Delete request

This request deletes the created static segment.

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

CRUD operations on dynamic segments

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

Create request

This request creates a dynamic segment and sets statuscode to Draft.

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_segments
{
    "msdyncrm_segmentname": "Customers with name and email",
    "msdyncrm_segmentquery": "PROFILE(contact, contact_1).FILTER(ISNOTNULL(contact_1.emailaddress1) && ISNOTNULL(contact_1.fullname))",
    "msdyncrm_segmenttype": 192350000,
    "statuscode": 192350000
}

The following request creates a dynamic segment with a conditional segment query to get 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
}

The following request creates a new dynamic segment and sets statuscode to Going Live.

POST api/data/v9.0/msdyncrm_segments
{

  "msdyncrm_segmentname": "Customers with name and email",
  "msdyncrm_segmenttype": 192350000,
  "msdyncrm_segmentquery": "PROFILE(contact, contact_1).FILTER(ISNOTNULL(contact_1.emailaddress1) && ISNOTNULL(contact_1.fullname))",
  "statuscode": 192350006
}

Update request

Use the update request to change the status of the dynamic segment to Going Live.

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

Note

Don't move the segments directly to the Live state.

Retrieve request

Use the retrieve request to get all the dynamic segments that are in the Stop state.

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

Delete request

Use the delete request to remove the dynamic segment.

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

CRUD operations on compound segments

This section shows how to do 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_query":"SEGMENT(segment1) UNION SEGMENT(segment2)",
    "statuscode": 192350006
}

Update request

Use the update request to change the status of the compound segment to Stopping.

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

Note

Don't move the segments directly to the Stopped state.

Retrieve request

Use the retrieve request to get all the compound segments that are in the Stop state.

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

Delete request

Use the delete request to remove the compound segment.

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

Add/Remove contacts to static segments

Segment members can be added to or removed from static segments of contacts. You can add/remove contacts either by providing a query definition, or by providing specific contact IDs.

Keep these important points in mind when you add or remove segment members:

  • Only instances of the entity type Contact can be added or removed as members.
  • If a contact ID doesn't exist, the system ignores it.
  • The system processes add or remove member requests asynchronously.
  • If you use business unit scoping, adding a contact that the segment owner can't access can hang the segment and make it unusable. Make sure your code doesn't add contacts from the wrong business unit.
  • Add or remove contacts by invoking the endpoint multiple times, usually in batches of up to 20,000 contacts each time.

Add segment members by providing IDs

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

Remove segment members by providing IDs

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

Add segment members by providing a query

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_SegmentMembersUpdate
{
    "msdyncrm_segmentid": "b5466fbb-2cef-e911-a81d-000d3a6d200c",
    "msdyncrm_operation": "addByQuery",
    "msdyncrm_query": "PROFILE(account, account_1).FILTER(account_1.accountid == '1cc00a15-37ef-e911-a81d-000d3a6d200c').TRAVERSE(contact_account_parentcustomerid, contact_1).FILTER(ISNOTNULL(contact_1.emailaddress1))"
}

Remove segment members by providing a query

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_SegmentMembersUpdate
{
    "msdyncrm_segmentid": "b5466fbb-2cef-e911-a81d-000d3a6d200c",
    "msdyncrm_operation": "removeByQuery",
    "msdyncrm_query": "PROFILE(account, account_1).FILTER(account_1.accountid == '1cc00a15-37ef-e911-a81d-000d3a6d200c').TRAVERSE(contact_account_parentcustomerid, contact_1).FILTER(ISNOTNULL(contact_1.emailaddress1))"
}

Get status of pending operations

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_SegmentMembersUpdate
{
    "msdyncrm_segmentid":"b5466fbb-2cef-e911-a81d-000d3a6d200c",
    "msdyncrm_operation":"getState"
}

Retrieve segment members (recommended)

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_FetchContactsByQuery
{
    "Query":"(SEGMENT(SEGMENT_CRM_ID_e1fa7fdc5c78ea11a811000d3a8e8fcc)).ORDERBY(fullname ASC).SKIP(0).TAKE(15).SELECT(contactid)",
    "FetchXml":"<fetch version=\"1.0\" output-format=\"xml-platform\" mapping=\"logical\" count=\"15\" page=\"1\" returntotalrecordcount=\"true\"><entity name=\"contact\"><attribute name=\"fullname\"/><attribute name=\"emailaddress1\"/><attribute name=\"company\"/><attribute name=\"parentcustomerid\"/><attribute name=\"contactid\"/><order attribute=\"fullname\" descending=\"false\"/></entity></fetch>","OwningBusinessUnit":"0b4b85cc-7f6c-ea11-a811-000d3a54d359",
    "Scope":270100000,
    "TimeZone":null
}

Important

In the example above, replace SEGMENT_CRM_ID_ce97cb9dbd75ea11a811000d3a8e8fcc with the name of your segment in the backend, as it appears in the msdyncrm_segmentqueryname field of your segment. If your segment has the ID ce97cb9d-bd75-ea11-a811-000d3a8e8fcc, that value is SEGMENT_CRM_ID_ce97cb9dbd75ea11a811000d3a8e8fcc.

Retrieve segment members (deprecated)

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

Before you create or change a segment, check the new definition by using the validation endpoint. The endpoint always returns an HTTP status OK message and an object with a ValidationResult property that has an array of errors.

If the definition is valid, the result array is empty. Otherwise, it shows records for the identified issues. The segment definition is checked when you create the record, and the status code is set to Going Live.

Validation is skipped when you create a segment in Draft state. Failed validation returns 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 an 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_query\"}]"
}