API starter - multiple contacts (Journeys and Campaign Manager)

This article is about triggering a journey or a campaign in Campaign Manager.

 

Say that you have a large number of contacts gathered in some other system that you want to trigger a journey or a campaign for at the same time. To accomplish this you should use the batchtrigger endpoint of the Symplify REST API.

Note for Journeys: this endpoint is only intended for when you have a number of contacts that should be entered at the same time; this endpoint is not intended for use when entering individual contacts to a Journey. For that purpose, please use the API single request.

 


Prerequisites

The API batch starter requires an input file with JSON rows representing each individual contact to be added to the journey/campaign:

{"id": "0", "properties": {"emailAddress": "the_boss@example.com", "firstname": "Bruce", "attributeName": "yes"}}
{"id": "1", "properties": {"emailAddress": "aretha.f@example.com", "firstname": "Aretha", "attributeName": "yes"}}
{"id": "2", "properties": {"emailAddress": "ladygaga@example.com", "firstname": "Lady", "attributeName": "no"}}

 

NOTE: Each row in the input file needs to be a separate JSON object. Do NOT use a JSON array.

The "id" attribute of each JSON object in the file represents the id of the contact in your system. The "properties" attribute can be used to supply additional data with each contact for use, e.g. in segments or placeholders.

The contact file can be supplied to Symplify in two different ways: Symplify can download the file from a specified URI, or it can be accepted as a PUT to a pre-signed URI received from the Symplify API. You will initiate using a POST to https://<server>.symplify.com/rest/{customerid}/batchtrigger/v2, and the request payload will be different depending on which approach you use.

 

Upload file to Symplify

POST the following payload:

{
"type": "JOURNEY_COMMENCE",
"entityId": <id of the Journey/Campaign to commence>
}

The response payload will specify an URL where to upload the contact file:

{
"uploadUrl": "https://symplify-batchtrigger.cellar-c2.services.clever-cloud.com/uploads/www4/70225847284177e6bbda5780166c781987bcd1b37695bddd8d1f754066d7fa7e94ffdf9bcae267?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20190920T172612Z&X-Amz-SignedHeaders=content-type%3Bhost&X-Amz-Expires=43200&X-Amz-Credential=AKIAJNJRZJQCQ3W66YIQ%2F20190920%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Signature=ba9fed3c4eef3ac6b6eb768f74ac4f287d54207a0f67db12e4e0c24e145230b9",
"status": "WAITING_FOR_UPLOAD"
}

You may now upload the contact file using a PUT to the uploadUrl specified in the response. The batch will start within seconds after the file has been uploaded. Please note:

  • The value of Content-Type header should be text/plain
  • The uploaded file should be UTF-8 encoded.
  • The uploadUrl is valid for 12 hours.

 

Specify a download URL to Symplify

POST the following payload:

{
"type": "JOURNEY_COMMENCE",
"entityId": <Id of the Journey/Campaign to commence>,
"downloadUrl": "https://download.example.com/contacts.txt?signature?abc123"
}

Symplify will immediately download the file and start the batch. Note that the file must be publically available for download. For this reason, it is recommended that it's protected using a secure, time-based signature.

 

Campaign Manager specific

Unlike Journeys, Campaigns are one-time sendouts, meaning you normally can not send the same campaign more than once. However, in Campaign Manager, this is possible if you allow the specific campaign to be triggered more than once (default is one-time execution). This is managed on the starter conditions.

mceclip0.png

Please note that if you trigger an already sent campaign, only new contacts in your file will enter the campaign the second time.

Also, if you have scheduled steps in your campaign where the scheduled date is passed, these steps will get executed immediately (with the standard buffert time of five minutes).

 

Responses

A correct request will provide a 200 response and as long as a campaign is published the import job will be executed (the contacts in your file will get modified according to your request). 

 

409 Conflict "Journey cannot be triggered - status is NO_ACTIVE_VERSION"

The campaign you're trying to send is a draft (not published) or has been stopped.

409 Conflict "Journey cannot be triggered - status is ALREADY_TRIGGERED"

The campaign you're trying to send is already sent and is not allowing to be triggered again.

 

 

Was this article helpful?
0 out of 0 found this helpful