# 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](https://support.cordial.com/hc/en-us/articles/15280050793613) 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](https://integrations-ingest-svc.cordial.com/docs#/). 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](https://support.cordial.com/hc/en-us/articles/115005365087-API-Keys).

### Access by region

- **usw1:** [https://integrations-ingest-svc.cordial.com/api](https://integrations-ingest-svc.cordial.com/)
- **usw2:** [https://integrations-ingest-svc.usw2.cordial.com/api](https://integrations-ingest-svc.usw2.cordial.com/)
- **use1:** [https://integrations-ingest-svc.use1.cordial.com/api](https://integrations-ingest-svc.use1.cordial.com/)

## 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](https://support.cordial.com/hc/en-us/articles/13084804213517) set up in your account

## Supported actions

- [POST/upsertContact](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#upsertContact)  - [POST/upsertContact/batch](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#upsertContactBatch)
- [POST/createContactactivities](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#CreateContactactivities)  - [POST/createContactactivities/batch](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#createContactActivitiesBatch)
- [POST/addContactsToList](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#addContactsToList)  - [POST/addConctactsToList/batch](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#addContactsToListBatch)
- [POST/removeContactsFromList](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#removeContactsFromList)  - [POST/removeContactsFromList/batch](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#removeContactsFromListBatch)
- [POST/upsertOrder](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#upsertOrder)  - [POST/upsertOrder/batch](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#upsertOrderBatch)
- [POST/upsertSupplementRecords](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#upsertSupplementRecords)  - [POST/upsertSupplementRecords/batch](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#upsertSupplementRecordsBatch)
- [POST/addProductsToCart](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#addProductsToCart)  - [POST/addProductsToCart/batch](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#addProductsToCartBatch)
- [POST/removeProductsFromCart](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#removeProductsFromCart)  - [POST/removeProductsFromCart/batch](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#removeProductsFromCartBatch)

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

- [Parameters](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#zp-1-0)
- [Example JSON request](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#zp-1-1)

\* Required

| Parameters | Type | Description | Example |
| --- | --- | --- | --- |
| source | string | Data source | api.example.com |
| \*identifiers | object | Contains contact key-value pairs. Schema: <br>- customID<br>- email<br>- 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: <br>- channel and subscribe status<br>- array<br>- number<br>- location.postal.code<br>- email<br>- customId<br>- 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.<br>- **mergeAllowed:** Boolean. Determines if contacts merge is allowed for this upsert.<br>- **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. |  |

- [Parameters](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#zp-2-0)
- [Example JSON request](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#zp-2-1)

\* 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:<br>- **identifiers:** object<br>- **identifiersPriority:** object<br>- **attributes:** Object. The attributes to be set if a contact does not exist and should be created. Ignored otherwise.<br>- **forceSubscribe:** boolean<br>- **mergeOptions:** boolean<br>- **canBeCreated:** Boolean. Optional and false by default. Defines if a contact should be created if it’s not present.<br>- **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:<br>- name<br>- time<br>- properties: array<br>- geo: array<br>- 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. |  |

- [Parameters](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#zp-3-0)
- [Example JSON request](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#zp-3-1)

\* Required

| Parameters | Type | Description | Example |
| --- | --- | --- | --- |
| source | string | Data source | api.example.com |
| \*contact | object | Identifies contacts to add to list. Schema:<br>- identifiers: object<br>- 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. |  |

- [Parameters](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#zp-4-0)
- [Example JSON request](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#zp-4-1)

\* Required

| Parameters | Type | Description | Example |
| --- | --- | --- | --- |
| source | string | Data source | api.example.com |
| \*contacts | object | Identifies contacts to remove from list. Schema:<br>- identifiers: object<br>- 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:<br>- name of list<br>- 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. |  |

- [Parameters](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#zp-5-0)
- [Example JSON request](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#zp-5-1)

\* Required

| Parameters | Type | Description | Example |
| --- | --- | --- | --- |
| source | string | Data source | api.example.com |
| \*contact | object | Identifies contact making purchase. Schema: <br>- identifiers: object<br>- 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. <br>**Required:** \*productID, \*sku, \*name<br>**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. |  |

- [Parameters](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#zp-6-0)
- [Example JSON request](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#zp-6-1)

\* Required

| Parameters | Type | Description | Example |
| --- | --- | --- | --- |
| source | string | Data source | api.example.com |
| \*contact | object | Identifies contact. Schema: <br>- identifiers: object<br>- 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. |  |

- [Parameters](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#zp-7-0)
- [Example JSON request](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#zp-7-1)

\* Required

| Parameters | Type | Description | Example |
| --- | --- | --- | --- |
| source | string | Data source | api.example.com |
| \*contact | object | Identifies contact. Schema: <br>- identifiers: object<br>- identifiersPriority: object | See example request. |
| \*items | array | Products added to cart. <br>**Required:** \*productID, \*qty, \*sku, \*name, \*category, \*name<br>**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. |  |

- [Parameters](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#zp-8-0)
- [Example JSON request](https://support.cordial.com/hc/en-us/articles/18799979779085-Asynchronous-API#zp-8-1)

\* Required

| Parameters | Type | Description | Example |
| --- | --- | --- | --- |
| source | string | Data source | api.example.com |
| \*contact | object | Identifies contact. Schema: <br>- identifiers: object<br>- identifiersPriority: object | See example request. |
| \*items | array | Products removed from cart. <br>**Required:** \*productID, \*qty<br>**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.