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, you can access and test our APIs—and access and validate various data assets in the Cordial database.

Use Swagger

1. To access Swagger platform, use the appropriate URL. Cordial has two distinct API addresses, so it's important to check which one is associated with your account.

• For accounts located at HTTPS://admin.cordial.io/, the associated API URL is https://api.cordial.io/docs/v2/.
• For accounts located at HTTPS://usw2.admin.cordial.io/, the associated API URL is https://api.usw2.cordial.io/docs/v2/.

2. You will be taken to the Cordial API Swagger page.

3. You need your API key in order to begin using Cordial's APIs.

• Learn how to create an API key from within the Cordial UI here.

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

Example test

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.

Keep in mind that API calls made in Swagger will directly affect your production data.

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

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

2. 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 want to download the exported CSV file in the Cordial UI, we're using destination type aws, which is the default destination type for downloadable contact activity exports.

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

3. Click the Try it out! button when you're ready to execute the call.

4. 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, which is helpful for troubleshooting the cause.

Example response body: success

{
  "jobId": "5ceec74dddb829e04ceb0895"
}

Example response body: error

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

View exported jobs in the UI

Exported Jobs can be viewed in the Jobs Widget within Cordial.

1. Click the Jobs icon at the top of your Cordial Dashboard.

2. Select View All Jobs to access additional job details and download links.