Firing an Entry Event is great for injecting single contacts into a Salesforce Marketing Cloud journey from external systems or websites – but what if you need to inject contacts to a journey in bulk?

After reading a recent question on Salesforce Stack exchange, I found myself playing with the unofficial REST endpoint /interaction-experimental/v1/batchcontactevents, which is used by the Marketing Cloud Connector managed package in Salesforce to inject contacts in bulk into journeys, for example, if you’re adding a batch of contacts into a Salesforce Campaign used as a journey entry source.

If you would like to see for yourself how this works, you can initiate a Marketing Cloud Connector log from the Marketing Cloud tab in Salesforce and add a few contacts to a running Campaign. The log will register the details of your call along with the REST endpoint and the JSON payload:

	*****2020-11-12 16:51:04.337|HTTP RESPONSE|"6ffc2d53-c97e-4a89-bd66-535cxxxxx"
	*****2020-11-12 17:02:29.36|HTTP CALLOUT|FireJourneyBuilderEvent
	*****2020-11-12 17:02:29.46|HTTP REQUEST|https://mcxxxxx.rest.marketingcloudapis.com/interaction-experimental/v1/batchcontactevents
	{
	"EventDefinitionKey":"SalesforceObjcbd44d55f8f9df29b0f5631xxxxxx",
	"ContactPersonType":"CampaignMember",
	"CallerSystemName":"Salesforce",
	"BatchId":"",
	"RecordCount":2,
	"CalloutTimeStamp":"12/11/2020 17:02",
	"BatchDetails":[
	{
	"ContactKey":"0031t00000XXX8UAAS",
	"Data":{
	"CampaignMember:Id":"00v1t00000XXXOEAA0",
	"CampaignMember:Common:Id":"0031t00000XXX8UAAS",
	"CampaignMember:Common:Email":"zuzanna@sfmarketing.cloud",
	"CampaignMember:Common:HasOptedOutOfEmail":false,
	"MemberRecordType":"Contact"
	}
	},
	{
	"ContactKey":"0031t00000XXXWMAA1",
	"Data":{
	"CampaignMember:Id":"00v1t00000XXXOFAA0",
	"CampaignMember:Common:Id":"0031t00000XXXWMAA1",
	"CampaignMember:Common:Email":"info@ampscript.io",
	"CampaignMember:Common:HasOptedOutOfEmail":true,
	"MemberRecordType":"Contact"
	}
	}
	]
	}
	*****2020-11-12 17:02:29.52|HTTP RESPONSE|"8dfb0fa9-40e2-432c-adfa-a742c6xxxxx"

view raw campaign-journey-payload.json hosted with ❤ by GitHub

Based on above, I have been able to build a payload to use with other journeys that have an API entry event.

DISCLAIMER: As this is an experimantal, undocumented endpoint, you need to use it with caution and on your own responsibility. It’s not supported and could be disabled without a warning.

Authentication

The major downside of using this endpoint that I discovered, is that it requires you to use the “old” v1 access token (24 digit). This means that if you’re on a newer Salesforce Marketing Cloud instance where you haven’t been able to install the legacy package before they were discontinued, you won’t be able to use the /interaction-experimental/v1/batchcontactevents endpoint. If you are on an older instance where you still have an access to a legacy package, follow requestToken Reference for Legacy Packages to obtain an OAuth token.

JSON Parameters

To build your request, make sure you already have a journey with an API Entry Event and the list of associated Data Extension fields. In the JSON payload, you will need to include the API EventDefinitionKey, the number of contacts you are sending and their details: ContactKey is required for every contact included in your payload and any additional Data Extension fields need to be included in the Data object. Below I have included two contacts and two Data Extension fields, email and firstName:

	Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
	POST /interaction-experimental/v1/batchcontactevents
	Content-Type: application/json
	Authorization: Bearer YOUR_V1_ACCESS_TOKEN
	{
	"EventDefinitionKey":"{{API entry event key}}",
	"BatchId":"",
	"RecordCount":2,
	"BatchDetails":[
	{
	"ContactKey":"{{Contact key}}",
	"Data":{
	"email":"{{email address}}",
	"firstName":"{{first name}}"
	}
	},
	{
	"ContactKey":"{{Contact key}}",
	"Data":{
	"email":"{{email address}}",
	"firstName":"{{first name}}"
	}
	}
	]
	}

view raw batchcontactevents.json hosted with ❤ by GitHub

According to this Salesforce Stack Exchange post, above works up to 500 records per batch, which means that you will need to split bigger payloads into batches.

During testing, I noticed that the response is always 201 “Created”, even if the contacts did not go through, so error handling might be tricky. The response itself returns an eventInstanceId.

If you have also been playing with this endpoint and feel that something is worth adding to the above, feel free to reach out!

---

Questions? Comments?

Leave a comment below or email me at zuzanna@sfmarketing.cloud.

---