How can we help?

Asynchronous API

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 processes

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.

Supported actions

POST/upsertContact

Method URI path
POST

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.phone.address

     

    See example request.
    identifiersPriority

    array

    The order in which identifiers are used when searching for a contact.

    [ 'customId', 'email', 'phone' ]
    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.phone.address': '+1234567890'
    },
    'identifiersPriority': [ 'customId', 'email', 'phone' ],
    '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/createContactactivities

Method URI path
POST

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.
    • canBeCreated: Boolean. Optional and false by default. Defines if a contact should be created if it’s not 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.phone.address': '+1234567890'
            },
            'identifiersPriority': [ 'customId', 'email', 'phone' ],
            '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/addContactsToList

Method URI path
POST

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/removeContactsFromList

Method URI path
POST

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 add to 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.
  • {
        'source': 'api.example.com',
        'contacts': {
            'identifiers': [
                {
                    'custom_id': 'test-user',
                    'email': 'test@example.com'
                },
                {
                    'email': 'another@example.com'
                }
            ],
            'identifiersPriority': [ 'custom_id', 'email' ]
        },
        'identifyListBy': {
            'name': 'test-list',
            'segment_group_id': '777'
        }
    }

POST/upsertOrder

Method URI path
POST

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/upsertSupplementRecords

Method URI path
POST

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/addProductsToCart

Method URI path
POST

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/removeProductsFromCart

Method URI path
POST

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
            }
        ]
    }

 

Comments

0 comments

Please sign in to leave a comment.