Adding custom attributes

ChartMogul allows you to add custom attributes to customers and contacts using our API.

Custom attributes can be used with filtering, search, and segmentation. For example, a customer's last login, the marketing campaign used to acquire them, or the name of their account manager.

There is no limit to the number of custom attributes you can add.

📘
You can add and edit custom attributes using the API. For quick edits, update custom attributes using the app interface.

Here's what we cover in this tutorial:

Adding custom attributes to customers

There are three ways to add custom attributes to customers using the API:

1. Add custom attributes when creating the customer
The Create a Customer endpoint allows you to include custom attributes when importing customers into ChartMogul.

curl -X POST "https://api.chartmogul.com/v1/customers" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
            "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
            "external_id": "cus_0001",
            "name": "Adam Smith",
            "attributes": {
              "tags": ["important", "Prio1"],
              "custom": [
                {"type": "String", "key": "channel", "value": "Facebook", "source": "integration"},
                {"type": "Integer", "key": "age", "value": 18}
              ]
            }
        }'

ChartMogul::Customer.create!(
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  external_id: "cus_0001",
  name: "Adam Smith",
  attributes: {
    custom: [
      { type: "String", key: "channel", value: "Facebook" },
      { type: "Integer", key: "age", value: 18, source: "clearbit" },
    ],
  },
)

ChartMogul.Customer.create(config, {
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  external_id: "cus_0001",
  name: "Adam Smith",
  attributes: {
    custom: [
      { type: "String", key: "channel", value: "Facebook" },
      { type: "Integer", key: "age", value: 18, source: "clearbit" },
    ],
  },
});

ChartMogul\Customer::create([
  "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  "external_id" => "cus_0001",
  "name" => "Adam Smith",
  "attributes" => [
    "custom" => [
      ["type" => "String", "key" => "channel", "value" => "Facebook"],
      ["type" => "Integer", "key" => "age", "value" => 18, "source" => "clearbit"]
    ]
  ]
]);

api.CreateCustomer(&cm.NewCustomer{
  DataSourceUUID:     "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  ExternalID:         "cus_0001",
  Name:               "Adam Smith",
  Email:              "[email protected]",
  Country:            "US",
  City:               "New York",
  LeadCreatedAt:      "2015-10-14",
  FreeTrialStartedAt: "2015-11-01",
  Attributes: &cm.NewAttributes{
    Tags: []string{"important", "Prio1"},
    Custom: []*cm.CustomAttribute{
      {Key: "channel", Value: "Facebook", Type: "String"},
      {Key: "age", Value: 18, Type: "Integer", Source: "clearbit"},
    },
  },
})

ChartMogul.Customer.create(
  config,
  data={
    "data_source_uuid": "ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11",
    "external_id": "cus_0001",
    "name": "Adam Smith",
    "attributes": {
      "custom": [
        {"type": "String", "key": "channel", "value": "Facebook"},
        {"type": "Integer", "key": "age", "value": 18, "source": "clearbit"},
      ]
    },
  },
)

2. Add custom attributes to an existing customer using their UUID
You can add custom attributes to a customer using their ChartMogul UUID once they have a customer record in ChartMogul. This is useful when you want to add custom attributes on an ongoing basis from one or several data sources.

curl -X POST "https://api.chartmogul.com/v1/customers/cus_de305d54-75b4-431b-adb2-eb6b9e546012/attributes/custom" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
            "custom": [
              {"type": "String", "key": "channel", "value": "Facebook"},
              {"type": "Integer", "key": "age", "value": 8, "source": "clearbit"}
            ]
         }'

customer = ChartMogul::Customer.retrieve("cus_de305d54-75b4-431b-adb2-eb6b9e546012")
customer.add_custom_attributes!(
  { type: "String", key: "channel", value: "Facebook" },
  { type: "Integer", key: "age", value: 8, source: "clearbit" }
)

ChartMogul.CustomAttribute.add(
  config,
  "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
  {
    custom: [
      { type: "String", key: "channel", value: "Facebook" },
      { type: "Integer", key: "age", value: 8, source: "clearbit" },
    ],
  }
);

$customer = ChartMogul\Customer::retrieve("cus_de305d54-75b4-431b-adb2-eb6b9e546012");

$custom = $customer->addCustomAttributes(
  ["type" => "String", "key" => "channel", "value" => "Facebook"],
  ["type" => "Integer", "key" => "age", "value" => 8, "source" => "clearbit"]
);

api.AddCustomAttributesToCustomer("cus_ec341fd8-ee01-11e6-b78e-9b6f6124979f",
  []*cm.CustomAttribute{
    &cm.CustomAttribute{
      Type:  "String",
      Key:   "channel",
      Value: "Facebook"},
    &cm.CustomAttribute{
      Type:   "Integer",
      Key:    "CAC",
      Value:  8,
      Source: "clearbit"},
  },
)

chartmogul.CustomAttributes.add(
  config,
  uuid="cus_c0dc8d74-edfd-11e6-a357-832dddba822f",
  data={
    "custom": [
      {"type": "String", "key": "channel", "value": "Facebook"},
      {"type": "Integer", "key": "CAC", "value": 8, "source": "clearbit"}
    ]
  }
)

3. Add custom attributes to existing customers using their email
You can also add custom attributes to customers with a specific email. This is useful when you only have a customer's email address, and not their ChartMogul UUID. For instance, customers imported using Zapier.

🚧
Custom attributes are added to all customers that have the specified email address in your account.

curl -X POST "https://api.chartmogul.com/v1/customers/cus_de305d54-75b4-431b-adb2-eb6b9e546012/attributes/custom" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
            "custom": [
              {"type": "String", "key": "channel", "value": "Facebook"},
              {"type": "Integer", "key": "age", "value": 8, "source": "clearbit"}
            ]
         }'

customers = ChartMogul::Customer.search("[email protected]")
customers.each do |c|
  c.add_custom_attributes!(
    { type: "String", key: "channel", value: "Facebook" },
    { type: "Integer", key: "age", value: 8, source: "clearbit" }
  )
end

ChartMogul.CustomAttribute.add(config, {
  email: "[email protected]",
  custom: [
    { type: "String", key: "channel", value: "Facebook" },
    { type: "Integer", key: "age", value: 8, source: "clearbit" },
  ],
});

$customers = ChartMogul\Customer::search("[email protected]");

foreach ($customers->entries as $customer) {
  $customer->addCustomAttributes(
    ["type" => "String", "key" => "channel", "value" => "Facebook"],
    ["type" => "Integer", "key" => "age", "value" => 8, "source" => "clearbit"]
  );
}

api.AddCustomAttributesWithEmail("[email protected]",
  []*cm.CustomAttribute{
    &cm.CustomAttribute{
      Type:  "String",
      Key:   "channel",
      Value: "Facebook"},
    &cm.CustomAttribute{
      Type:   "Integer",
      Key:    "CAC",
      Value:  8,
      Source: "clearbit"},
  },
)

chartmogul.CustomAttributes.add(
  config,
  data={
    "email": "[email protected]",
    "custom": [
      {"type": "String", "key": "channel", "value": "Facebook"},
      {"type": "Integer", "key": "CAC", "value": 8, "source": "clearbit"},
    ],
  },
)

Adding custom attributes to contacts

Add custom attributes when creating the contact
The Create a Contact endpoint allows you to include custom attributes when importing contacts to ChartMogul.

curl -X POST "https://api.chartmogul.com/v1/contacts" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
            "customer_uuid": "cus_00000000-0000-0000-0000-000000000000",
            "data_source_uuid": "ds_00000000-0000-0000-0000-000000000000",
            "first_name": "Adam",
            "last_name": "Smith",
            "position": 9,
            "title": "CEO",
            "email": "[email protected]",
            "phone": "+1234567890",
            "linked_in": "https://linkedin.com/linkedin",
            "twitter": "https://twitter.com/twitter",
            "notes": "Heading\nBody\nFooter",
            "custom": [
              { "key": "Facebook", "value": "https://www.facebook.com/adam.smith" },
              { "key": "date_of_birth", "value": "1985-01-22" }
            ]
         }'

Which custom attributes can I send to ChartMogul?

Add sales, marketing and customer success data, such as:

Marketing campaign
Account manager
NPS score
Number of support requests
Cost of acquisition
Last active timestamp

Each custom attribute has three required properties:

type - A string indicating the data type of the custom attribute. Can be one of String, Integer, Decimal, Timestamp or Boolean.
- String - Accepts alphanumeric characters. Maximum of 255 characters allowed.
- Integer - Accepts only numeric characters.
- Decimal - Accepts floating point numbers.
- Timestamp - In the ISO 8601 format.
- Boolean - Can be one of TRUE, true, t, 1, FALSE, false, f, or 0.
key- A string containing the name of the custom attribute. Accepts alphanumeric characters and underscores.
value - The value of the custom attribute. Should be of the data type and allowed values as specified above under type.
source - The source of the attribute data. This is an optional parameter for use in the UI. It can be updated, but doesn't appear in the response.

How do I update custom attributes using the API?

You can update custom attributes for customers and contacts using the API. This is useful when attributes change over time such as Total number of support requests or last active time.

Update custom attributes while updating a customer
The endpoint to update a customer is useful when you need to update many customer fields, including their custom attributes.

curl -X PATCH "https://api.chartmogul.com/v1/customers/cus_ab223d54-75b4-431b-adb2-eb6b9e234571" \
     -u YOUR_API_KEY: \
     -H  "Content-Type: application/json" \
     -d '{
            "state": "CA",
            "attributes": {
              "tags": ["high-value"],
              "custom": {
                "CAC": 25
              }
            }
        }'

customer = ChartMogul::Customer.retrieve("cus_ab223d54-75b4-431b-adb2-eb6b9e234571")

customer.state = "CA"

customer.attributes[:tags] = ["high-value"]

customer.attributes[:custom] = { "CAC": 25 }

customer.update!

const customerUuid = "cus_ab223d54-75b4-431b-adb2-eb6b9e234571";

const data = {
  state: "CA",
  attributes: {
    tags: ["high-value"],
    custom: {
      CAC: 25,
    },
  },
};

ChartMogul.Customer.modify(config, customerUuid, data);

ChartMogul\Customer::update(
  ["customer_uuid" => "cus_ab223d54-75b4-431b-adb2-eb6b9e234571"],
  [
    "state" => "CA",
    "attributes" => [
      "tags" => ["high-value"],
      "custom" => ["CAC" => 25]
    ]
  ]
);

api.UpdateCustomer(&cm.Customer{
  State: "CA",
  Attributes: &cm.Attributes{
    Tags: []string{"high-value"},
    Custom: map[string]interface{}{
      "CAC": 25,
    },
  },
}, "cus_ab223d54-75b4-431b-adb2-eb6b9e234571")

chartmogul.Customer.modify(
  config,
  uuid="cus_ab223d54-75b4-431b-adb2-eb6b9e234571",
  data={
    "state": "CA", 
    "attributes": {
      "tags": ["high-value"], 
      "custom": {"CAC": 25}
    }
  },
)

Update custom attributes for a specific customer
The endpoint to update custom attributes of a customer is useful when you only need to update custom attributes and keep all other customer data the same.

curl -X PUT "https://api.chartmogul.com/v1/customers/cus_de305d54-75b4-431b-adb2-eb6b9e546012/attributes/custom" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
            "custom":{
              "pro": true,
              "channel": "Twitter"
            }
         }'

customer = ChartMogul::Customer.retrieve("cus_de305d54-75b4-431b-adb2-eb6b9e546012")

customer.update_custom_attributes!(
  pro: true,
  channel: "Twitter",
)

ChartMogul.CustomAttribute.update(
  config,
  "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
  {
    custom: {
      pro: true,
      channel: "Twitter",
    },
  }
);

$customer = ChartMogul\Customer::retrieve("cus_de305d54-75b4-431b-adb2-eb6b9e546012");

$customer->updateCustomAttributes(
  ["channel" => "Twitter"],
  ["pro" => true]
);

api.UpdateCustomAttributesOfCustomer(
  "cus_c0dc8d74-edfd-11e6-a357-832dddba822f",
  map[string]interface{}{
    "channel": "Twitter",
  },
)

chartmogul.CustomAttributes.update(
  config,
  uuid="cus_c0dc8d74-edfd-11e6-a357-832dddba822f",
  data={
    "custom": {
      "channel": "Twitter"
    }
  },
)

Update custom attributes while updating a contact
The Update a Contact endpoint allows you to include custom attributes when updating contacts in ChartMogul.

curl -X PATCH "https://api.chartmogul.com/v1/contacts/con_00000000-0000-0000-0000-000000000000" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
            "customer_external_id": "customer_002",
            "first_name": "Bill",
            "last_name": "Thompson",
            "position": 10,
            "title": "CTO",
            "email": "[email protected]",
            "phone": "+987654321",
            "linked_in": "https://linkedin.com/bill-linkedin",
            "twitter": "https://twitter.com/bill-twitter",
            "notes": "New Heading\nNew Body\nNew Footer",
            "custom": [
              { "key": "Facebook", "value": "https://www.facebook.com/bill.thompson" },
              { "key": "date_of_birth", "value": "1990-01-01" }
            ]
         }'

It's also possible to remove custom attributes if they are no longer relevant for the customer.

To remove an attribute from all customers, archive it by navigating in-app to Settings & Data > Custom Attributes.

How do I segment my customers using custom attributes?

Once you add custom attributes to your customers, you can use them for filtering, segmentation, and search. Learn more about segmentation.

If you're an Admin in ChartMogul account, manage custom attributes by navigating to Settings & Data > Custom Attributes.