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
Comments
0 comments
Please sign in to leave a comment.