Customers

A customer represents a single person who is either a member of a loyalty program or has purchased products from the company.

Each customer is defined by a set of mandatory, optional and company-specific custom fields.

Importing customer with same identifier the second time updates the customer record. Only keys that are supplied in the later imports are updated leaving the previously imported keys untouched.

If you want to remove keys from a customer, supply the removed keys with an empty string as the value.

Common fields

Mandatory fields

A customer must be identified by supplying at least one of the following fields. Custobar may merge customer information based on these fields in the future.

Field Type Description
external_id string Your unique identifier for a customer record, e.g. a loyalty number. The external_id must consist of letters, numbers and dashes only.
phone_number phone_number Phone number of a customer in a country prefixed format, e.g. +358101234567.
email email Email address of a customer, e.g. person@example.org.

Optional fields

Optional fields are not required, but recommended, since they add more richness for Custobar users, thus allowing them to make better marketing decisions.

Field Type Description
canonical_id string Should you have a need to provide multiple customer records which all represent a single natural or a legal person, use this field to group all these customers to a same entity.
first_name string First name of the customer.
last_name string Last name of the customer.
can_email boolean Email marketing permission for given email address. Defaults to false if omitted.
can_post boolean Permission from the customer to receive messaging by postal mail. Defaults to false if omitted.
can_profile boolean Permission from the customer to be profiled. Segmenting is done always. Defaults to false if omitted.
can_push boolean Permission from the customer to receive push messages. Segmenting is done always. Defaults to false if omitted.
can_sms boolean SMS marketing permission for given telephone number. Defaults to false if omitted.
date_joined datetime Customer account creation date, e.g. 2015-08-28 or 2015-08-28T14:10:00Z. If the timezone is not given, the timezone will be defaulted to the timezone configured in the Custobar’s settings.
mailing_lists list of string A single mailing list as a string or an array of mailing list identifiers that the customer belongs to.
is_forgotten boolean Anonymise all personally identifiable and/or sensitive data, and mark customer as forgotten. The customer cannot be unforgotten. Defaults to false if omitted.

In addition to recommended fields the customer model may be enriched with the following information.

Field Type Description
birth_date date Customer’s date of birth formatted as year-month-day, e.g. 1991-06-14.
city string Name of the city.
company string Name of the company behalf which the customer makes purchases.
country country_code Abbreviation for a country where the customer lives, e.g. se for Sweden.
gender string Customer’s gender. Male, female, other, or a free-form string.
house_number string Number of the house in the street, e.g. “3” or “III”.
house_number_addition string Additional information for street_name, e.g. the apartment number.
language language_code Primary language of the customer, e.g. sv for Swedish.
last_login datetime Last logged in date, e.g. 2015-08-28 or 2015-08-28T14:10:00Z. If the timezone is not given, the timezone will be defaulted to the timezone configured in the Custobar’s settings.
province string Name of the province.
street_address string Street address. Alternatively you may supply the address information using street_name, house_number and house_number_addition fields.
street_name string An alternative to using street_address. Name of the street without house_number or house_number_addition.
tags set of string Tags assigned for this customer.
vat_number string Value added tax id, if the customer makes VAT free purchases, e.g. FI123456.
zip_code string The postal area code depending on the country.

Company-specific fields

You may add additional fields, that are company specific by prefixing them with a company short name and a double underscore __, e.g. COMPANY__loyalty_level.

Company specific fields are searchable in the Custobar user interface.

Marking the customer as deleted

A customer may be marked as deleted by providing an extra field is_deleted with value true. This removes the customer from Custobar index and makes it unavailable to the marketing planners. A customer that has once been marked as deleted cannot be recovered by omitting the deleted flag or setting it explicitly false.

Example

To upload new or changed customer information, you may pass them to Custobar using a HTTP POST command, e.g.

curl -X POST -u USER -H "Content-Type: application/json" \
  --data-binary @customers.json \
  https://COMPANY.custobar.com/api/customers/upload/

The customer objects must be provided as a list, wrapped into a JSON object, with a key customers, as shown in the example below.

{
  "customers": [
    {
      "external_id": "3619490226",
      "first_name": "James",
      "last_name": "Carroll",
      "email": "james.carroll@example.org",
      "can_email": true,
      "phone_number": "+447757138957",
      "can_sms": true,
      "date_joined": "2015-11-23T13:11:23Z",
      "last_login": "2015-11-25T13:11:23Z",
      "language": "EN",
      "tags": ["kitchenware", "vip"],
      "COMPANY__customer_group": 1
    },
    {
      "external_id": "2319490132",
      "first_name": "Joshua",
      "last_name": "Stewart",
      "email": "josh@example.org",
      "street_address": "42 Red Lane",
      "date_joined": "2015-06-03T13:11:23Z",
      "last_login": "2017-10-15T03:01:13Z",
      "zip_code": "OX15 3PW",
      "city": "Epwell",
      "can_sms": false,
      "country": "GB",
      "language": "EN",
      "COMPANY__customer_group": 2
    }
  ]
}