Overview
You can use the Orchestrations API to trigger Podium Orchestrations—and to send and receive all information contained in one or multiple Orchestrations.
API set name: orchestrations
Authentication
Cordial's core APIs use HTTP Basic Authentication (BA). From within the Cordial platform, you can generate an encoded API key for your account and use it for authorization.
Methods, parameters, and examples
- GET/v2/orchestrations
- GET/v2/orchestrations/{orchestrationID}
- POST/v2/orchestrations/{orchestrationID}/trigger
GET/orchestrations
Method | URI Path |
---|---|
GET | v2/orchestrations |
Retrieves all Podium Orchestrations from the Cordial database. Response data can be filtered using Orchestration name , tags , and timestamp values. |
-
Parameter Type Description Example _id
string The unique Podium Orchestration ID. Available in the UI by navigating to Automations > Podium Orchestrations > Trigger > An API Sending Method. "5abcd555abcd555abcd555"
name
string Name of the Podium Orchestration. "Welcome Series"
tags
string Tags attached to the Orchestration. Returns Orchestrations that contain the specified message tags. Multiple tags are comma separated. [welcome, promo, series]
status
boolean 0 = the Orchestration has not been enabled to send, 1 = the Orchestration is enabled to send. 1
lm
string Last modified date for the Orchestration. "2024-12-10T21:48:46+0000"
ct
string Creation date for the Orchestration. "2024-07-23 22:06:32"
composition
object Draft status of the Orchestration. If it's published, the request will return the Orchestration ID, last publication date, and other identifying information. See example JSON response. -
The following URL will retrieve all Orchestration records in an account.
https://api.cordial.io/v2/orchestrations
-
[ { "_id": "5abcd555abcd555abcd555", "name": "Welcome Series", "tags": [welcome, promo, series], "status": 1, "lm": "2024-12-10T21:48:46+0000", "ct": "2024-07-23 22:06:32", "composition": { "draft": "5abcd555abcd555abcd555", "current": "", "published": [ { "id": "5abcd555abcd555abcd555", "pubDate": { "sec": 1532384020, "usec": 967000 } }, { "id": "5abcd555abcd555abcd555", "pubDate": { "sec": 1532387114, "usec": 40000 } } ], "lastPubDate": { "sec": 1532387114, "usec": 40000 } } }, { "_id": "5abcd555abcd555abcd555", "name": "Order Confirmation", "tags": [ "array" ], "status": 0, "lm": "2024-10-09T20:20:11+0000", "ct": "2019-08-29 17:41:28", "composition": { "draft": "5d680e48130fbb0d0a0c9a42", "current": "", "published": [], "lastPubDate": "" } } ]
GET/orchestrations/{orchestrationID}
Method | URI Path |
---|---|
GET | v2/orchestrations/{orchestrationID} |
|
-
Parameter Type Description Example orchestrationID
string The unique Orchestration ID. Available in the UI by navigating to Automations > Podium Orchestrations > Trigger > An API Sending Method. "5abcd555abcd555abcd555"
-
The following URL will retrieve an Orchestration where the
_id
value is"5abcd555abcd555abcd555"
and include all fields.https://api.cordial.io/v2/orchestrations/5abcd555abcd555abcd55
-
[ { "_id": "5abcd555abcd555abcd555", "name": "Welcome Series", "tags": ["welcome", "promo", "series"], "status": 1, "lm": "2024-12-10T21:48:46+0000", "ct": "2024-07-23 22:06:32", "composition": { "draft": "5abcd555abcd555abcd555", "current": "", "published": [ { "id": "5abcd555abcd555abcd555", "pubDate": { "sec": 1532384020, "usec": 967000 } }, { "id": "5abcd555abcd555abcd555", "pubDate": { "sec": 1532387114, "usec": 40000 } } ], "lastPubDate": { "sec": 1532387114, "usec": 40000 } } } ]
POST/orchestrations/{orchestrationID}/trigger
Method | URI Path |
---|---|
POST | v2/orchestrations/{orchestrationID}/trigger |
Triggers an existing Orchestration. The orchestration can be triggered for one or more contacts, as specified within the JSON body. |
-
*Required
Parameter Type Description Example orchestrationID
string The unique Orchestration ID. Available in the UI by navigating to Automations > Podium Orchestrations > Trigger > An API Sending Method. "5abcd555abcd555abcd555"
* for
array The contacts who will receive the messages in the Orchestration and any data associated with them. "smithers@example.com"
identifyBy
string Specifies which identifier key in the request body should be used to look up the contact (e.g. cID
,email
,custID
). Because contact attribute data sent in thecontact
object of the call will upsert corresponding contact attributes in Cordial,identifyBy
should be used to specify which key serves as the contact identifier and should not be upserted."email"
extVars
string Using the extVars
object, any number of external variables may be added. These values are then made available for all initial actions in the Orchestration. For example, if"extVars": {"orderID":"o1234"}
is included in the request body, then within the message it can be accessed as{$extVars.triggerData.orderID}
.extVars
defined within aPodiumForPayload
are merged withextVars
defined at the root of the request body."extVars": {"orderID":"o1234"}
-
[ { "for": [ { "contact": { "email": "smithers@example.com" }, "extVars": { "key": "string" } } ], "identifyBy": "email", "extVars": { "key": "string" } }, { "for": [ { "contact": { "email": "homer.simpson@example.com" }, "extVars": { "firstName": "Homer", "lastName": "Simpson" } }, { "contact": { "email": "marge.simpson@example.com" }, "extVars": { "firstName": "Marge", "lastName": "Simpson" } } ], "identifyBy": "email" } ]
-
The following URL in conjunction with the JSON will trigger the Orchestration.
https://api.cordial.io/v2/orchestrations/5abcd555abcd555abcd555/trigger
- The following is an example response when the POST request is successful.
{ "success": true, "message": "Orchestration API trigger successfully processed", "triggered": [ { "triggered": true, "contact": { "email": "smithers@example.com" } }, { "triggered": true, "contact": { "email": "homer.simpson@example.com" } }, { "triggered": true, "contact": { "email": "marge.simpson@example.com" } } ], "failures": [] }
Comments
0 comments
Please sign in to leave a comment.