Using Swagger to Access and Test Cordial APIs

Overview

Cordial provides a robust set of REST based APIs for managing data, contact records, messages and other facets of the Cordial platform. Using Swagger, it is possible to access and test your APIs as well as access and validate various data assets in your Cordial database.

Access Swagger

To access the Swagger platform, use the appropriate URL:

https://api.cordial.io/docs/v2/ or https://api.usw2.cordial.io/docs/v2/

You will be taken to the Cordial API Swagger page:

Before proceeding, you will need your API key in order to begin using Cordial APIs. Learn how to create an API key from within the Cordial platform.

Once you have your API key, return to the Cordial API Swagger page and paste it into the API Key field at the top left of the page. Click the Auth button to validate the key. There will be no visual feedback on the initial authentication. This is the expected behavior and you should proceed to test available API methods.

If the initial authentication did not succeed for some reason, you will be prompted for a Username and Password upon attempting to execute an API call. If this occurs, ensure you have the correct API key, paste it into the Username field, and leave the password field blank. Click Log In to validate the key once again. If your key is accepted, the authentication prompt will not return.

Test Cordial APIs

After successful API authentication, you can begin testing API calls by clicking available API categories to reveal available methods for each.

In the following example, we will export contact activity as a CSV file which, once exported, can be downloaded directly from the Jobs Widget page in Cordial.

The Contact Activity Export (API) article provides a comprehensive look at additional export parameters and JSON request examples.

Expand the contact activity exports category to reveal available API methods for exporting contact activity. Select the /v2/contactactivityexport method to access the corresponding UI.

• Body - Use standardized JSON format in the body section to provide desired contact activity export parameters. Learn more about RESTful API and JSON usage.
• Model - Reveals JSON key names for the selected API method, acceptable value format, and whether the value is required or optional.
• Model Schama - Clicking on the provided JSON Model Schema will copy its contents into the body, giving you a convenient starting point.

When used in the body section, the following JSON snippet will export contact activity filtered by contacts who opted out, and are in the previously created audience rule of "3-Day-engaged". Since we wish to download the exported CSV file via the Cordial UI, we are using destination type "aws" (default destination type for downloadable contact activity exports).

Click Try it out! button when you are ready to execute the call.

{
  "name": "OptedOutActivity",
  "exportType": "csv",
  "destination": {
    "type": "aws"
  },
  "showHeader": true,
  "selected_audience_key": "3-Day-engaged",
  "selected_action_name": "optout",
  "compress": false
}

Check the Response Body section in Swagger below the Try it out! button for confirmation that the call was successful. If unsuccessful, the Response Body will return an error message, helpful for troubleshooting the cause.

Example Response Body - Success:

{
  "jobId": "5ceec74dddb829e04ceb0895"
}

Example Response Body - Error:

{
  "error": true,
  "message": "The selected export type is invalid."
}

Exported jobs can be viewed in the Jobs Widget and by clicking View all jobs to access additional job details and download links.