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.

Methods, parameters, and examples

GET /contacts

Parameters

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":

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

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

Parameters

* Required

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

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.

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}

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}

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}

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

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.

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}

Parameters

* Required

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

Parameters

* Required

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

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

Parameters

* Required

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

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

Parameters

* Required

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}

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}

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

Parameters

* Required

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.