« Back to guides


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 E.164 String Phone number of a customer in a country prefixed format, e.g. +358101234567.
email RFC5322 String Email address of a customer, e.g. [email protected].

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 Bool Email marketing permission for given email address. Defaults to false if omitted.
can_post Bool Permission from the customer to receive messaging by postal mail. Defaults to false if omitted.
can_profile Bool Permission from the customer to be profiled. Segmenting is done always. Defaults to false if omitted.
can_sms Bool SMS marketing permission for given telephone number. Defaults to false if omitted.
date_joined ISO8601 String 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 String or Array of Strings A single mailing list as a string or an array of mailing list identifiers that the customer belongs to.
is_forgotten Bool 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 ISO8601 String 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 ISO3166-2 String Abbreviation for a country where the customer lives, e.g. SE (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 ISO639-1 String Primary communication language with the customer, e.g. SV (Swedish).
last_login ISO8601 String 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 Name of the street without house_number or addition.
vat_number String Value added tax id, if the customer makes VAT free purchases, e.g. FI123456.
zip_code String Postal code.

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.


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": "[email protected]",
      "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",
      "COMPANY__customer_group": 1
      "external_id": "2319490132",
      "first_name": "Joshua",
      "last_name": "Stewart",
      "email": "[email protected]",
      "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
Data Import