Edit

Basic outbound marketing customer journey API operations

  • Article

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.

Potential customers follow a path as they engage with your company. They start by discovering your product, evaluating whether it meets their needs, looking for a good offer, then finally making a purchase. This process is called the customer journey.

You can use customer journeys to create a model that guides members of marketing segments through this process using automated messaging, activity generation, interactive decision points, and more. More information: Create Customer Journey.

The customer journey API enables programmatic interaction with customer journey records, including publishing and validation. The API uses the standard Microsoft Dataverse Web API for manipulating entities and messages. More information: Use the Microsoft Dataverse Web API.

When you create a customer journey, the properties are stored in the msdyncrm_customerjourney entity. You can browse the entity metadata information using @odata.contextin the GET response.

Note

Before you perform operations, you should install Dynamics 365 Customer Insights - Journeys.

This article demonstrates how to perform operations on the msdyncrm_customerjourney entity. The msdyncrm_name field is the only required field to create a customer journey. The fields that are used in this article to create a customer journey are shown in the following table.

Display name Schema name Description or value
Name msdyncrm_name Name of the Customer Journey
Status Reason statuscode Current status of the customer journey. Following are the available status codes:
- Draft 192350000
- Live 192350001
- Stopped 192350002
- Live, Editable 192350003
- Error 192350005
- Going Live 192350006
- Stopping 192350007
Suppression Segment msdyncrm_SuppressionSegmentId The ID of the associated Suppression Segment. Use it to set reference to a record from msdyncrm_segments record set.
Recurrence Interval (Days) msdyncrm_recurrenceintervaldays The duration of the iteration (in days). Non-negative integer.
Minimum Consent msgdpr_requiredconsent - (1) Consent 587030001
- (2) Transactional 587030002
- (3) Subscriptions 587030003
- (4) Marketing 587030004
- (5) Profiling 587030005
Recurrence Count msdyncrm_recurrencecount The number of iterations. Non-negative integer.
Workflow Definition msdyncrm_workflowdefinition The customer journey design definition. More information: Customer Journey workflow definition.
Customer Journey Designer State msdyncrm_customerjourneydesignerstate This is a hidden field, used by the customer journey designer to persist its internal state. The field should be copied if you are creating a copy of the msdyncrm_workflowdefinition field from another customer journey or customer journey template record.
Time Zone msdyncrm_customerjourneytimezone Effective time zone for the customer journey.
Content Settings msdyncrm_contentsettingsId The ID of associated Content Settings. Use it to reference a record from the msdyncrm_contentsettingss record set.
End Date and Time msdyncrm_enddatetime Date/time value in ISO 8601 UTC format. Note that seconds and milliseconds precision will be disregarded.
Start Date and Time msdyncrm_startdatetime Date/time value in ISO 8601 UTC format. Note that seconds and milliseconds precision will be disregarded.
Is Recurring msdyncrm_isrecurring A Boolean value.
Entity Target msdyncrm_entitytarget - Contact 0
- Account 1
Type msdyncrm_type - Automated 192350000
- LinkedIn 192350001
Status statecode Status of the customer journey.

Note

The statuscode and statecode fields define the state of the customer journey. Changing their values can result in Publishing or Stopping of customer journey workflow. If you wish to go live save the record in Going Live state (statuscode = 192350006). To stop a customer journey record, save the Live record in Stopping state (statuscode = 192350007).

Create, retrieve, update, and delete operations

Create request

This request creates a customer journey record and sets the statuscode to Draft. This customer journey includes a segment with ID:24db2671-1529-e911-a9b7-000d3a1e6adc and Unique Name: TC407937_DynamicSegment_2KZQ1pand an email with ID: 15bd0ab8-c12a-e911-a9b6-000d3a1e6c14. The effective Content Settings has record ID: 1922b1d8-0523-e911-a9ba-000d3a1e689f. The response header OData-EntityId contains the URL to this newly created record (entity instance), which parenthetically includes the unique ID 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_customerjourneys
{
    "msgdpr_requiredconsent": 587030001,
    "msdyncrm_customerjourneydesignerstate": "{\"NextActivityID\":8,\"NextActivityItemID\":42}",
    "msdyncrm_workflowdefinition": "[{\"ActivityTypeId\":\"bpf_root\",\"ParentBranchId\":0,\"ParentRelationshipType\":\"Default\",\"ActivityId\":\"01\",\"Properties\":{\"Items\":[{\"ItemId\":null,\"ActivityTypeId\":\"bpf_root\",\"Title\":\"Undefined\",\"IsNameSystemDefined\":true,\"Name\":\"New ActivityTypeName_bpf_root_TitleText\",\"ActivityItemId\":0}]}},{\"ActivityTypeId\":\"Segment\",\"ParentActivityId\":\"01\",\"ParentBranchId\":0,\"ParentRelationshipType\":\"Default\",\"ActivityId\":\"01_0\",\"Properties\":{\"Items\":[{\"ItemId\":null,\"ActivityTypeId\":\"Segment\",\"Title\":\"Undefined\",\"IsNameSystemDefined\":true,\"Name\":\"New Segment group\",\"ActivityItemId\":23,\"SegmentMergeMethod\":\"Union\"},{\"ItemId\":\"24db2671-1529-e911-a9b7-000d3a1e6adc\",\"ActivityTypeId\":\"SegmentItem\",\"Title\":\"Undefined\",\"IsNameSystemDefined\":true,\"Name\":\"TC407937_DynamicSegment_2KZQ1p\",\"ActivityItemId\":24,\"ContainmentMethod\":\"Inclusion\",\"SegmentSourceType\":\"Segment\",\"DciSegmentName\":\"TC407937_DynamicSegment_2KZQ1p\",\"SegmentDisplayName\":\"TC407937_DynamicSegment_2KZQ1p\",\"Description\":\"\"}]},\"EntityTarget\":\"contact\"},{\"ActivityTypeId\":\"Email\",\"ParentActivityId\":\"01_0\",\"ParentBranchId\":0,\"ParentRelationshipType\":\"Default\",\"ActivityId\":\"01_0_2\",\"Properties\":{\"Items\":[{\"ItemId\":\"15bd0ab8-c12a-e911-a9b6-000d3a1e6c14\",\"ActivityTypeId\":\"Email\",\"Title\":\"Undefined\",\"IsNameSystemDefined\":true,\"Name\":\"Relationship test\",\"ActivityItemId\":32}]},\"EntityTarget\":\"contact\"}]",
    "msdyncrm_customerjourneytimezone": 92,
    "msdyncrm_contentsettingsId@odata.bind": "/msdyncrm_contentsettingss(1922b1d8-0523-e911-a9ba-000d3a1e689f)",
    "msdyncrm_enddatetime": "2019-03-09T11:29:00.000Z",
    "msdyncrm_startdatetime": "2019-02-09T11:29:00.000Z",
    "msdyncrm_name": "Simple Email Sample",
    "msdyncrm_isrecurring": false,
    "msdyncrm_type": 192350000,
    "msdyncrm_entitytarget": 0,
    "statuscode": 192350000,
    "statecode": 0,
    "ownerid@odata.bind": "/systemusers(d0e20c01-d6c6-480f-aab5-0fa6749565a5)"
}

Retrieve request

The retrieve request retrieves the list of Live customer journeys.

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

Update request

With the update request, you update statuscode to, which effectively publishes it.

PATCH {{OrgUrl}}api/data/v9.0/msdyncrm_customerjourneys(8aee9d91-8c2b-e911-a9b7-000d3a1e6adc)
{
    "statuscode": 192350006
}

Delete request

With the delete request, you delete the customer journey that you created earlier.

DELETE {{OrgUrl}}/api/data/v9.0/msdyncrm_customerjourneys(b6faa2b7-b92b-e911-8185-000d3af9d16a)

Check for Errors

The Check for Errors feature checks the current record for missing content and technical errors and then displays the validation results, including error messages that should help the user solve any issues that were found.

The request body is a JSON object, which contains number of data elements with values corresponding to the msdyncrm_customerjourney entity properties. The reference field (for example, Content Settings ID) doesn't use @odata.bind with the record set reference but uses the ID of the referenced record. The following table explains the mapping.

Key Corresponding property msdyncrm_customerjourney entity (logical name)
FieldValueCustomerJourneyId msdyncrm_customerjourneyid
FieldValueStatusCode statuscode
FieldValueName msdyncrm_name
FieldValueStartDateTime msdyncrm_startdatetime
FieldValueEndDateTime msdyncrm_enddatetime
FieldValueWorkflowDefinition msdyncrm_workflowdefinition
FieldValueIsRecurring msdyncrm_isrecurring
FieldValueRecurrenceIntervalDays msdyncrm_recurrenceintervaldays
FieldValueRecurrenceCount msdyncrm_recurrencecount
FieldValueRequiredConsent msgdpr_requiredconsent
FieldValueEntityTarget msdyncrm_entitytarget
FieldValueSuppressionSegmentId msdyncrm_suppressionsegmentid
FieldValueCustomerJourneyTimeZone msdyncrm_customerjourneytimezone

Validate Customer Journey request

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_CustomerJourneyValidate
{
    "FieldValueCustomerJourneyId": "{6628BBF7-C52A-E911-A9B7-000D3A1E6ADC}",
    "FieldValueStatusCode": 192350000,
    "FieldValueName": "Sample Customer Journey",
    "FieldValueStartDateTime": "2019-02-08T11:48:00.000Z",
    "FieldValueEndDateTime": "2019-03-08T11:48:00.000Z",
    "FieldValueWorkflowDefinition": "[{\"ActivityTypeId\":\"bpf_root\",\"ParentBranchId\":0,\"ParentRelationshipType\":\"Default\",\"ActivityId\":\"01\",\"Properties\":{\"Items\":[{\"ItemId\":null,\"ActivityTypeId\":\"bpf_root\",\"Title\":\"Undefined\",\"IsNameSystemDefined\":true,\"Name\":\"New ActivityTypeName_bpf_root_TitleText\",\"ActivityItemId\":0}]}},{\"ActivityTypeId\":\"Segment\",\"ParentActivityId\":\"01\",\"ParentBranchId\":0,\"ParentRelationshipType\":\"Default\",\"ActivityId\":\"01_0\",\"Properties\":{\"Items\":[{\"ItemId\":null,\"ActivityTypeId\":\"Segment\",\"Title\":\"Undefined\",\"IsNameSystemDefined\":true,\"Name\":\"New Segment group\",\"ActivityItemId\":52,\"SegmentMergeMethod\":\"Union\"},{\"ItemId\":\"056bbe66-f025-e911-a9ba-000d3a1e689f\",\"ActivityTypeId\":\"SegmentItem\",\"Title\":\"Undefined\",\"IsNameSystemDefined\":true,\"Name\":\"TC407937_DynamicSegment_bmkX5u\",\"ActivityItemId\":53,\"ContainmentMethod\":\"Inclusion\",\"SegmentSourceType\":\"Segment\",\"DciSegmentName\":\"TC407937_DynamicSegment_bmkX5u\",\"SegmentDisplayName\":\"TC407937_DynamicSegment_bmkX5u\",\"Description\":\"\"}]},\"EntityTarget\":\"contact\"},{\"ActivityTypeId\":\"Email\",\"ParentActivityId\":\"01_0\",\"ParentBranchId\":0,\"ParentRelationshipType\":\"Default\",\"ActivityId\":\"01_0_3\",\"Properties\":{\"Items\":[{\"ItemId\":\"15bd0ab8-c12a-e911-a9b6-000d3a1e6c14\",\"ActivityTypeId\":\"Email\",\"Title\":\"Undefined\",\"IsNameSystemDefined\":true,\"Name\":\"Relationship test\",\"ActivityItemId\":61}]},\"EntityTarget\":\"contact\"}]",
    "FieldValueIsRecurring": true,
    "FieldValueRecurrenceIntervalDays": 30,
    "FieldValueRecurrenceCount": 3,
    "FieldValueRequiredConsent": 587030001,
    "FieldValueContentSettingsId": "{1922B1D8-0523-E911-A9BA-000D3A1E689F}",
    "FieldValueEntityTarget": 0,
    "FieldValueSuppressionSegmentId": "{544A3E20-9B23-E911-A9B6-000D3A1E6C14}",
    "FieldValueCustomerJourneyTimeZone": 92
}

Validate Customer Journey response

{
    "@odata.context": "{{orgUrl}}/api/data/v9.0/$metadata#Microsoft.Dynamics.CRM.msdyncrm_CustomerJourneyValidateResponse",
    "ValidationResult": "{\"ActivityValidationResults\":[{\"ActivityId\":\"\",\"Fault\":\"ErrorRecurringCampaignEndDateDoesNotFitRequestedIterations\",\"Result\":\"Error\",\"ErrorMessageArguments\":[]}],\"Result\":\"Error\"}"
}

Validation result

The following table describes the schema of the ValidationResult object received in the Validate Customer Journey response.

Property Type Description
Result String The overall error check result. It has the following values:
Valid – Records that passed the validation check.
Warning – Records that passed validation check; there are nonblocking issues with it.
Error – Records that did not pass validation; there are blocking issues with it.
ActivityValidationResults Object[] An array of validation detail objects. Each one refers to a specific problem that can apply to the customer journey record, a specific tile within the workflow design. See the Activity validation result schema.

Activity validation result

The following table shows the schema of objects contained within the ActivityValidationResults array of the ValidationResult object.

Property Type Description
ActivityId String The Activity ID of the actual workflow tile to which the validation result applies. If empty, the validation result applies globally to the entire workflow definition or other properties of the customer journey.
Fault String The code that identifies the actual validation result. See the validation sample to learn how to work with messages associated with fault codes.
Result String The result severity. It has the following values:
Valid – Informative entry
Warning – Nonblocking issue
Error – Blocking issue
ErrorMessageArguments String[] Optional list of arguments that provides details of the validation result, for example, an ID of the element that fails to meet the validity criteria.