Account Contact Attributes API

Overview

The Account Contact Attributes Collection contains the universal set of attributes or fields that can be associated with contact profiles.

• API Set Name: accountcontactattributes

Additional information

• The possible data types for attributes are:
• string: can be any string.
• number: must be a number.
• date: must be a date. Date format is "ISO 8601" standard.
• geo: this is actually an object that contains address fields as well as a coordinate set. It is automatically indexed.
• array: an array of one or more values.
• The "cart" attribute type comes included as part of the contact data schema. There is no need to add a cart attribute for storing cart item data.  Learn more in the contacts API article.
• Attributes may be added at any time to your database and are immediately available to all contacts once created.
• Attributes must already exist before contact data containing those attributes can be added.
• Attribute names must be unique.
• Attributes can be optionally indexed.
• If the data is strictly used for personalization, there is no need for it to be indexed.
• If the field will be used in an audience builder query, it should be indexed.

Resource associations

The following resource collections are associated to this collection.

Collection	Association
contacts	Attribute/value data can be added to a contact based on the existence of an accountcontactattributes attribute.

POST /accountcontactattributes

Method	URI Path
POST	/accountcontactattributes
Creates a new attribute in the Cordial database using the appropriate JSON body. Posting more than one time for the same attribute name will generate an error. Use the PUT method to change or update fields once the attribute is created.

Parameters

* Required

Parameter	Type	Description	Example
*key	string	Unique key value to identify and reference the attribute field.	first_name
*name	string	User friendly display name.	First Name
*type	string	Defines the field's data type. Possible Values: string, number, date, geo, array.	string
index	boolean	Indicates if the field should be indexed or not. If this field is intended to be used for search or audience creation, set it to true. Default value is false. Possible Values: 1, 0, true, false	true
updateUnauthenticated	boolean	Defines if unauthenticated modifications are allowed to the attribute via JavaScript. Default is false. Possible Values: true, false	true
retainOnDestroy	string	Determines how attribute values will be treated when a contact record is deleted. If no value (or null value) is passed, the attribute value will be destroyed. Default is null. Possible Values: anonymized, unchanged, null, ""	null
Optional validators object
min	integer	Defines the minimum number of characters for string data type, the minimum number of characters per array value in array data type, and the minimum value for numeric data type. Required if max is set. Default is 0.	0
max	integer	Defines the maximum number of characters for string data type, the maximum number of characters per array value in array data type, and the maximum value for numeric data type. Required if min is set. Default for string, array and numeric is 128.	500
required	boolean	Defines if a value is required. Default is false. Possible Values: true, false	true
Optional options object
maxitems	integer	For the array data type, defines the maximum number of array items. Default is 25.	5

Example JSON requests

String

The following will create an indexed string contact attribute called "first_name".

{
 "name": "First Name",
 "key": "first_name",
 "type": "string",
 "index": true
}

Number

The following will create an indexed numeric contact attribute called "points" that is required and has a maximum value of 250.

{
 "name": "Points",
 "key": "points",
 "type": "number",
 "index": true,
 "validators": {
 "min": 0,
 "max": 250,
 "required": true
 }
}

Date

The following will create an indexed date contact attribute called "bday".

{
 "name": "Birthday",
 "key": "bday",
 "type": "date",
 "index": true
}

Geo

The following will create an indexed geo contact attribute called "home_address".

{
 "name": "Home Address",
 "key": "home_address",
 "type": "geo",
 "index": true
}

Array

The following will create an indexed array contact attribute called "fruits" with a max item count of 5 and min/max allowed characters per item of 1 and 40, respectively.

{
 "name": "Favorite Fruits",
 "key": "fruits",
 "type": "array",
 "index": true,
 "validators": {
 "max": 40,
 "min": 1
 },
 "options": {
 "maxitems": 5
 }
}

Example request URIs

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

http://<path>/accountcontactattributes

GET /accountcontactattributes

Method	URI Path
GET	/accountcontactattributes
Retrieves contacts' attributes from the Cordial database. It is possible to filter the response using query string parameters for type and index values. For example, you may want to retrieve all non-indexed "string" type attributes.

Example request URIs

The following URI will retrieve all accountcontactattributes.

http://<path>/accountcontactattributes

The following URI will retrieve all accountcontactattributes that have type "string".

http://<path>/accountcontactattributes?type=string

The following URI will retrieve all accountcontactattributes that have type "number" and are being indexed.

http://<path>/accountcontactattributes?type=number&indexed=1

GET /accountcontactattributes/{key}

Method	URI Path
GET	/accountcontactattributes/{key}
Retrieves the specified contact attribute from the Cordial database based on the attribute's unique key value. For example, /accountcontactattributes/first_name would return the response data for the attribute with the key value of "first_name".

Example request URIs

The following URI will retrieve the accountcontactattribute with the key value of "first_name".

http://<path>/accountcontactattributes/first_name

PUT /accountcontactattributes/{key}

Method	URI Path
PUT	/accountcontactattributes/{key}
Updates existing contact attribute fields using the appropriate JSON body. The accountcontactattribute is defined by the accountcontactattribute's unique key value. For example, /accountcontactattributes/first_name allows the attribute with the key value of "first_name" to be updated.

Parameters

See parameters for the POST method above. No parameters are required.

Example JSON requests

The following will update the account contact attribute name to "first", and will change the field to be indexed.

{
 "name": "first",
 "index": true
}

Example request URIs

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

http://<path>/accountcontactattributes/first_name

DELETE /accountcontactattributes/{key}

Method	URI Path
DELETE	/accountcontactattributes/{key}
Deletes an existing attribute from the Cordial database. The accountcontactattribute is defined by the accountcontactattribute's unique key value. For example, /accountcontactattributes/points would delete the attribute with the key value of "points".

Example request URIs

The following URI will delete the accountcontactattribute with the key value of "points".

http://<path>/accountcontactattributes/points

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 Account Contact Attributes 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
VALIDATION_ERROR	Min value should be greater than or equal to 0 Max value should be greater than or equal to 0 Max must be Greater than Min Possible values is empty	Check to see that required values are input. Also check to see that the Max value is greater than the Min value, which is 0 or higher.
ACCOUNT_ATTRIBUTES_KEY_MUST_BE_UNIQUE	Key must be unique	An error will be provided if the key is not unique.
ACCOUNT_ATTRIBUTES_NAME_MUST_BE_UNIQUE	Name must be unique	An error will be provided if the name is not unique.
ACCOUNT_ATTRIBUTES_KEY_EXISTS_AS_LIST_NAME	This key name must be unique This key is currently in use as a list name	An error will be provided if the key name is not unique.
ACCOUNT_ATTRIBUTES_NAME_OR_KEY_IS_RESERVED	NAME/KEY is not allowed for the name or key of an attribute	Reserved words ("name" and "key") are prohibited from being used for the name or key of an attribute.
ACCOUNT_ATTRIBUTES_INVALID_FIELD_TYPE	Invalid field type	The provided field type is invalid.
ACCOUNT_ATTRIBUTES_KEY_NOT FOUND	Key does not exist.	Ensure that the key exists and is input correctly.
ACCOUNT_ATTRIBUTES_SECONDARY_KEY_EXCEPTION	Empty string passed as key field Index specification has no elements	An empty string is invalid input for a secondary key field.
ACCOUNT_ATTRIBUTES_SECONDARY_KEY_LIMIT_EXCEEDED	Total of secondary keys cannot be more than some value	Check the limits for secondary key inputs to ensure they are not exceeded.
ACCOUNT_ATTRIBUTES_INVALID_VALIDATORS	Invalid validators	Check the limits provided for validator inputs to ensure they are not exceeded.
ACCOUNT_ATTRIBUTES_INVALID_NAME	Invalid attribute name	For names, use letters, numbers, dashes, and underscores to ensure they are valid.
ACCOUNT_ATTRIBUTES_INVALID_KEY	Invalid attribute key Invalid attribute key name	For keys and key names, use letters, numbers, dashes, and underscores to ensure they are valid. Keys are unique.
ACCOUNT_ATTRIBUTES_GEO_FIELDS_MUST_BE_INDEXED	Geo fields must be indexed	Geo fields are automatically indexed.
ACCOUNT_ATTRIBUTES_CANNOT_CHANGE_FIELD_TYPE	You can not change type	Attribute field types are permanently set.