Scriptable API utilities – Cordial Knowledge Base

How can we help?

Overview

Cordial's Scriptable API utilities create additional capabilities for our Scriptable API, using Smarty scripts to transform data for compatibility.

Transformation utilities

upsertContact

Support for contact merge strategies on unique key conflicts.

Syntax: $utils->upsertContact($data)
Example
Parameters

{$utils->upsertContact($request->parseBodyAsJson())}

* Required

Parameters	Type	Description
source	string	Data source
*identifiers	object	Contains contact key-value pairs. Schema: - customID - email - channels.phone.address
identifiersPriority	array	The order in which identifiers are used when searching for a contact.
attributes	object	Attributes to update. Schema: - channel and subscribe status - array - number - location.postal.code - email - customId - LISTNAME
forceSubscribe	boolean	forceSubscribe should be passed as true if subscribeStatus is changed from unsubscribed to subscribed.
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.

createContactactivities

Creates or updates contacts in real time.

Syntax: $utils->createContactactivities($data)
Example
Parameters

{$utils->createContactactivities($request->parseBodyAsJson())}

* Required

Parameters	Type	Description
source	string	Data source
*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.
*contactActivities	array	Specifies events triggered by contact. Schema: - name - time - properties: array - geo: array - device: array

addContactsToList

Creates a new list in real time.

Syntax: $utils->addContactsToList($data)
Example
Parameters

{$utils->addContactsToList($request->parseBodyAsJson())}

* Required

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

removeContactsFromList

Removes contacts from a list in real time.

Syntax: $utils->removeContactsFromList($data)
Example
Parameters

{$utils->removeContactsFromList($request->parseBodyAsJson())}

* Required

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

upsertOrder

Removes order items from cart when needed, such as when an order is completed.

Syntax: $utils->upsertOrder($data)
Example
Parameters

{$utils->upsertOrder($request->parseBodyAsJson())}

* Required

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

upsertSupplementsRecords

Skips updates if the existing record has a more recent update date than the one coming from the request.

Syntax: $utils->upsertSupplementsRecords($data)
Example
Parameters

{$utils->upsertSupplementsRecords($request->parseBodyAsJson())}

* Required

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

addProductsToCart

Adds products to cart when needed.

Syntax: $utils->addProductsToCart($data)
Example
Parameters

{$utils->addProductsToCart($request->parseBodyAsJson())}

* Required

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

removeProductsFromCart

Removes products from cart when needed.

Syntax: $utils->removeProductsFromCart($data)
Example
Parameters

{$utils->removeProductsFromCart($request->parseBodyAsJson())}

* Required

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

addHeader

Adds any custom header to a response.

Syntax: $response->addHeader($name, $value)
Example

{$response->addHeader('Content-Type','application/json')}

setStatusCode

Sets the response status code.

Syntax: $response->setStatusCode($statusCode)
Example

{$response->setStatusCode(200)}

setResponseBody

Sets the response body.

Syntax: $response->setResponseBody($responseBody)
Example

{$response->setResponseBody('Sample response body.')}

getLastError

Retrieves information about the last error that occurred during the processing of the Smarty template.

Syntax: $utils->getLastError()
Example

{$lastError = $utils->getlastError()}

Authentication utilities

getSecret

Gets secret value by key.

Syntax: $utils->getSecret($key)
Example

API key: {$utils->getSecret('api_key')}
Password: {$utils->getSecret('password')}

authorize

Method to authenticate the request, assuming conditions were checked.

Syntax: $utils->authorize()
Example

{$utils->authorize(Content for authorized users)}

authorizeByKey

Authenticates the request by Cordial API key.

Syntax: $utils->authorizeByKey($apiKey)
Example

{$utils->authorizeByKey($request->header('custom-header'))}