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.
shop_id	string	Name or identifier for the shop that the customer belongs to.

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.

Adding and removing customers from mailing lists & tags

You can easily remove or add mailing lists / tags for customers by sending in the data with mailing_lists.add or mailing_lists.remove as shown in the example below

{
  "customers": [
    {
      "external_id": "3619490226",
      "first_name": "James",
      "last_name": "Carroll",
      "email": "james.carroll@example.org",
      "can_email": true,
      "tags.add": ["vip"],
      "mailing_lists.remove": ["kitchenware"]
    }
  ]
}

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
    }
  ]
}