Asynchronous API – Cordial Knowledge Base

How can we help?

Overview

Cordial's Asynchronous API offers system-to-system methods for sending event, contact, orders, and supplement data. This allows you to stream data from third parties into Cordial, send multiple API requests at the same time, and have more precise control over how Cordial interacts with other systems.

When to use
We recommend using our Asynchronous API whenever possible—unless a synchronous response is required. Use our Scriptable API if custom authentication or transformations are required.

Synchronous v. Asynchronous API process

Synchronous API process: a request comes in to Cordial, data from the request is written to the database, and the response is returned to the sender.

Asynchronous API process: a request comes in to Cordial, a response is returned to the sender, then the request is queued to be processed to our database as soon as possible. For Asynchronous API calls, there's no need to wait for record-level processing because that processing is queued asynchronously from the API exchange.

Keep in mind that managing Asynchronous APIs can be complex and has multiple differences from managing REST APIs. Contact your CSM for guidance.

Access and test Asynchronous API

You can use Swagger to access and test our Asynchronous API offerings. In order to do so, you'll need an API key.

Visit this article to learn how to create an API key from within Cordial.

Access by region

usw1: https://integrations-ingest-svc.cordial.com/api
usw2: https://integrations-ingest-svc.usw2.cordial.com/api
use1: https://integrations-ingest-svc.use1.cordial.com/api

Authentication

The Asynchronous API uses an x-api-key header for authentication. The value is your Cordial API key.

Allowed identifiers

The Asynchronous API accepts these identifiers:

_id for contact ID
email for email address
channels.sms.address for mobile phone number
custom_id correlates to any primary or secondary keys set up in your account

Supported actions

The payload for each endpoint listed here is an array of individual items with the array size ranging from 1 to 100. Keep the array size within that range to ensure success.

POST/upsertContact

Method	Example URL path
POST	https://integrations-ingest-svc.cordial.com/api/upsertContact
Support for contact merge strategies on unique key conflicts.

* Required

Parameters	Type	Description	Example
source	string	Data source	api.example.com
*identifiers	object	Contains contact key-value pairs. Schema: - customID - email - channels.sms.address	See example request.
identifiersPriority	array	The order in which identifiers are used when searching for a contact.	[ 'customId', 'email', 'sms' ]
attributes	object	Attributes to update. Schema: - channel and subscribe status - array - number - location.postal.code - email - customId - LISTNAME	See example request.
forceSubscribe	boolean	forceSubscribe should be passed as true if subscribeStatus is changed from unsubscribed to subscribed.	true, false
mergeOptions	boolean	Optional. Controls if contacts merge is enabled. - mergeAllowed: Boolean. Determines if contacts merge is allowed for this upsert. - mergeableSecondaryKeys: String. Defines which secondary keys conflicts do not prevent the merge.	See example request.

{
    "source": "api.example.com",
    "identifiers": {
        "customId": "test-user",
        "email": "test@example.com",
        "channels.sms.address": "+1234567890"
    },
    "identifiersPriority": [\
        "customId",\
        "email",\
        "sms"\
    ],
    "attributes": {
        "channels.email.subscribeStatus": "subscribed",
        "array": [1, 2, 3],
        "number": 2,
        "location.postal_code": "92613",
        "email": "new@example.com",
        "customId": "test-user",
        "LISTNAME": false
    },
    "forceSubscribe": true,
    "mergeOptions": {
        "mergeAllowed": true,
        "mergeableSecondaryKeys": [\
            "email"\
        ]
    }
}

The contact field defines a contact to be upserted.

POST/upsertContact/batch

Batch requests are supported using POST/api/upsertContact/batch.

POST/createContactactivities

Method	Example URL path
POST	https://integrations-ingest-svc.cordial.com/api/createContactactivities
Creates or updates contacts in real time.

* Required

Parameters	Type	Description	Example
source	string	Data source	api.example.com
*contact	object	Identifies a contact for whom to record a contact activity. Schema: - identifiers: object - identifiersPriority: object - attributes: Object. The attributes to be set if a contact does not exist and should be created. Ignored otherwise. - forceSubscribe: boolean - mergeOptions: boolean - canBeCreated: Boolean. Optional and false by default. Defines if a contact should be created if it’s not present. - canBeUpdated: Boolean. Optional and false by default. Defines if a contact should be updated if it’s already present.	See example request.
*contactActivities	array	Specifies events triggered by contact. Schema: - name - time - properties: array - geo: array - device: array	See example request.

{
    "source": "api.example.com",
    "contact": {
        "identifiers": {
            "customId": "test-user",
            "email": "test@example.com",
            "channels.sms.address": "+1234567890"
        },
        "identifiersPriority": [\
            "customId",\
            "email",\
            "sms"\
        ],
        "attributes": {
            "required_attribute": "my-cool-attr"
        },
        "forceSubscribe": false,
        "mergeOptions": {
            "mergeAllowed": true,
            "mergeableSecondaryKeys": [\
                "email"\
            ]
        },
        "canBeCreated": true,
        "canBeUpdated": false
    },
    "contactActivities": [\
        {\
            "name": "pageView",\
            "time": "2023-02-01T14:29:03+00:00",\
            "properties": {\
                "first": "test",\
                "number": 2,\
                "url": "/academy/"\
            },\
            "geo": {\
                "city": "San Francisco",\
                "country": "United States",\
                "geoLoc": {\
                    "lat": 40.2964197,\
                    "lon": -76.9411617\
                }\
            },\
            "device": {\
                "type": "mobile",\
                "device": "iPhone7,2",\
                "platform": "iPhone OS",\
                "browser": "Safari",\
                "ip": "8.8.8.8",\
                "robot": false\
            }\
        }\
    ]
}

POST/createContactactivities/batch

Batch requests are supported using POST/api/createContactactivities/batch.

POST/addContactsToList

Method	Example URL path
POST	https://integrations-ingest-svc.cordial.com/api/addContactsToList
Creates a new list in real time.

* Required

Parameters	Type	Description	Example
source	string	Data source	api.example.com
*contact	object	Identifies contacts to add to list. Schema: - identifiers: object - identifiersPriority: object	See example request.
*listName	string	List to which contacts will be added.	See example request.
isAllowedToCreateLists	boolean	Determines if list creation on the fly is allowed. Optional and set to true by default.	true, false

{
    "source": "api.example.com",
    "contacts": {
        "identifiers": [\
            {\
                "custom_id": "test-user",\
                "email": "test@example.com"\
            },\
            {\
                "email": "another@example.com"\
            }\
        ],
        "identifiersPriority": [\
            "custom_id",\
            "email"\
        ]
    },
    "listName": "MyList",
    "isAllowedToCreateLists": true
}

POST/addContactsToList/batch

Batch requests are supported using POST/api/addContactsToList/batch.

POST/removeContactsFromList

Method	Example URL path
POST	https://integrations-ingest-svc.cordial.com/api/removeContactsFromList
Removes contacts from a list in real time.

* Required

Parameters	Type	Description	Example
source	string	Data source	api.example.com
*contacts	object	Identifies contacts to remove from list. Schema: - identifiers: object - identifiersPriority: object	See example request.
*listIdentifier	string	Value by which the list will be identified, searching list name by default. May be overridden using listIdentifierKey property.	See example request.
listIdentifierKey	number	Secret key for destination API. Schema: - name of list - destination ID	See example request.

POST/removeContactsFromList/batch

Batch requests are supported using POST/api/removeContactsFromList/batch.

POST/upsertOrder

Method	Example URL path
POST	https://integrations-ingest-svc.cordial.com/api/addContactsToList
Removes order items from cart when needed, such as when an order is completed.

* Required

Parameters	Type	Description	Example
source	string	Data source	api.example.com
*contact	object	Identifies contact making purchase. Schema: - identifiers: object - identifiersPriority: object	See example request.
*orderID	string	Unique ID for the order.	See example request.
*purchaseDate	string	Date of purchase.	See example request.
*status	string	Order status.	See example request.
totalAmount	number	Total price of purchase.	See example request.
tax	number	Sales tax applied to purchase.	See example request.
properties	array	Additional details of product(s) purchased.	See example request.
shouldRemoveItemsFromCart	boolean	Removes purchased items from cart. Optional and true by default.	true
*items	array	Items pulled from orders collection. Required: productID, sku, name Optional:* manufacturerName, category, itemPrice, qty, url, images, properties, attributes	See example request.

{
    "source": "api.example.com",
    "contact": {
        "identifiers": {
            "segment_id": "test-user",
            "email": "test@example.com"
        },
        "identifiersPriority": [\
            "segment_id",\
            "email"\
        ]
    },
    "orderID": "test-order-id",
    "purchaseDate": "2022-04-29T09:00:23+00:00",
    "status": "Order Completed",
    "totalAmount": 623.32,
    "tax": 42.76,
    "properties": {
        "affiliation": "Google"
    },
    "removeItemsFromCart": true,
    "items": [\
        {\
            "productID": "test-product-id",\
            "sku": "test-sku",\
            "name": "test-product-name",\
            "category": "test-category",\
            "manufacturerName": "test-brand",\
            "itemPrice": 23.54,\
            "qty": 2,\
            "url": "https://example.com/product",\
            "images": [\
                "https://cdn.example.com/product.jpg"\
            ],\
            "properties": {\
                "variant": "black",\
                "size": "xs"\
            },\
            "attr": []\
        }\
    ]
}

POST/upsertOrder/batch

Batch requests are supported using POST/api/upsertOrder/batch.

POST/upsertSupplementRecords

Method	Example URL path
POST	https://integrations-ingest-svc.cordial.com/api/upsertSupplementRecords
Skips updates if the existing record has a more recent update date than the one coming from the request.

* Required

Parameters	Type	Description	Example
source	string	Data source	api.example.com
*contact	object	Identifies contact. Schema: - identifiers: object - identifiersPriority: object	See example request.
*supplement	string	Supplement name.	See example request.
updatedDateField	string	Supplement field name for updated date. Allows you to skip updates with older records.	See example request.
*records	array	Supplemental data about contact and order. Pulled from the supplement records collection.	See example request.

{
    "source": "api.example.com",
    "contact": {
        "identifiers": {
            "email": "test@example.com"
        },
        "identifiersPriority": [\
            "email"\
        ]
    },
    "supplement": "recharge_subscriptions",
    "updatedDateField": "updated_at",
    "records": [\
        {\
            "id": 266787835,\
            "product_title": "Silver-Gold ring",\
            "updated_at": "2022-08-02T16:27:41+00:00"\
        },\
        {\
            "id": 266787836,\
            "properties": {\
                "is_prepaid": true\
            },\
            "updated_at": "2022-08-02T16:27:41+00:00"\
        }\
    ]
}

POST/upsertSupplementRecords/batch

Batch requests are supported using POST/api/upsertSupplementRecords/batch.

POST/addProductsToCart

Method	Example URL path
POST	https://integrations-ingest-svc.cordial.com/api/addProductsToCart
Adds products to cart when needed.

* Required

Parameters	Type	Description	Example
source	string	Data source	api.example.com
*contact	object	Identifies contact. Schema: - identifiers: object - identifiersPriority: object	See example request.
*items	array	Products added to cart. Required: productID, qty, sku, name, category, name Optional: description, itemPrice, url, images, properties, attributes	See example request.

{
    "source": "api.example.com",
    "contact": {
        "identifiers": {
            "email": "test@example.com"
        },
        "identifiersPriority": [\
            "email"\
        ]
    },
    "items": [\
        {\
            "productID": "507f1f77bcf86cd799439011",\
            "sku": "G-32",\
            "qty": 1,\
            "category": "Games",\
            "name": "Monopoly: 3rd Edition",\
            "description": "Best game ever!",\
            "itemPrice": 18.99,\
            "url": "https://www.example.com/product/path",\
            "images": [\
                "https://www.example.com/product/path.jpg"\
            ],\
            "properties": {\
                "coupon": "MAYDEALS",\
                "variant": "200 pieces"\
            },\
            "attr": []\
        }\
    ]
}

POST/addProductsToCart/batch

Batch requests are supported using POST/api/addProductsToCart/batch.

POST/removeProductsFromCart

Method	Example URL path
POST	https://integrations-ingest-svc.cordial.com/api/removeProductsFromCart
Removes products from cart when needed.

* Required

Parameters	Type	Description	Example
source	string	Data source	api.example.com
*contact	object	Identifies contact. Schema: - identifiers: object - identifiersPriority: object	See example request.
*items	array	Products removed from cart. Required: productID, qty Optional: sku, category, name, description, itemPrice, url, images, properties, attributes	See example request.

{
    "source": "api.example.com",
    "contact": {
        "identifiers": {
            "custom_id": "test-user",
            "email": "test@example.com"
        },
        "identifiersPriority": [\
            "custom_id",\
            "email"\
        ]
    },
    "items": [\
        {\
            "productID": "507f1f77bcf86cd799439011",\
            "qty": 1\
        },\
        {\
            "productID": "7994fas21daf39afsd12011",\
            "qty": 5\
        }\
    ]
}

POST/removeProductsFromCart/batch

Batch requests are supported using POST/api/removeProductsFromCart/batch.