In This Section

Contacts

API Set Name: contacts

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 accountcontactattributes collection.
  • A contact can be associated to one or more lists, stored in the contact as an array of lists, but inserted and updated as attribute 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 contactactivities 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
accountcontactattributes Attribute/value data can be added to a contact based on the existence of an account contact attributes.
contactactivities Contacts are linked to their activities by their primary key.
accountlists Contacts can be associated to accountlists, 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:

  • filter the response by "email" to retrieve information for a single contact.
  • filter the response by "cID" to retrieve information for a single contact.
  • filter the response by an audience key to limit the response to a certain audience.
  • filter the response by an attribute key to limit the attribute data to a specific value.
  • apply "per_page" and "page" query string parameters to limit the count returned and page position for large responses.
  • sort response by a specific field (ascending or descending order).

Parameters

* Required

Parameter Type Description Example
email 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 asc/desc
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. true

Example GET Request URIs

Retrieve all contacts

The following URI will retrieve all contacts and include all account contact attributes fields:

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:

Note: In the API response, cID is referred to as "_id".
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 Defaults to "none". Promotional messages will not be sent unless set to "subscribed" none, subscribed or unsubscribed
invalid boolean Defaults to "false". No email message will be sent unless set to "false" true or false
<attribute key> string When the attribute type is set as string Mark
<attribute key> ISO 8601 date When the attribute type is set as date 2015-10-09T07:40:00.000Z
<attribute key> number When the attribute type is set as number 22
<attribute key> geo When the attribute type is set as geo group field city, state, postal_code
<attribute key> array

When the attribute type is set as an array
The default behavior is to replace the array value with the provided one. An object specifying add/remove behavior can be specified to override the default. 

["apple","banana","orange"]

To add an element:
{ "add": ["apple"] }

To remove a element:
{ "remove": ["banana"] }
<list key> boolean Adds or removes the contact from a list true or false
forceSubscribe boolean If unsubscribed, this key must be used to update subscribeStatus to subscribed true or false

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, if that is a requirement.

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 (fName, lName, location.postal_code, age) and list assignment (auto-enthusiast and safe-driver).

{
  "channels": {
    "email": {
      "address": "msmith@example.com",
      "subscribeStatus": "subscribed"
    }
  },
  "fName": "Mark",
  "lName": "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.
  • Lists must already exist in the system to add their assignment.
  • List assignment is determined by a boolean value, "true" or "false".
  • "location.postal_code" is a geo attribute.

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.

Example JSON Requests

Updating an attribute

The following will update the "fName" attribute to "Markus". Note that the "fName" attribute was created prior to updating the contact.

{
  "fName": "Markus"
}

Update list value

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.

{
  "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"
    }
}

Update an number value

The following will update the "points" attribute for the contact.

{
  "points":75
}

The following will increment the "points" attribute for the contact.

{
  "points": {"inc":15}
}

The following will decrement the "points" attribute for the contact.

{
  "points": {"inc":-15}
}

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).

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

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

 

Related articles

Comments

0 comments

Please sign in to leave a comment.