Overview
Cordial's powerful real-time segmentation and personalization relies on the data you make available in the platform. As a developer, it's your job to get relevant data flowing into the platform to enable your marketing team to build dynamic, personalized messages for your customers.
API first and developer friendly
We built Cordial with the developer in mind. A robust RESTful API is available, giving you access to virtually all of the platform's functionality using industry standard GET, POST, PUT, and DELETE calls. Cordial also provides a suite of JavaScript listeners that can be embedded on your website for a seamless flow of real-time data to your account.
About the data
Cordial uses a document-based and search-based database to store all data in the following set of collections.
| Collection | Description |
|---|---|
| Contact Collection | Stores data specific to a contact including channels, attributes, list membership and cart items. |
| Events (Contact Activities) Collection | Stores event data specific to messages (opens, clicks, etc.) or any custom named event. |
| Product Collection | Stores data from a product catalog. Typically developers will update this collection on a nightly or weekly basis. This data can be used to embellish an email, but is not used for audience search. |
| Orders Collection | Stores order data. This can hold specific order details and can be used for building an audience. |
| Supplements Collection | Stores additional data (store locations, coupon codes, message content, etc.) that doesn’t fit into one of the above collections. |
RESTful API
Cordial's API gives you access to virtually all of the platform's functionality, such as importing and exporting contacts, event, order, product, and message data—as well as sending batch and triggered messages and other job-related activities.
Here some recommended articles to get you started with our API:
In our documentation, API calls are grouped according to the following categories:
- Contact management
- Orders, products, and supplements
- Message creation and delivery
- Operations related
API testing
For testing and documentation needs, we built a custom implementation of Swagger to test all available API calls. Learn about using Swagger to access and test Cordial APIs here.
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/
Before using Cordial APIs, you'll first need to generate an API key.
Embedded JavaScript listeners
To transfer one-way data using a client-side approach, we built JavaScript listeners that can be embedded on your website to identify visitors and pass contact profile data, custom-named events, orders, and cart items to your account.
Our JavaScript listeners also store anonymous data about a site visitor and pass that data to the appropriate collection once the contact is identified.
Recommended data integrations
Your industry and marketing strategy will determine how you collect and store data. We have some suggestions to help you get started.
- Contact attribute data: Contact data is paramount to any marketing strategy and can be passed to Cordial using the following methods:
- Via the API using the POST /contacts and POST /contactimports.
- Via javascript using the cordial.contact() method.
- Contact activity events: Events (also referred to as contact activities) such as cart abandon and browse abandon are essential to triggered messaging strategies. They can be sent to Cordial using these methods:
- Via the API using the POST /contactactivities call.
- Via JS using the cordial.event() method for custom named events.
- Cart items: Cordial stores cart items in the Contact Collection, and they can be used for populating message content in cart abandonment messages. Cart items can be passed two ways:
- Via the API using POST /contacts/{primary_key}/cart or POST /contacts/{primary_key}/cartitems.
- Via JS using cordial.cartitem()
- Order data: You can use order data in the content of a message as well as to build an audience. Order data is used in replenishment campaigns, order surveys, and order confirmation messages—and can be sent two ways.
- Via the API using the POST /orders call.
- Via JS using the cordial.order() method.
When using order data to send confirmation messages, we recommend using the API method.
- Product data: Product data is used in message content and should be updated on a recurring basis to maintain a current catalog. You can do so:
- Via the API using the POST /products and POST /productimports calls.
Product data is also updated in the Product Collection when passed along with order data.
Additional resources
- JSON validator: JSONLint is an awesome tool for checking your JSON for errors when making API calls. Sometimes it's just a misplaced comma that is causing the problem!
- HTML, JS, and JSON beautifier: jsbeautifier.org will beautify your code and make it easier to read.
- DNS lookup: whatsmydns.net/#NS checks the current IP address of your domain name and DNS record information against multiple name servers located in different parts of the world.
- Postman: An alternative to Swagger for testing API calls is Postman.
<%= heading %>
Comments
0 comments
Please sign in to leave a comment.