Use the Create Journey From Template API

The Create Journey From Template API lets you create customer journeys from predefined templates in Dynamics 365 Customer Insights - Journeys. Use this API to quickly set up journeys, make changes, and keep validation and business logic in place.

API overview

Authentication and prerequisites

• You need the prvCreatemsdynmkt_journey privilege.
• You need access to journey templates in the organization.
• You need appropriate business unit permissions if you specify msdynmkt_owningbusinessunitid.

Request parameters

Required parameters

Optional parameters

Response properties

Usage examples

Basic journey creation

POST [Organization URI]/api/data/v9.2/msdynmkt_CreateJourneyFromTemplate
Content-Type: application/json

{
    "msdynmkt_journeytemplateid": "12345678-1234-1234-1234-123456789012",
    "msdynmkt_journeyname": "Welcome Campaign Q1 2024",
    "msdynmkt_journeystarttime": "2025-09-15T09:00:00Z", // UTC time
    "msdynmkt_journeyendtime": "2025-10-23T12:30:00.000+02:00" // Time zone specified
}

Response

{
    "msdynmkt_journeyid": "87654321-4321-4321-4321-210987654321",
    "msdynmkt_isvalid": true,
    "msdynmkt_errors": "[]"
}

Advanced journey creation with modifications

POST [Organization URI]/api/data/v9.2/msdynmkt_CreateJourneyFromTemplate
Content-Type: application/json

{
    "msdynmkt_journeytemplateid": "12345678-1234-1234-1234-123456789012",
    "msdynmkt_journeyname": "Personalized Welcome Series",
    "msdynmkt_jsonpathmodifications": "{
        \"$.actions['6b461239-d698-449d-9196-0e365753798e'].parameters.contentId\":\"e7e3cf6c-1d89-f011-b4cc-000d3a306706\",
        \"$.actions['b03bff11-1b09-4566-967b-4cc77270c0f6'].parameters.smsId\":\"6fcbe68f-ef8e-f011-b4cb-000d3a5972e9\",
        \"$.actions['d444ab08-1a65-4a94-b9e2-78499bc9faeb'].parameters.pushNotificationId\":\"7f030313-f08e-f011-b4cb-000d3a5972e9\",
        \"$.trigger.exclusionSegments\":\"['009b7a68-9a59-4ac7-8f85-2bf0f21dfd84','08c46b79-b1b5-4b91-b909-3048d82a0c2f']\",
        \"$.trigger.parameters.condition.rightOperand.value\":\"{\\\"logicalName\\\":\\\"msevtmgt_event\\\",\\\"id\\\":\\\"d13019d9-8554-4ba8-bda9-fb52734dff93\\\"}\"
        }",
    "msdynmkt_journeystarttime": "2025-09-15T09:00:00Z",
    "msdynmkt_journeyendtime": "2025-12-31T23:59:59+02:00",
    "msdynmkt_createmode": "Draft",
    "msdynmkt_owningbusinessunitid": "11111111-2222-3333-4444-555555555555"
}

JSONPath modifications

The msdynmkt_jsonpathmodifications parameter is a serialized key value collection where:

• Keys are JSONPath expressions that target specific elements in the journey template. See RFC for a JSONPath definition.
• Values are the replacement values for those elements. Make sure that values are properly escaped, if needed.

JSONPath examples

JSONPath modification example (before serialization)

{
    "$.trigger.audience": "98765432-1234-5678-9012-123456789012",
    "$.actions['6b461239-d698-449d-9196-0e365753798e'].parameters.contentId": "e7e3cf6c-1d89-f011-b4cc-000d3a306706"
}

Create modes

Draft mode (default)

• The journey is created in a draft state.
• You can edit and change the journey before activation.
• You need to publish the journey manually through the user interface or a separate API call (msdynmkt_PublishJourneyV2).
• Some validation errors are ignored (for example, the message template for email, SMS, or push doesn't need to be in published state).

Publish mode

• The journey is created and published right away.
• All validation must pass for the journey to be created.
• The journey starts according to the defined schedule.
• If there are any validation errors, the journey isn't created.

Error codes

When msdynmkt_isvalid returns false, the msdynmkt_errors field has a JSON array of error objects. Each error includes an ErrorCode and ErrorMessage.

JSON and template errors

Data source and binding validation errors

System and configuration errors

Journey definition errors

Time and scheduling errors

Business unit and permissions errors

Segment and audience errors

Message and content errors

Event and trigger errors

General errors

Error response example

{
    "msdynmkt_journeyid": "87654321-4321-4321-4321-210987654321",
    "msdynmkt_isvalid": false,
    "msdynmkt_errors": "[{\"ErrorCode\":\"NonExistingSegment\",\"ErrorMessage\":\"Segment with ID: 12345678-1234-1234-1234-123456789012 does not exist.\"},{\"ErrorCode\":\"InvalidStartTime\",\"ErrorMessage\":\"Journey start time cannot be in the past.\"}]"
}

Internal properties

The journey JSON contains many internal properties, which are populated automatically based on the provided data. You don't need to modify the following properties:

• The placeholderbindings and placeholderBindingsOriginal objects are populated automatically based on the selected message template.
• messageDesignation, complianceSettingsId, purposeId, and topicId are populated based on the selected message template.
• The persistedUIState object is populated based on the selected message template.
• $.name is automatically set from input parameter msdynmkt_journeyname.
• $.trigger.parameters.startTime is automatically set from input parameter msdynmkt_journeystarttime.
• $.trigger.parameters.endTime is automatically set from input parameter msdynmkt_journeyendtime.

Best practices

Template management

1. Template validation: Check that journey templates are valid and accessible before using them.
2. Template testing: Test templates in a development environment before using them in production.

JSONPath modifications

1. Path validation: Test JSONPath expressions against the template structure.
2. Value compatibility: Make sure modification values match the expected data types.
3. Escaping: Escape special characters in JSON strings.
4. Case sensitivity: JSON path keys are case sensitive.

Error handling

1. Validation check: Always check msdynmkt_isvalid before you continue.
2. Error parsing: Parse the msdynmkt_errors JSON array for detailed error information. Items in the array are objects with ErrorMessage and ErrorCode properties.
3. Retry logic: Add retry logic for transient errors.

Limitations

• Journey templates must be accessible to the calling user.
• The API follows all standard Dynamics 365 security and business rules.
• If the API is executed inside the plugin, it isn't executed as part of the current Dataverse transaction. For example, entities created during the plugin execution aren't visible to the msdynmkt_CreateJourneyFromTemplate API.
• It's not possible to remove elements from the journey.

Related APIs

• Create Journey JSON From Template (msdynmkt_CreateJourneyJsonFromTemplate): Create the journey JSON without persisting.
• Validate journey JSON (msdynmkt_ValidateJourneyJson): Validate the journey JSON without creating a journey entity.
• Publish journey: (msdynmkt_PublishJourneyV2): Publish the existing journey.

SDK examples

C# example using the Dynamics 365 SDK

using Microsoft.Xrm.Sdk;
using Microsoft.Xrm.Sdk.Messages;
using System;
using System.Collections.Generic;

public void CreateJourneyFromTemplate(IOrganizationService service)
{
    var request = new OrganizationRequest("msdynmkt_CreateJourneyFromTemplate");

    var jsonPathModifications = new Dictionary<string, string>();
    jsonPathModifications.Add("$.actions['0395747d-7cd7-43dc-8228-303f54ecb32b'].parameters.contentId", "703f7dc8-149a-f011-bbd3-00224806bf98"); // Email
    jsonPathModifications.Add("$.actions['93952de9-e3a6-4160-ba02-3979231bea13'].parameters.smsId", "10c0e594-159a-f011-bbd3-00224806bf98"); // SMS
    jsonPathModifications.Add("$.actions['e0c3dda2-78c2-4d49-b7c3-ec33f12346c1'].parameters.pushNotificationId", "a9e38845-169a-f011-bbd3-00224806bf98"); // Push

    // Delay tile
    jsonPathModifications.Add("$.actions['8c647164-4a2f-4601-ab7b-6a40365b672c'].parameters.count", "2"); // Wait 2 units
    jsonPathModifications.Add("$.actions['8c647164-4a2f-4601-ab7b-6a40365b672c'].parameters.unit", "3"); // Unit is 3 == days

    jsonPathModifications.Add("$.actions['7277ee5b-9824-44b3-b79a-6bf92e4e8f60'].parameters.waitUntil", "2025-11-17T13:50:00.000Z");

    var serializerJsonPaths = System.Text.Json.JsonSerializer.Serialize(jsonPathModifications);
    
    request["msdynmkt_journeytemplateid"] = new Guid("12345678-1234-1234-1234-123456789012");
    request["msdynmkt_journeyname"] = "API Created Journey";
    request["msdynmkt_jsonpathmodifications"] = serializerJsonPaths;
    request["msdynmkt_journeystarttime"] = DateTime.UtcNow.AddDays(1);
    request["msdynmkt_createmode"] = "Draft";
    
    try
    {
        var response = service.Execute(request);
        
        var journeyId = (Guid)response["msdynmkt_journeyid"];
        var isValid = (bool)response["msdynmkt_isvalid"];
        var errors = (string)response["msdynmkt_errors"];
        
        if (isValid)
        {
            Console.WriteLine($"Journey created successfully with ID: {journeyId}");
        }
        else
        {
            Console.WriteLine($"Journey created but has validation errors: {errors}");
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Error creating journey: {ex.Message}");
    }
}

PowerShell example using Microsoft.Xrm.Data.PowerShell

# Connect to Dynamics 365
$conn = Get-CrmConnection -ConnectionString "<YourConnectionString>"

# Prepare request parameters
$parameters = @{
    "msdynmkt_journeytemplateid" = [guid]"12345678-1234-1234-1234-123456789012"
    "msdynmkt_journeyname" = "PowerShell Created Journey"
    "msdynmkt_createmode" = "Draft"
}

try {
        # Run the custom API
    $response = Invoke-CrmAction -conn $conn -ActionName "msdynmkt_CreateJourneyFromTemplate" -Parameters $parameters
    
    $journeyId = $response["msdynmkt_journeyid"]
    $isValid = $response["msdynmkt_isvalid"]
    $errors = $response["msdynmkt_errors"]
    
    if ($isValid) {
        Write-Host "Journey created successfully with ID: $journeyId"
    } else {
        Write-Host "Journey created but has validation errors: $errors"
    }
}
catch {
    Write-Error "Error creating journey: $($_.Exception.Message)"
}

Troubleshooting

Common issues

1. Permission denied

   • Check that the user has the prvCreatemsdynmkt_journey privilege.
   • Check business unit access permissions.

2. Template not found

   • Check that the template ID is correct and exists.
   • Check that the template is accessible to the current user.
   • Check that the template isn't being created inside a Dataverse transaction calling msdynmkt_CreateJourneyFromTemplate.

3. Invalid JSONPath modifications

   • Check JSON syntax.
   • Test JSONPath expressions with the template structure.
   • Check that special characters are escaped properly.

4. Validation failures

   • Check all referenced segments, messages, and events.
   • Check that all dependencies are in the correct state.
   • Check that the journey definition is complete.

For more support, see the Customer Insights - Journeys documentation or contact Microsoft Support.