SFMC Tips #12 : Extracting Contacts Passing Through Wait Activities Using Journey Builder REST API
In the ever-evolving landscape of Salesforce Marketing Cloud, developers often grapple with the challenge of efficiently extracting contact lists from specific journey activities. While Data Views offer a solution for email activities, the elusive task of extracting contacts who traverse wait activities remains a puzzle.
In the pursuit of this extraction, a workaround emerged: the setup of an “Update Contact” activity on the Journey Builder path. This involved crafting a mechanism to accumulate contacts passing through that activity into a data extension.
Yet, this approach came with its own set of challenges. The “Update Contact” activity necessitated advance preparation on the journey path. In cases where an abrupt need for extracting the contact list arose, the process could hit a roadblock, leading to a frustrating experience for users.
To address this conundrum, I unveil a groundbreaking feature introduced in the Summer ’23 release — the “Journey Builder History Download via REST API”. This functionality not only resolves the existing challenges but also ushers in a new era of possibilities.
*Using this REST API, you can download the journey history for the last 30 days in CSV or TSV format. The extraction of this file is limited to not exceed 1 GB. Additionally, a REST API has been concurrently introduced to check whether the extracted content exceeds 1 GB.
Let’s delve into the details of how to leverage this feature to extract contacts who have passed through wait activities.
Setting the Stage
Before embarking on this journey, ensure you have the following essentials from a previous guide: the REST Base URL and the all-important Access Token. If you haven’t obtained them yet, refer to the guide on “How to Execute Basic Setup for Salesforce Marketing Cloud’s REST API using Talend API Tester”.
--- METHOD
POST
--- ENDPOINT
https://[Authentication Base URL].auth.marketingcloudapis.com/v2/token
--- HEADERS
Content-Type：application/json
--- BODY
{
"grant_type": "client_credentials",
"client_id": "[Client Id]",
"client_secret": "[Client Secret]",
"account_id": "[MID]"
}Ensure the following scopes are selected in the API setup:
- AUTOMATION — Journeys — Read
- CONTACTS — List and Subscribers — Read
*Forgetting the CONTACTS — List and Subscribers — Read input may result in all contacts being labeled as “Contact Unknown”.
Obtaining the Wait Activity ID
The first step is to obtain the Activity ID of the wait activity. A handy guide, “Playful Tricks to Snatch Journey Builder Activity IDs Easily”, provides insights into this process.
Making Waves with Talend API Tester
Now, let’s dive into the exciting part — using Talend API Tester to interact with the REST API.
- Launch Talend API Tester and initiate a new request.
- Fill in the necessary details:
--- METHOD
POST
--- ENDPOINT
https://[REST Base URL].rest.marketingcloudapis.com/interaction/v1/interactions/journeyhistory/download?columns=ContactKey
--- HEADERS
Content-Type：application/json
Authorization：Bearer [Access Token]
x-direct-pipe：true
--- BODY
{
"activityIds": ["8bb8d44a-9576-4ec8-9b19-576c56ec1746"],
"statuses": ["complete"]
}- For this example, we’re requesting only the ContactKey.
- If you don’t specify “statuses” in the body, contacts will be duplicated in the extraction. Be sure to specify it.
- Extraction is possible only for the past 30 days of history.
- You can also specify the time range for the extraction.
If no parameters are specified, the following will be automatically retrieved:
- TransactionTime (e.g., 2024–06–13T14:24:26.687Z)
- ContactKey (e.g., BOR501)
- Status (e.g., Complete)
- DefinitionId (e.g., 152018ff-d987–4797-bc1b-9566bb6120d2)
- DefinitionName (e.g., Test_Journey)
- ActivityId (e.g., 8bb8d44a-9576–4ec8–9b19–576c56ec1746)
- ActivityName (e.g., 1 Day)
- ActivityType (e.g., WaitActivity)
If you want to select all extractable items, please copy and paste the following as the parameter. It will replace ContactKey.
ContactKey,ActivityId,ActivityName,ActivityType,ClientStatus,CreatedDate,DefinitionId,DefinitionInstanceId,DefinitionName,EndDate,EntrySource,EpochTimeInMilliseconds,EventId,EventName,Id,Message,OutcomeActivityId,SourceType,StartDate,Status,TransactionTime,Result.Status,Result.Tags,Result.Messages,Result.Outcome
Harvesting the Fruits of Your Efforts
Hit the “Send” button and await the 200 OK response, indicating a successful request.
With the successful response, the stage is set for downloading the CSV file. Simply click the “Download” button in the bottom right corner.
Other than the access token you entered this time, you can reuse the information in Talend API Tester for future use. Please save it as needed.
[additional information] February 8, 2024
If you want to extract only contacts from a specific time period within the extractable 30 days, please modify the body as follows:
*Please note that the time should be specified in UTC. The following body is an example of extracting contacts that arrived during the waiting activity between 8:00 and 18:00 on January 31, 2024, in JST (Japan Standard Time, UTC+9). Please subtract 9 hours for each date when entering the time.
--- BODY
{
"start": "2024-01-30T23:00:00Z",
"end": "2024-01-31T09:00:00Z",
"activityIds": ["f8acd255-19da-4d88-beaf-d2efba9b9279"],
"statuses": ["complete"]
}[additional information] September 30, 2024
The definitionIds represent version IDs, not journey IDs. Below are sample codes to retrieve contacts who have met the goal in a specific version, and to retrieve contacts who have met the exit criteria in a specific version.
--- Sample body to retrieve contacts who have met the goal:
{
"definitionIds": ["a8787c44-d866-4b3a-bf71-f515b9a5c63f"],
"activityTypes": ["goalcriteriaactivity"]
}
--- Sample body to retrieve contacts who have met the exit criteria:
{
"definitionIds": ["86f7c10b-76fa-4f5f-94b5-8afc6d0509af"],
"statuses": ["ExitCriteriaMet"]
}Please also refer to the following article for an easy way to retrieve the version ID.
Conclusion
This article has unveiled the potential of the “Journey Builder History Download via REST API” feature, solving the long-standing challenge of extracting contacts from wait activities. The journey doesn’t end here — stay tuned for future articles exploring additional functionalities and creative use cases. Happy extracting! 🕵️♂️✨
Thank you for reading.
Nobuyuki Watanabe
https://www.linkedin.com/in/nobuyuki-watanabe/ (+Follow me)
