Overview

In conjunction with the Cordial UI, the Cordial platform provides a robust set of RESTful APIs (Application Program Interfaces). Using these APIs, developers can programmatically perform many of the same functions available from within the UI such as adding, updating, and removing contacts, creating lists, sending messages, retrieving message activity data, and a variety of other actions. Cordial also provides non-UI related APIs to support general integrations and open-application development.

Cordial embraces the developer community and understands the need for having highly scalable industry standard APIs for building transactional messaging applications and for maintaining and managing the bi-directional flow of large amounts of structured and unstructured data. With Cordial, you can harness the power and innovations of the platform entirely via APIs or through some combination of APIs and UI interactions.

The purpose of this document is to help application designers and developers understand the underlying design of Cordial's data structures and definitions and how best to accomplish common objectives using the API resources. This document augments the interactive documentation as a companion resource.

Target audience and assumptions

This document is meant for application designers and developers who want to understand the general capabilities of Cordial's API resources. It does require the reader to have some basic working knowledge of web and API technologies to fully comprehend. However, some portions may still be helpful to those less technical that look to obtain a general overview of Cordial's API capabilities and best practices.

This document does not address the specific details of using each API in your application, but it does provide some code samples that may be helpful. It assumes that the developer already understands coding principles regarding security, encoding and decoding JSON, looping through record sets, error processing and recovery, and general programming standards.

Data structure and organization

Cordial's data structures are built using MongoDB. MongoDB is a document-based database that provides high performance, high availability, and high scalability. Cordial is designed to handle large amounts of data generated over long periods of time. Contact profile data, contact activity data, purchase data, product catalog data, device generated IoT (Internet of Things) data, and publishing data are examples of structured and unstructured data that Cordial can elegantly represent, index, store, retrieve, and operate over.

In Cordial, the data structures are referred to as collections. Collections exist independent of each other; but through keys or other field associations, they may be logically associated to form a full picture of some current state. For example, a contact in the database is defined by an email address that exists in the collection of contacts. Attributes that are used to extend a contact's data structure are independently defined and live in a collection of attributes. Once attributes are created, they are available to extend the data schema of a given contact by including an array of attribute value pairs using a JSON structure.

Another example of how collections work together is in the association of message activity data back to a contact. Message activity data exists in its own collection. As activity data is generated by a contact, it is stored in the message activity data collection with a contact ID (cID) value. The cID value then serves as the key or link to associate that activity to its respective owner.  

As we go through describing each collection, you will see the various associations emerge as well as the sequence with which we construct data and reference it using the APIs.