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.

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

Access by region

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

Supported actions

• POST/upsertContact
• POST/createContactactivities
• POST/addContactsToList
• POST/removeContactsFromList
• POST/upsertOrder
• POST/upsertSupplementRecords
• POST/addProductsToCart
• POST/removeProductsFromCart

POST/upsertContact

• * 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

• * 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/addContactsToList

• * 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

• * 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

• * 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

• * 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

• * 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

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