Account Contact Attributes

API Set Name: accountcontactattributes

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

API Description and Functional Purpose:

The accountcontactattributes collection contains the universal set of attributes or fields that can be associated with contacts.

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 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 to index.
• 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 PUT to change or update fields once they are created.

Parameters

* Required

Parameter	Type	Description	Example
*key	string	Unique key value to identify and reference the 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 will be used for search or audience creation, set it to true. Default 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	Defines 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 characters for string data type, the minimum characters per array value in array data type and minimum value for numeric data type. Required if max is set. Default is 0.	0
max	integer	Defines the maximum characters for string data type, max characters per array value in array data type, and the max 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.	true
Optional options object
maxitems	integer	For the array type, defines the max amount of 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 a has 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.

{
	"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 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 account attributes that are of type "string" and are not being used as an index.

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 an 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 fields for an attribute within the Cordial database. 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 using the appropriate JSON body.

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 attribute within 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 of "points".

Example Request URIs

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

http://<path>/accountcontactattributes/points