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

• POST/accountcontactattributes
• GET/accountcontactattributes
• GET/accountcontactattributes/{key}
• PUT/accountcontactattributes/{key}
• DELETE/accountcontactattributes/{key}
• Error responses

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.

Methods, parameters, and examples

POST/accountcontactattributes

• * 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

• 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
   }
  }

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

  http://<path>/accountcontactattributes

GET/accountcontactattributes

• 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}

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

  http://<path>/accountcontactattributes/first_name

PUT/accountcontactattributes/{key}

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

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

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

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

  http://<path>/accountcontactattributes/first_name

DELETE/accountcontactattributes/{key}

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