Orchestrations API – Cordial Knowledge Base

How can we help?

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/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.
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.
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.

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