# How can we help?

## Overview

Cordial's Scriptable API utilities create additional capabilities for our [Scriptable API](https://support.cordial.com/hc/en-us/articles/15280050793613), using Smarty scripts to transform data for compatibility.

## Transformation utilities

- [upsertContact](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#h_01H2RGJVQ5JG6CN7841W8WS5BX)
- [createContactactivities](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#h_01H2RGK41WMQ5518E28737Y1VW)
- [addContactsToList](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#h_01H2RGKBPZ84WHVJ6RPNA0Z2T4)
- [removeContactsFromList](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#h_01JJAES99SBM4QTXNVQ75CC1F2)
- [upsertOrder](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#h_01JJAES99SRVF9X3NT9XJQS14K)
- [upsertSupplementsRecords](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#h_01JJAES99SVE2TJH9Y6CCA5WVV)
- [addProductsToCart](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#h_01JJAES99S209DJRW910Y0ZT76)
- [removeProductsFromCart](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#h_01JJAES99SZ0S2G2ZYCPPDMR6K)
- [addHeader](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#h_01JJAES99VCXN1VNR8A4JS9AM5)
- [setStatusCode](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#h_01JJAES99VKBTBG676XCWYDYKZ)
- [setResponseBody](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#h_01JJAES99VDPBW2BX8RHW2S8EP)
- [getLastError](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#h_01H2RGJCR4K7BSQDS44QVCNX6Q)

### upsertContact

Support for contact merge strategies on unique key conflicts.

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

- [Example](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#zp-1-0)
- [Parameters](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#zp-1-1)

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

\* Required

| Parameters | Type | Description |
| --- | --- | --- |
| source | string | Data source |
| \*identifiers | object | Contains contact key-value pairs. Schema: <br>- customID<br>- email<br>- channels.phone.address |
| identifiersPriority | array | The order in which identifiers are used when searching for a contact. |
| 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 |
| 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.<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. |

### createContactactivities

Creates or updates contacts in real time.

- Syntax: `$utils->createContactactivities($data)`

- [Example](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#zp-2-0)
- [Parameters](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#zp-2-1)

```
{$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:<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>- **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:<br>- name<br>- time<br>- properties: array<br>- geo: array<br>- device: array |

### addContactsToList

Creates a new list in real time.

- Syntax: `$utils->addContactsToList($data)`

- [Example](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#zp-3-0)
- [Parameters](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#zp-3-1)

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

\* Required

| Parameters | Type | Description |
| --- | --- | --- |
| source | string | Data source |
| \*contact | object | Identifies contacts to add to list. Schema:<br>- identifiers: object<br>- 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](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#zp-4-0)
- [Parameters](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#zp-4-1)

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

\* Required

| Parameters | Type | Description |
| --- | --- | --- |
| source | string | Data source |
| \*contacts | object | Identifies contacts to add to list. Schema:<br>- identifiers: object<br>- 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:<br>- name of list<br>- destination ID |

### upsertOrder

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

- Syntax: `$utils->upsertOrder($data)`

- [Example](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#zp-5-0)
- [Parameters](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#zp-5-1)

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

\* Required

| Parameters | Type | Description |
| --- | --- | --- |
| source | string | Data source |
| \*contact | object | Identifies contact making purchase. Schema: <br>- identifiers: object<br>- 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. <br>**Required:** \*productID, \*sku, \*name<br>**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](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#zp-6-0)
- [Parameters](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#zp-6-1)

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

\* Required

| Parameters | Type | Description |
| --- | --- | --- |
| source | string | Data source |
| \*contact | object | Identifies contact. Schema: <br>- identifiers: object<br>- 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](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#zp-7-0)
- [Parameters](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#zp-7-1)

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

\* Required

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

### removeProductsFromCart

Removes products from cart when needed.

- Syntax: `$utils->removeProductsFromCart($data)`

- [Example](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#zp-8-0)
- [Parameters](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#zp-8-1)

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

\* Required

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

### addHeader

Adds any custom header to a response.

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

- [Example](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#zp-9-0)

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

### setStatusCode

Sets the response status code.

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

- [Example](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#zp-10-0)

```
{$response->setStatusCode(200)}
```

### setResponseBody

Sets the response body.

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

- [Example](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#zp-11-0)

```
{$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](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#zp-12-0)

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

## Authentication utilities

- [getSecret](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#h_01H2RGKJT45ER0G67R3Q873V39)
- [authorize](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#h_01H2RGKV09R7XKNMR0TK3BZJ46)
- [authorizeByKey](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#h_01H2RGM2ZW7C6SFA66MSCJWJNS)

### getSecret

Gets secret value by key.

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

- [Example](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#zp-13-0)

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

### authorize

Method to authenticate the request, assuming conditions were checked.

- Syntax: `$utils->authorize()`

- [Example](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#zp-14-0)

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

### authorizeByKey

Authenticates the request by Cordial API key.

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

- [Example](https://support.cordial.com/hc/en-us/articles/16685802820749-Scriptable-API-utilities#zp-15-0)

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