Overview

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

Transformation utilities

• upsertContact
• createContactactivities
• addContactsToList
• removeContactsFromList
• upsertOrder
• upsertSupplementsRecords
• addProductsToCart
• removeProductsFromCart
• addHeader
• setStatusCode
• setResponseBody
• getLastError

upsertContact

Support for contact merge strategies on unique key conflicts.

• Syntax: $utils->upsertContact($data)

• {$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)

• {$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)

• {$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)

• {$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)

• {$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)

• {$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)

• {$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)

• {$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)

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

setStatusCode

Sets the response status code.

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

• {$response->setStatusCode(200)}

setResponseBody

Sets the response body.

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

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

getLastError

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

• Syntax: $utils->getLastError()

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

Authentication utilities

• getSecret
• authorize
• authorizeByKey

getSecret

Gets secret value by key.

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

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

authorize

Method to authenticate the request, assuming conditions were checked.

• Syntax: $utils->authorize()

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

authorizeByKey

Authenticates the request by Cordial API key.

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

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