Get Journey history by filtering the Definition ID via API

In today’s article, we will be going through a non-documented way of getting journey’s history through the API. The majority of this information is available on the UI. However, having a second way of getting this data in raw format can be helpful in some use cases. You can use free software like POSTMAN to interact with Marketing Cloud’s API and follow the steps in this article.

Let’s start by setting the correct scopes in Salesforce Marketing Cloud.

Set scope on Contacts and Journeys

When requesting our access token, we need to provide scopes used by our API calls. Do not forget to enable the Journeys & List and Subscribers scopes on the Installed package. We will be using these two scopes to get our journey’s history. Check out “Introduction to SFMC APIs” article for in-depth information about Installed packages setup and Salesforce Marketing Cloud APIs.

We need to set the scopes on the payload to get our access token: [see code snippet on Github]

Get Journey’s Definition ID

In this step, we will be getting information about a specific journey. The undocumented endpoint “interaction” provides access to a range of data, including the DefinitionID. Before getting into it, let me explain the differences between the three different identifiers of a journey:

  • Id: A unique id of the journey assigned by the journey’s API during its creation
  • Key: A unique id of the journey within the MID. Can be generated by the developer
  • DefinitionId: A unique UUID provided by Salesforce Marketing Cloud. Each version of a journey has a unique DefinitionID while the Id and Key remain the same.

Since the journey’s history is version dependent, we will be using DefinitionID to get history of a specific version.

Let us start by making a call to the below endpoint using name=JOURNEY_NAME as a URL parameter. By default, mostRecentVersionOnly parameter is set to true, therefore, the call will return information of the most recent version of the journey. Use VersionNumber=VERSION_NUMBER and mostRecentVersionOnly=false to get information about a specific version. Note that more parameters are available but not covered in this article since irrelevant: [see code snippet on Github]

The DefinitonID is located in a nested array called items, something like: [see code snippet on Github]

Get Journey’s history by filtering via Definition ID

We are finally there. In this step, we will call the endpoint below: [see code snippet on Github]

The payload should be something like below. Do not forget to set the Content-type as application/json on the call’s parameters: [see code snippet on Github]

You can apply multiple filters by setting different variables in the payload. In this example, we are selecting history data for our journey starting from October 23, 2019 to now. The journey is identified by the DefinitionID in the DefinitionIds array parameter in the payload. Other filters are:

  • Page and PageSize: For results pagination. The page starts from one.
  • Extras: represents a list of additional data to fetch. Available values are all, activities, outcomes and stats.
  • OrderBy: You can order by CreatedDate
  • MostRecentVersionOnly: To get information about the most recent versio of the journey. Accepts a true or false value.

This call will return something like below depending on the payload: [see code snippet on Github]


About the author

Rachid Mamai is a SFMC geek and a Digital Marketing enthusiast living in France. To get in touch with Rachid, visit his LinkedIn.

5 thoughts on “Get Journey history by filtering the Definition ID via API

  1. Ee Chuan Chang

    Hi Rachid,

    Awesome post!

    We’re trying to retrieve journey history data from SFMC so that we can trace our subscribers movement in our data warehouse.

    I’ve tried POST /interaction/v1/interactions/journeyhistory/search and with the payload as per your post and it works.

    However, i am failing to set the filters properly. Could you provide some guidance on the payload for filtering page, pagesize, and orderby?

    This is what i’ve tried

    {

    “definitionIds”: [“xxxx-xx..”],
    “page”:2,
    “pageSize”:50,
    “start”: “2019-10-23T12:29:11.882Z”,
    “end”: null,
    “extras”: “all”,
    “orderby”: “CreatedDate”
    }

    Like

  2. Mamai Rachid

    Hi Ee Chuan Chang, thank you.

    As for the page and pagesize filtering, you need to add them to your endpoint parameters, try something like:

    ../interaction/v1/interactions/journeyhistory/search?Content-Type=application/json&$page=2&$pageSize=10

    That should get it working ..
    Regarding the orderby attribute, it doesn’t seem to work any more, I’ll take some time to investigate it and let you know here in the comments or directly in the article.

    Have a good day
    Regards
    Rachid

    Like

  3. Harry

    Hi Rachid,

    Nice post.

    I have tried with the payload which you’ve mentioned in the post with definitionIds. It worked. The same way I have given for activityTypes. I got the filtered output for given activityTypes.
    When I tried to do the same for activityNames . I am not getting the filtered output.
    This is my code:[Adding this in the payload]
    {
    “activityNames”: [“Other”]
    }
    Also,, how to apply [not equal] to condition here? If I don’t want any records with particular activityName. Is there any way to filter them out ?

    Thanks,
    Harry

    Like

  4. Mamai Rachid

    Hi Harry,

    I don’t believe you can apply a filter on ActivityNames. Even on the UI on Journey Builder History, you can see that there is no way to achieve that. I’ve tried it different ways, and still not working.

    For the not equal condition, you can check out the answers to this question on Stackoverflow: https://stackoverflow.com/questions/4614255/rest-url-design-for-greater-than-less-than-operations.

    Still, id doesn’t seem to work on the payload or even on the endpoint’s parameters.

    Regards
    Rachid

    Like

  5. Ran

    Hi Rachid,

    Brilliant post!

    Do you know if this method is robust enough to pull-out all historical data for a journey?
    In other words, are there any limitations as to date range / number of results?

    Before reading this, I was going to go with a SOAP API call for Tracking Data Extract as described here:

    https://developer.salesforce.com/docs/atlas.en-us.noversion.mc-apis.meta/mc-apis/creating_a_data_extract_activity_with_the_soap_web_service_api.htm

    But as to my understanding, limitation is 30-days period for each Tracking Data Extract.

    How would the two compare?
    What would be your preferred method if you had to pull out 4-5 years history for a journey to export it to Salesforce CRM?

    Thanks,
    And keep up the good work!

    Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s