How can we help?

Search

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

Access by region

Authentication

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

Supported actions

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.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/upsertContact/batch

Batch requests are supported using POST/api/upsertContact/batch. The payload is an array of individual items with the array size ranging from 1 to 100.

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.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/createContactactivities/batch

Batch requests are supported using POST/api/createContactactivities/batch. The payload is an array of individual items with the array size ranging from 1 to 100.

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. The payload is an array of individual items with the array size ranging from 1 to 100.

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 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"
        ]
    },
    "listName": "MyList",
    "isAllowedToCreateLists": true
}

POST/removeContactsFromList/batch

Batch requests are supported using POST/api/removeContactsFromList/batch. The payload is an array of individual items with the array size ranging from 1 to 100.

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. The payload is an array of individual items with the array size ranging from 1 to 100.

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. The payload is an array of individual items with the array size ranging from 1 to 100.

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. The payload is an array of individual items with the array size ranging from 1 to 100.

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. The payload is an array of individual items with the array size ranging from 1 to 100.

Comments

0 comments

Please sign in to leave a comment.