How can we help?

Search

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. This can include geographic information, product preferences, loyalty program points, and more.

API set name: accountcontactattributes

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

Authentication

Cordial's core APIs use HTTPS Basic Authentication (BA). From within the Cordial platform, you can generate an encoded API key for your account and use it for authorization.

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.

Methods, parameters, and examples

POST/v2/accountcontactattributes

Method URL path
POST /v2/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.

  • * 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 shirts with a max item count of 5 and min/max allowed characters per item of 1 and 40, respectively.

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

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

    https://<path>/v2/accountcontactattributes

GET/v2/accountcontactattributes

Method URL Path
GET /v2/accountcontactattributes
  • Retrieves contacts' attributes from the Cordial database.
  • It's 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.

  • The following URL will retrieve an account's contact attributes.

    https://<path>/v2/accountcontactattributes

    The following URL will retrieve all contact attributes that have type string

    https://<path>/v2/accountcontactattributes?type=string

    The following URL will retrieve all contact attributes that have type number and are being indexed.

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

GET/v2/accountcontactattributes/{key}

Method URL Path
GET /v2/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

  • The following URL will retrieve the  contact attributes with the key value of first_name

    https://<path>/v2/accountcontactattributes/first_name

PUT/v2/accountcontactattributes/{key}

Method URL path
PUT /v2/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.

  • Use the same parameters as the POST method above, updating the desired information. No additional 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 URL in conjunction with the JSON will perform the POST.

    https://<path>/v2/accountcontactattributes/first_name

DELETE/v2/accountcontactattributes/{key}

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

  • The following URL will delete the contact attribute with the key value of points

    https://<path>/v2/accountcontactattributes/points

Test in Swagger

You can access and test Cordial's APIs in Swagger.

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.

Comments

0 comments

Please sign in to leave a comment.