Custom attributes

Every organization is unique, and which data is needed to drive a powerful marketing operation therefor vary from organization to organization. At the center of most marketing activities is the Contact model, holding personal information and contact details for your contacts. Many of your marketing activities will also involve the order history of your contacts, which is where the Order model come in. Out-of-the-box the Contact and Order models provide a range of general attributes - name, contact information, order value, order items etc. that covers a lot of ground. However, to make the most of your marketing efforts, your organization may want to import additional attributes, not covered by the general attributes - this is where custom attributes come in handy.

Custom attributes are additional attributes that your organization want to save on a Contact or an Order, to make segmentation and filtering even more customized to your needs - it may be a membership renewal date, a loyalty program level, or any other data point that is important to you.

You can extend your data model with additional custom attributes at any time and they will be immediately available for filtering in the MarketHype application. To make it possible for us to provide you with appropriate filter options and to validate and properly index your data, all custom attributes need to be defined in advance, before you can import any data using those attributes.

Extend Contact model

The Contact model holds personal data and contact information for a single contact in your database. When extending the Contact model with custom attributes, try to focus on attributes that somehow describe that person:

Loyalty program level (Silver / Gold / Platinum)
A list of preferred music genres (Rock, Pop & Jazz)
Membership renewal date

Extend Order model

The Order model holds data about a specific order placed by a Contact. By default the order can hold information about when the order was placed, what was purchased, order amount etc. When extending the Order model with custom attributes, try to focus on attributes that additionally describe the specific order:

Customer satisfaction score
Loyalty program number
Shipment method

Define a custom attribute

Before you can import data including your custom attribute, you need to define the attribute. By defining the attribute in advance, we can validate your data on import, index it for filtering and provide relevant filtering options in the application depending on what type of data your attribute holds.

Custom attributes can be defined on either the Contact or Order model. To define an attribute you need to define key label and type.

Key

The key is a unique identifier for your custom attribute. The key is used to map your imported data to the right attribute.

WARNING

The same key cannot be used twice on your model and cannot be changed in the future.

Label

The label is used in the MarketHype filter tool to describe your custom attribute. Use a label that describe the attribute and make sense to your marketing organization. You can update the label of a custom attribute at any time.

Type

The type specifies the data type you intend to store as the custom attribute. Custom attributes currently support five different types - string number boolean date and list. When you import data for your custom attribute we will validate the incoming data against the data type and ignore data that cannot be mapped to the defined type.

The type will also impact what kind of filters are available in the application for the given custom attribute. A custom attribute of type number will have range filters (greater than / less than), which will not be available for a custom attribute of type boolean, to give an example.

WARNING

The type of the custom attribute cannot be changed in the future.

List

Custom attributes of type list need to be sent in as an object instead of an actual list. Each key in the object is a value in the custom attribute list you want to add or remove. The value for each key says whether this key should be added or removed from the custom attribute list.

For example, in order to add Elephant and Dog to the Animals custom attribute list, the client needs to send in:

"customAttributes": {
  "Animals": { "Elephant": true, "Dog": true },
},

This results in a contact or order with a Animals custom attribute with values: "Elephant", "Dog" Similarly, if you want to add Cat and remove Dog from this custom attribute list you would send in:

"customAttributes": {
  "Animals": { "Cat": true, "Dog": false },
},

If this was done on the same order/contact this would result in Animals being "Elephant", "Cat"

Example

Your organization have a loyalty program and on your Contact model you want to store the loyalty program level for each contact, to make it possible to filter your contacts based on what level they currently belong to.

To be able to import your loyalty program level, you would first have to extend your Contact model with a custom attribute to hold the data. You therefor need to decide what key, label, and type to use for the custom attribute.

label	key	type
Loyalty program level	loyaltyProgramLevel	`string`

To create a new custom contact attribute, you need to issue an HTTP request to the Data Ingestion API:

curl -X 'POST' \
  'https://api.markethype.io/ingestion/v1/imports/contacts/attributes' \
  -H 'Accept: application/json' \
  -H 'X-API-TOKEN: your-api-token' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "loyaltyProgramLevel",
  "label": "Loyalty program level",
  "type": "string"
}'

Your Contact model has now been extended with a custom attribute to hold the information and you can start importing your loyalty program data.

NOTICE

The endpoint is different depending on if you want to define a custom attributes for the Contact or Order model

# Custom attributes

# Extend Contact model

# Extend Order model

# Define a custom attribute

# Key

# Label

# Type

# List

# Example