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.
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
street_address String Street address.
zip_code String Postal code.
state String Name of the state.
city String Name of the city.
country ISO3166-2 String Abbreviation for a country where the customer lives, e.g. SE (Sweden).
language ISO639-1 String Primary communication language with the customer, e.g. SV (Swedish).
company String Name of the company behalf which the customer makes purchases.
vat_number String Value added tax id, if the customer makes VAT free purchases, e.g. FI123456.
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.
birth_date ISO8601 String Customer's date of birth formatted as year-month-day, e.g. 1991-06-14.

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. acme__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 PUT command, e.g.

curl -X PUT -u USER:PASS -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",
            "acme__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",
            "acme__customer_group": 2
       }
    ]
}