# How can we help? ## Overview You can use the Orchestrations API to trigger [Podium Orchestrations](https://support.cordial.com/hc/en-us/articles/360015822851)—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](https://support.cordial.com/hc/en-us/articles/115005365087) and use it for authorization. - [Learn more about Cordial API authentication here](https://support.cordial.com/hc/en-us/articles/203885498-RESTful-API-summary-and-usage#authentication) ## Methods, parameters, and examples - [GET/v2/orchestrations](https://support.cordial.com/hc/en-us/articles/30496242469517-Orchestrations-API#GET/orchestrations) - [GET/v2/orchestrations/{orchestrationID}](https://support.cordial.com/hc/en-us/articles/30496242469517-Orchestrations-API#GET/orchestrations/{orchestrationID}) - [POST/v2/orchestrations/{orchestrationID}/trigger](https://support.cordial.com/hc/en-us/articles/30496242469517-Orchestrations-API#POST/orchestrations/{orchestrationID}/trigger) ### GET/orchestrations | Method | URL Path | | --- | --- | | GET | /v2/orchestrations | | Retrieves all Podium Orchestrations from the Cordial database. Response data can be filtered using Orchestration `name`, `tags`, and `timestamp` values. | - [Parameters](https://support.cordial.com/hc/en-us/articles/30496242469517-Orchestrations-API#zp-1-0) - [Example request URL](https://support.cordial.com/hc/en-us/articles/30496242469517-Orchestrations-API#zp-1-1) - [Example JSON response](https://support.cordial.com/hc/en-us/articles/30496242469517-Orchestrations-API#zp-1-2) | 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 | URL Path | | --- | --- | | GET | /v2/orchestrations/{orchestrationID} | | - Retrieves a specified Orchestration from the Cordial database.
- The Orchestration record is defined by the unique key value. | - [Parameters](https://support.cordial.com/hc/en-us/articles/30496242469517-Orchestrations-API#zp-2-0) - [Example request URL](https://support.cordial.com/hc/en-us/articles/30496242469517-Orchestrations-API#zp-2-1) - [Example JSON response](https://support.cordial.com/hc/en-us/articles/30496242469517-Orchestrations-API#zp-2-2) | 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 | URL 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. | - [Parameters](https://support.cordial.com/hc/en-us/articles/30496242469517-Orchestrations-API#zp-3-0) - [Example JSON request](https://support.cordial.com/hc/en-us/articles/30496242469517-Orchestrations-API#zp-3-1) - [Example request URL](https://support.cordial.com/hc/en-us/articles/30496242469517-Orchestrations-API#zp-3-2) - [Example JSON response](https://support.cordial.com/hc/en-us/articles/30496242469517-Orchestrations-API#zp-3-3) \* 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 the `contact` 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 a `PodiumForPayload` are merged with `extVars` defined at the root of the request body. | `"extVars": {"orderID":"o1234"}` | ``` {\ "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": []\ } ``` ## Test in Swagger You can [access and test Cordial's APIs in Swagger](https://support.cordial.com/hc/en-us/articles/216197618). ## Error responses You can [find a list of global API error responses here](https://support.cordial.com/hc/en-us/articles/4402427843597).