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
Keyremain 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
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]
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
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.
7 thoughts on “Get Journey history by filtering the Definition ID via API”
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
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:
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
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]
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 ?
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.
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:
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?
And keep up the good work!
We also wanted to do this but it is not supported by salesforce. So for any business critical process you are building a bomb ready to detonate. Also the data is only 30 days. And they have set a limit on the amount of rows you can get with no possibility to continue retrieving the next batch
Where to find ID and Key Values..