In this section

Contacts API

Overview

The Contacts Collection contains all contacts and their associated attribute, list, and channel data.

  • API Set Name: contacts

Additional information

  • Cordial keeps track of contact data by assigning at least one unique identifier to all contact records. Default primary and secondary contact identifier keys can be configured uniquely for each Cordial account based on clients' data infrastructure.
  • 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.

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 or secondary identifier keys.
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:

  • Filter the response by primary or secondary contact identifier 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 column/field (ascending or descending order).

Parameters

Parameter Type Description Example
contact identifier string Unique contact identifier value to look up and reference the contact. Possible variations include <cID_value>, or <primary_key_value> or <secondary_key:secondary_key_value>. 58d2fc99ac0c8117814d4e78,
email:msmith@example.com, custID:ID1234, sms:16198880000
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 fields:

http://<path>/contacts

Filter results by email

The following URI will retrieve a contact and its associated account contact attributes where email is the identifier:

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/cID:58d2fc99ac0c8117814d4e78

Filter response by audience key

The following URI will retrieve contacts within the audience using the audience key (or name) 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 channel address to identify and reference the contact. msmith@example.com, 6198888888
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:

  • street_address
  • street_address2
  • city
  • state
  • postal_code
  • country
  • tz (time zone)
  • loc
    • lat (latitude)
    • lon (longitude)

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".
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. If the max items limit is exceeded (default is 25), newer values will replace the oldest values.

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

To add a value:
{ "add": ["apple"] }

To remove a value:
{ "remove": ["banana"] }
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
suppressTriggers boolean If true, will suppress message triggers that are based on updates to contact attribute values. Defaults to true. false

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: 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"
		}
	},
	"first_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}
/contacts/{secondary_key}:{value}
Deletes a contact from the Cordial database.

The primary_key is defined by the primary contact identifier value.

The secondary_key is defined by the secondary contact identifier key and value.

Example DELETE request URI

The following URI will delete a contact and its associated account attribute values where email is the contact identifier:

http://<path>/contacts/email:msmith@example.com

GET /contacts/{primary_key}

Method URI Path
GET /contacts/{primary_key}
/contacts/{secondary_key}:{value}
Retrieves a single contact from the Cordial database.

The primary_key is defined by the primary contact identifier value.

The secondary_key is defined by the secondary contact identifier key and value.

Example GET request URI

The following URI will retrieve a contact record and its associated account attribute values where the contact identifier is "msmith@example.com".

http://<path>/contacts/email:msmith@example.com

PUT /contacts/{primary_key}

Method URI Path
PUT /contacts/{primary_key}
/contacts/{secondary_key}:{value}
Updates a contact within the Cordial database using the appropriate JSON body.

The primary_key is defined by the primary contact identifier value.
The secondary_key is defined by the secondary contact identifier key and 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 a 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"]
	}
}
Note: If the number of array values exceeds the max items limit (default 25), the oldest values will be replaced with the newest values. The max items limit can be set using a POST or PUT Account Contact Attributes API call.

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: 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 where the identifier is "msmith@example.com".

http://<path>/contacts/email:msmith@example.com

PUT /contacts/{primary_key}/unsubscribe/{channel}

Method URI Path
PUT /contacts/{primary_key}/unsubscribe/{channel}
/contacts/{secondary_key}:{value}/unsubscribe/{channel}
Unsubscribes a contact within the Cordial database per channel.

The primary_key is defined by the primary contact identifier value. The channel is the specified channel ("email" for example).
The secondary_key is defined by the secondary contact identifier key and value.

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 where the contact identifier is "msmith@example.com".

http://<path>/contacts/email: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/email:msmith@example.com/unsubscribe/email?mcID=252:58ffed51f0c36063476c1752:ot:58d30719ac0c8117814da1f3:1

POST /contacts/merge

Method URI Path
POST /contacts/merge

Merges one contact (source) into another (destination) in the Cordial database using the appropriate JSON body.

Parameters

* Required

Parameter Type Description Example
*sourceContact string Contact ID (CID) of the source contact. This contact will be deleted after the merge. 60a2a151c60e523d3b632677
*destinationContact string Contact ID (CID) of the destination contact. This contact will still exist after the merge. 21a2a151c60a423d3b632677
*options object

Allows choosing of what data to keep from each contact. Note that this object contains the following set schema of key names:

  • orders
  • events
  • cart
  • lists
  • attributes
  • supplements
  • email_channels
  • sms_channels
  • push_channels
 See below

Example JSON request (minimum requirements)

The following will merge two contacts together by adding the source contact's SMS number to the destination contact and add all events and orders from the source contact to the destination contact.

{
    "sourceContact": "string",
    "destinationContact": "string",
    "options": {
        "orders": "merge",
        "events": "merge",
        "cart": "destinationContact",
        "lists": "destinationContact",
        "attributes": "destinationContact",
        "supplements": "destinationContact",
        "email_channels": "destinationContact",
        "sms_channels": "sourceContact",
        "push_channels": "ignore"
    }
}

Note:

  • orders = "merge", "ignore"
  • events = "merge", "ignore"
  • cart = "sourceContact", "destinationContact", "lastModified"
  • lists = "sourceContact", "destinationContact"
  • attributes = "sourceContact", "destinationContact"
  • supplements = "sourceContact", "destinationContact"
  • email_channels = "sourceContact", "destinationContact"
  • sms_channels = "sourceContact", "destinationContact"
  • push_channels = "merge", "ignore"

Example POST request URI

The following URI in conjunction with the JSON will perform the POST.

http://<path>/contacts/merge

DELETE /contacts/{primary_key}/cart

Method URI Path
DELETE /contacts/{primary_key}/cart
/contacts/{secondary_key}:{value}/cart
Removes cart object from the contact.

The primary_key is defined by the primary contact identifier value.
The secondary_key is defined by the secondary contact identifier key and value.

Example DELETE request URI

The following URI will delete the cart object from the contact where the contact identifier is msmith@example.com.

http://<path>/contacts/email:msmith@example.com/cart

POST /contacts/{primary_key}/cart

Method URI Path
POST /contacts/{primary_key}/cart
/contacts/{secondary_key}:{value}/cart
Adds a cart object to the contact.

The primary_key is defined by the primary contact identifier value.
The secondary_key is defined by the secondary contact identifier key and 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 where the contact identifier is "msmith@example.com".

http://<path>/contacts/email:msmith@example.com/cart

PUT /contacts/{primary_key}/cart

Method URI Path
PUT /contacts/{primary_key}/cart
/contacts/{secondary_key}:{value}/cart
Updates the cart object for the contact.

The primary_key is defined by the primary contact identifier value.
The secondary_key is defined by the secondary contact identifier key and 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 where the contact identifier is "msmith@example.com".

http://<path>/contacts/email:msmith@example.com/cart

POST /contacts/{primary_key}/cartitems

Method URI Path
POST /contacts/{primary_key}/cartitems
/contacts/{secondary_key}:{value}/cartitems
Adds a product to the cart.

The primary_key is defined by the primary contact identifier value.
The secondary_key is defined by the secondary contact identifier key and 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 where the contact identifier is "msmith@example.com".

http://<path>/contacts/email:msmith@example.com/cartitems

DELETE /contacts/{primary_key}/cartitems/{productID}

Method URI Path
DELETE /contacts/{primary_key}/cartitems/{productID}
/contacts/{secondary_key}:{value}/cartitems/{productID}
Removes a product from the cart.

The primary_key is defined by the primary contact identifier value.
The secondary_key is defined by the secondary contact identifier key and value.

Example DELETE request URI

The following URI will delete the cart item with the productID of "PurplePlaid123123" for the contact where the contact identifier is "msmith@example.com".

http://<path>/contacts/email:msmith@example.com/cartitems/PurplePlaid123123

DELETE /contacts/{primary_key}/cartitems/{productID}/{qty}

Method URI Path
DELETE /contacts/{primary_key}/cartitems/{productID}
/contacts/{secondary_key}:{value}/cartitems/{productID}
Removes a product from the cart by quantity.

The primary_key is defined by the primary contact identifier value.
The secondary_key is defined by the secondary contact identifier key and 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 where the contact identifier is "msmith@example.com".

http://<path>/contacts/email:msmith@example.com/cartitems/PurplePlaid123123/1

POST /contacts/{primary_key}/downloadprofile

Method URI Path
POST /contacts/{primary_key}/downloadprofile
/contacts/{secondary_key}:{value}/downloadprofile

Creates an export job to download and store a JSON file of a contact's profile (including event data) from the Cordial database.

The primary_key is defined by the primary contact identifier value.
The secondary_key is defined by the secondary contact identifier key and value.

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/email:msmith@example.com/downloadprofile

Error responses

The Cordial API will return an error object with an errorKey and message if there is a problem with an API call. Below is a list of errors specific to the Contacts API endpoint, along with suggested modifications to resolve each error. If you receive an error from this API endpoint that is not listed in this table, it is likely recorded within the Global API Error Responses page.

errorKey Message Modifications
CONTACTS_INVALID_PRIMARY_KEY Incorrect primary key Either no key was provided, or the provided key was not found.
CONTACTS_INVALID_SUPPRESS_TRIGGERS_VALUE Incorrect value for suppressTriggers The possible values for suppressTriggers are true or false.
CONTACTS_CHANNEL_OBJECT_MUST_BE_AN_ARRAY Channel must be an array The channel must be an array of one or more values.
CONTACTS_CHANNEL_KEY_NOT_FOUND Channel :channelName not found
Channel doesn't exist		 Check the unique channel key and address for the contact.
VALIDATION_ERROR Address cannot be empty This error most likely means there is a problem with the address entered for the contact.
CONTACTS_PUSH_CHANNEL_VALIDATION_ERROR Invalid push channel Make sure the contact information is input correctly.
CONTACTS_INVALID_SUBSCRIBE_STATUS Invalid subscribe status on :channel The possible values for subscribeStatus are none, subscribed, and unsubscribed.
CONTACTS_MISSING_PRIMARY_KEY PrimaryKey not provided Check that the primary_key is input correctly.
CONTACTS_RECORD_EXISTS Contact already exists This contact already exists in the database.
CONTACTS_CONTACT_NOT_FOUND Contact does not exist Check that the information provided for this contact is correct.
CONTACTS_INVALID_MCID_FOR_THIS_CONTACT mcID doesn't belong to this contact The unique mcID belongs to the contact the message was sent to.
CONTACTS_PRODUCT_NOT_FOUND Product does not exist The unique productID was not found.
CONTACTS_CONTACT_NOT_FOUND Contact not found The contact was not found based on the provided information.
CONTACTS_CART_NOT_FOUND Cart does not exist This error occurs when trying to remove a product from a cart that doesn't belong to the contact or when the cartitem is not present in the cart.
CONTACTS_INVALID_SEARCH_FIELD Search field is not correct Incorrect search parameter provided.
VALIDATION_ERROR Parameter server is not set
Parameter path is not set
Parameter username is not set
Parameter password is not set
Parameter password or key should be provided
Parameter port is not set
Parameter aws_access_key_id is not set
Parameter aws_secret_access_key is not set
Parameter aws_bucket is not set
Parameter aws_region is not set
Parameter gcs_bucket is not set		 Make sure the correct parameters are set and input with correct information.
CONTACTS_FIELD_MUST_BE_INDEXED Search field is not indexed The search field should be indexed.

Related articles

Comments

0 comments

Please sign in to leave a comment.