API Set Name: contacts
- GET /contacts
- POST /contacts
- DELETE /contacts/{primary_key}
- GET /contacts/{primary_key}
- PUT /contacts/{primary_key}
- PUT /contacts/{primary_key}/unsubscribe/{channel}
- DELETE /contacts/{primary_key}/cart
- POST /contacts/{primary_key}/cart
- PUT /contacts/{primary_key}/cart
- POST /contacts/{primary_key}/cartitems
- DELETE /contacts/{primary_key}/cartitems/{productID}
- DELETE /contacts/{primary_key}/cartitems/{productID}/{qty}
- POST /contacts/{primary_key}/downloadprofile
API Description and Functional Purpose:
The contacts collection contains all contacts and their associated attribute, list and channel data.
Additional information:
- A contact is unique based on email address (also referred to as primary_key). By default Cordial uses channels.email.address as the primary key.
- A contact can have multiple attribute key/value pairs such as First Name, Last Name, etc. provided an attribute has been previously defined within the account contact attributes collection.
- A contact can be associated to one or more lists, stored in the contact collection as an array of key/value pairs.
- Validators assigned to each attribute are enforced when attribute data is added or updated within the contact collection.
- Validators changed after data is added will not affect existing saved data nor will they force revalidation. However, edits to that data may.
- Contact activity data resides in the contact activities collection and is associated back to the contact via its primary key, currently the email address.
Resource Associations:
The following resource collections are associated to this collection.
Collection | Association |
---|---|
account contact attributes | Attribute data can be added to a contact based on the existence of account contact attributes. |
contact activities | Contacts are linked to their activities by their primary key (email address). |
account lists | Contacts can be associated to account lists, identifying a contact as a member of one or more lists. |
orders | Order data will be included in the response for the GET method, provided there is available order data for that contact. |
GET /contacts
Method | URI Path |
---|---|
GET | /contacts |
Retrieves all contacts from the Cordial database.
Using query string parameters (see example URIs below) it is possible to:
|
Parameters
Parameter | Type | Description | Example |
---|---|---|---|
string | Unique email address to identify and reference the contact. | msmith@example.com | |
audience-key | string | The name of the audience for filtering contacts. | 30_Day_Engaged |
sort_by | string | Column to sort by | lastModified |
sort_dir | string | Direction to sort by, works in conjunction with sort_by Possible Values: asc, desc |
asc |
page | number | Page number of results | 2 |
per_page | number | Number of results per page | 20 |
return_count | boolean | The number of records returned. The default is false. Possible Values: true, false |
true |
Example GET Request URIs
Retrieve All Contacts
The following URI will retrieve all contacts and include all account contact attributes
http://<path>/contacts
Filter Results By Email
The following URI will retrieve a contact and its associated account contact attributes where the email is "msmith@example.com":
http://<path>/contacts?email=msmith@example.com
Filter Results By cID
The following URI will retrieve a contact and its associated account contact attributes where the cID is "58d2fc99ac0c8117814d4e78":
http://<path>/contacts/58d2fc99ac0c8117814d4e78?isCID=true
Filter Response By Audience Key
The following URI will retrieve contacts within the audience with a key of "clicked".
http://<path>/contacts?audience-key=clicked
Filter Response By Attribute Key
The following URI will retrieve all contacts where the value for the contact attribute gender is "male".
http://<path>/contacts?gender=male
Page Request Parameters
The following URI will retrieve all contacts starting from the third page grouping contacts by 10. For example, page 1 would have included the first 10, page 2 the second group of 10 and so on.
http://<path>/contacts?page=3&per_page=10
Return Count
The following URI will retrieve a count of all contacts in the request:
http://<path>/contacts?return_count=true
Note: Get /contacts can process a maximum of 10k contacts. For example, a request for 1k contact records per page will return contact records for pages 1 through 10 but it will not return records on the 11th page. If it is necessary to access more that 10k contact records, the contactexport api call should be used.
POST /contacts
Method | URI Path |
---|---|
POST | /contacts |
Creates a new contact in the Cordial database using the appropriate JSON body.
Contacts can optionally include attribute values and list association. Note that list and contact attributes keys must be created prior to the POST /contacts method with the UI, or the API using the accountcontactattributes and accountlists methods. |
Parameters
* Required
Parameter | Type | Description | Example |
---|---|---|---|
*address | string | Unique email address to identify and reference the contact. This is the default primary key for contacts. | msmith@example.com |
subscribeStatus | string | Promotional messages will not be sent unless set to "subscribed". Default is "none". Possible Values: none, subscribed or unsubscribed |
subscribed |
invalid | boolean | No email message will be sent unless set to "false". Default is "false". Possible Values: true, false |
false |
string attribute key | string | Adds a string attribute value when the attribute type is set as "string". | Mark |
date attribute key | ISO 8601 date | Adds a dater attribute value when the attribute type is set as "date". | 2015-10-09T07:40:00.000Z |
number attribute key | number | Adds a number attribute value when the attribute type is set as "number". | 22 |
geo attribute key | geo |
Adds a geo attribute value when the attribute type is set as "geo". Note that geo attributes contain following set schema of key names:
Geo attributes may be added/updated using dot notation or an array of key/value pairs. |
"<geo_key>.city": "San Diego" or "<geo_key>": { "city": "San Diego" }, |
array attribute key | array |
Adds array attribute values when the attribute type is set as "array". |
["apple","banana","orange"] To remove a value: |
list key | boolean | Adds or removes the contact from a list. Possible Values: true, false |
true |
forceSubscribe | boolean | If unsubscribed, this key must be used to update subscribeStatus to subscribed Possible Values: true, false |
true |
Note: Cordial is designed as a multi-channel messaging platform. Email is the default channel, where address is required. channels.email.address acts as the primary key for each contact by default. With a custom configuration to your account, it is possible to alternatively use a contact attribute value as the primary key.
Example JSON Request (minimum requirements)
The following will create a new contact with the email "msmith@example.com".
{ "channels": { "email": { "address": "msmith@example.com" } } }
Example JSON Request (with subscribe status, contact attributes and list assignment)
The following will create a new contact for the email msmith@example.com with contact attribute values (first_name, last_name, age, location.postal_code) and list assignments (auto-enthusiast and safe-driver). Note that the contact attribute keys and list keys were created prior to the POST /contacts using the POST /accountcontactattributes and POST /accountlists API calls.
{ "channels": { "email": { "address": "msmith@example.com", "subscribeStatus": "subscribed" } }, "firat_name": "Mark", "last_name": "Smith", "location.postal_code": "92613", "age": 32, "auto-enthusiast": true, "safe-driver": true }
Note:
- If subscribe status is not set, it will default to "none". Other available options are "subscribed" and "unsubscribed".
- Contact attributes must already exist in the system to add their values. Contact attributes can be added using the POST /accountcontactattributes API call.
- Lists must already exist in the system to add their assignment. Lists can be added using the POST /accountlists API call.
- List assignment is determined by a boolean value, "true" or "false".
- "location.postal_code" is a geo attribute where the key is "location".
- Geo attributes contain the following set schema of key names:
- street_address
- street_address2
- city
- state
- postal_code
- country
- tz (time zone)
- loc
- lat (latitude)
- lon (longitude)
Example JSON Request (resubscribing a contact)
The following will resubscribe a contact and override the previously set unsubscribe flag. It will also set the invalid flag to false.
Note: Setting the invalid flag to false will override a hard bounced email address.
{ "channels": { "email": { "address": "msmith@example.com", "subscribeStatus": "subscribed", "invalid": false } }, "forceSubscribe": true }
Example POST Request URI
The following URI in conjunction with the JSON will perform the POST.
http://<path>/contacts
DELETE /contacts/{primary_key}
Method | URI Path |
---|---|
DELETE | /contacts/{primary_key} |
Deletes a contact from the Cordial database.
The primary_key is defined by the contact's unique "email address" value. |
Example DELETE Request URI
The following URI will delete a contact and its associated account attribute values with the primary key value of "msmith@example.com".
http://<path>/contacts/msmith@example.com
GET /contacts/{primary_key}
Method | URI Path |
---|---|
GET | /contacts/{primary_key} |
Retrieves a single contact from the Cordial database.
The primary_key is defined by the contact's unique "email address" value. |
Example GET Request URI
The following URI will retrieve a contact and its associated account attributes values with the primary key value of "msmith@example.com".
http://<path>/contacts/msmith@example.com
PUT /contacts/{primary_key}
Method | URI Path |
---|---|
PUT | /contacts/{primary_key} |
Updates a contact within the Cordial database using the appropriate JSON body.
The primary_key is defined by the contact's unique "email address" value. |
Parameters
See the parameters for POST /contacts above.
Example JSON Requests
Update a String Attribute
The following will update the contact's first_name string attribute to "Markus".
{ "first_name": "Markus" }
Update an Number Value
The following will update the contact's points number attribute to 75.
{ "points":75 }
The following will increment the contact's points number attribute by 15.
{ "points": { "inc": 15 } }
The following will decrement the contact's points number attribute by 15.
{ "points": { "inc": -15 } }
Update an Array Value
The following will update the contact's fav_fruits array attribute with the value "banana". Note that this will overwrite any existing array values.
{ "fav_fruits": ["banana"] }
The following will update the contact's fav_fruits array attribute with "banana" and "strawberry". Note this will overwrite existing array values.
{ "fav_fruits": ["banana", "strawberry"] }
The following will add the value "apple" to the contact's fav_fruits array attribute. Existing values will be retained unless the max items limit is exceeded (default 25).
{ "fav_fruits": { "add": ["apple"] } }
The following will remove the value "apple" and "strawberry" from the contact's fav_fruits array attribute.
{ "fav_fruits": { "remove": ["apple", "strawberry"] } }
Update List Assignment
The following will update the list assignments of safe-driver and premium-roadside-assistance for the contact. Note that the lists were created prior to updating the contact using the POST /accountlists API call.
{ "safe-driver": false, "premium-roadside-assistance": true }
Update Email Address
The following will update the email address for the contact.
{ "channels": { "email": { "address": "markussmith@example.com" } } }
Example PUT Request URI
The following URI in conjunction with the JSON will perform the PUT for the contact with the primary key of "msmith@example.com".
http://<path>/contacts/msmith@example.com
PUT /contacts/{primary_key}/unsubscribe/{channel}
Method | URI Path |
---|---|
PUT | /contacts/{primary_key}/unsubscribe/{channel} |
Unsubscribes a contact within the Cordial database per channel.
The primary_key is defined by the contact's unique "email address" value. The channel is the specified channel ("email" for example). |
Parameters
* Required
Parameter | Type | Description | Example |
---|---|---|---|
mcID | string | The message contact ID for attribution to a sent message. | 252:58ffed51f0c36063476c1752:ot:58d30719ac0c8117814da1f3:1 |
Example PUT Request URI
The following URI will set the subscribe status to "unsubscribed" in the "email" channel of the contact with a primary key of "msmith@example.com".
http://<path>/contacts/msmith@example.com/unsubscribe/email
The following URI will unsubscribe the contact and attribute the unsubscribe to a specific message using the mcID.
http://<path>/contacts/msmith@example.com/unsubscribe/email?mcID=252:58ffed51f0c36063476c1752:ot:58d30719ac0c8117814da1f3:1
DELETE /contacts/{primary_key}/cart
Method | URI Path |
---|---|
DELETE | /contacts/{primary_key}/cart |
Removes cart object from the contact.
The primary_key is defined by the contact's unique "email address" value. |
Example DELETE Request URI
The following URI will delete the cart object from the contact with a primary key of msmith@example.com.
http://<path>/contacts/msmith@example.com/cart
POST /contacts/{primary_key}/cart
Method | URI Path |
---|---|
POST | /contacts/{primary_key}/cart |
Adds a cart object to the contact.
The primary_key is defined by the contact's unique "email address" value. |
Parameters
* Required
Parameter | Type | Description | Example |
---|---|---|---|
mcID | string | Message Contact ID | 264:590261c7f0c360ee35a8046f:ot:5900ddf2ac0c81178189d93b:1 |
customerID | string | Customer ID | 38583 |
linkID | string | Link ID | 1234 |
url | string | Cart URL | http://example.com |
Cart Items | |||
*productID | string | Item Identifier | GreenPlaid123123 |
*sku | string | Item Number | 111222333 |
*category | string | Item Category | Shirts |
*name | string | Item Name | Green Plaid |
description | string | Item description | Awesome shirt |
qty | int | Quantity in the cart | 2 |
itemPrice | number | Price per item | 10.99 |
url | string | Link to the item | http://www.shirts.com/GreenPlaid123123 |
images | array | image names or paths | ["image1.jpg","image2.jpg"] |
properties | object | property value pairs | { "style": "v-neck", "material": "cotton" } |
attr | object | attribute value pairs | { "size": "small", "color": "red" } |
Example JSON Request
{ "mcID": "264:590261c7f0c360ee35a8046f:ot:5900ddf2ac0c81178189d93b:1", "customerID": "1234", "linkID": "1234", "url": "http:example.com", "cartitems": [{ "productID": "GreenPlaid123123", "name": "Green Plaid", "sku": "111222333", "category": "Shirts", "qty": 2, "images": ["image1.jpg", "image2.jpg"], "itemPrice": 10.99, "amount": 21.98, "description": "Awesome shirt", "url": "http://www.shirts.com/GreenPlaid123123", "attr": { "size": "small", "color": "green" }, "properties": { "style": "v-neck", "material": "cotton" } }, { "productID": "BluePlaid123123", "name": "Blue Plaid", "sku": "111222444", "category": "Shirts", "qty": 1, "itemPrice": 10.99, "amount": 10.99, "description": "Awesome shirt", "url": "http://www.shirts.com/BluePlaid123123", "attr": { "size": "small", "color": "blue" }, "properties": { "style": "v-neck", "material": "cotton" } } ] }
Example POST Request URI
The following URI in conjunction with the JSON will add the cart object for the contact with the primary key value of "msmith@example.com".
http://<path>/contacts/msmith@example.com/cart
PUT /contacts/{primary_key}/cart
Method | URI Path |
---|---|
PUT | /contacts/{primary_key}/cart |
Updates the cart object for the contact.
The primary_key is defined by the contact's unique "email address" value. |
Parameters
See parameters above for POST /contacts/{primary_key}/cart.
Example JSON Request
See example above for POST /contacts/{primary_key}/cart.
Example PUT Request URI
The following URI in conjunction with the JSON will update the cart object for the contact with the primary key of "msmith@example.com".
http://<path>/contacts/msmith@example.com/cart
POST /contacts/{primary_key}/cartitems
Method | URI Path |
---|---|
POST | /contacts/{primary_key}/cartitems |
Adds a product to the cart.
The primary_key is defined by the contact's unique "email address" value. |
Parameters
* Required
Parameter | Type | Description | Example |
---|---|---|---|
*productID | string | Item Identifier | GreenPlaid123123 |
*sku | string | Item Number | 111222333 |
*category | string | Item Category | Shirts |
*name | string | Item Name | Green Plaid |
description | string | Item description | Awesome shirt |
qty | int | Quantity in the cart | 2 |
itemPrice | number | Price per item | 10.99 |
url | string | Link to the item | http://www.shirts.com/GreenPlaid123123 |
images | array | image names or paths | ["image1.jpg","image2.jpg"] |
properties | object | property value pairs | { "style": "v-neck", "material": "cotton" } |
attr | object | attribute value pairs | { "size": "small", "color": "red" } |
Example JSON Request
{ "productID": "PurplePlaid123123", "name": "Green Plaid", "sku": "111222333", "category": "Shirts", "qty": 2, "images": ["image1.jpg", "image2.jpg"], "itemPrice": 10.99, "amount": 21.98, "description": "Awesome shirt", "url": "http://www.shirts.com/PurplePlaid123123", "properties": { "size": "large", "color": "Purple" } }
Example POST Request URI
The following URI in conjunction with the JSON will add an item to the cart of the contact with the primary key value of "msmith@example.com".
http://<path>/contacts/msmith@example.com/cartitems
DELETE /contacts/{primary_key}/cartitems/{productID}
Method | URI Path |
---|---|
DELETE | /contacts/{primary_key}/cartitems/{productID} |
Removes a product from the cart.
The primary_key is defined by the contact's unique "email address" value. |
Example DELETE Request URI
The following URI will delete the cart item with the productID of "PurplePlaid123123" for the contact with the primary key value of "msmith@example.com".
http://<path>/contacts/msmith@example.com/cartitems/PurplePlaid123123
DELETE /contacts/{primary_key}/cartitems/{productID}/{qty}
Method | URI Path |
---|---|
DELETE | /contacts/{primary_key}/cartitems/{productID} |
Removes a product from the cart by quantity.
The primary_key is defined by the contact's unique "email address" value. |
Example DELETE Request URI
The following URI will delete quantity of "1" from the cart item with the productID of "PurplePlaid123123" for the contact with the primary key value of "msmith@example.com".
http://<path>/contacts/msmith@example.com/cartitems/PurplePlaid123123/1
POST /contacts/{primary_key}/downloadprofile
Method | URI Path |
---|---|
POST | /contacts/{primary_key}/downloadprofile |
Creates an export job to download and store a JSON file of a contact's profile (including event data) from the Cordial database. |
Parameters
* Required
Parameter | Type | Description | Example |
---|---|---|---|
* Destination Note: Destination parameters are only required if SFTP or FTP is used as the destination. If parameters are not supplied, or set as AWS, the exported file can be downloaded through the UI. |
|||
type | string | Defines the destination type. Possible Values: aws, ftp, sftp |
sftp |
server (required if type is ftp or sftp) |
string | Domain or IP address of the SFTP server. | sftp.example.com |
port (required if type is ftp or sftp) | number | Defines the port number for the FTP or SFTP server. | 22 |
username (required if type is ftp or sftp) | string | Defines the username for FTP or SFTP authentication. | username |
password (required if type is ftp or sftp) | string | Defines the password for FTP or SFTP authentication. | password |
path (required if type is ftp or sftp) | string | Defines the path to the folder. | /folder |
Example JSON Requests
The following will initiate an export job of a JSON file containing all profile data (including events) of the specified contact, downloadable via the UI on the Jobs page.
{
"destination": {
"type": "aws"
}
}
The following will initiate an export job of a JSON file via SFTP containing all profile data (including events) of the specified contact.
{
"destination": {
"type": "sftp",
"server": "example.com",
"port": "21",
"username": "username",
"password": "password",
"path": "/"
}
}
Example Request URIs
The following URI in conjunction with the JSON will perform the POST.
http://<path>/contacts/{primary_key}/downloadprofile
Comments
0 comments
Please sign in to leave a comment.