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.

• Learn more about Cordial API authentication here

Methods, parameters, and examples

• GET/v2/orchestrations
• GET/v2/orchestrations/{orchestrationID}
• POST/v2/orchestrations/{orchestrationID}/trigger

GET/orchestrations

• 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}

• 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

• * 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.

Error responses

You can find a list of global API error responses here.