File Format - Customer / Customer Patch
Customer File Format
The first line of a Customer CSV file must be the header row.
A customer instance is a group of rows in the CSV file that are sequential and include the same required fields. Data relating to fields specified under Base Headers and Multi-Column Headers must be specified in the first row of a customer instance. Additional rows of a customer instance may only include fields specified under Multi-Row Headers.
Customer Patch File Format
The Customer Patch file allows users to PATCH partial data for a given customer. This means that the integrator does not need to populate every field in the .csv to update a single field. If an integrator wants to remove / set a field as NULL or empty string in Tulip, they can simply provide the string ‘SET_AS_NULL" in the appropriate field and that field will be emptied.
The customer patch file format is the same as the Customer File format and all rules should be followed when providing a Customer Patch file, with the exception of the following.
- Important Date (N) Type / Important Date Type - Must be a string which corresponds to
ImportantDateTypes.externalId.- Important date types can be fetched using the Get all important date types records endpoint
- Address (N) Type / Address Type - String Enum: one of
address-billing,address-Home,address-mailing,address-shipping,address-vacation - Social Profiles (N) Type / Social Profiles Type - String Enum: one of
whatsapp,wechat,line- Up-to-date values can be fetched using the Get all social profile type records endpoint
- Phone Numbers (N) Type / Phone Numbers Type - String Enum: one of
phone-home,phone-mobile,phone-work,phone-other - Loyalty Tier ID - Must be a string identifier and not an integer
Required Headers
To successfully import a customer CSV file, the following columns must be included in the header row:
| Column Name | Description | Type |
|---|---|---|
Customer ID (Required) | Identification string for a customer. Must be unique for every customer, otherwise overwritten. | string |
First Name | Customer’s first/given name | string |
Last Name | Customer’s last/family name | string |
Disabled | Whether or not the customer is disabled, send False if active. | boolean |
Image | URL of an image to use for this customer | string |
| Groups | See below | |
| Custom Attributes | See below |
Optional Headers
The following columns may be included in the header row:
| Column Name | Description | Type |
|---|---|---|
UUID | UUID of an existing customer. This can be used to target an existing customer that has not been assigned an externalId. This record import will fail if a customer with a matching UUID is not found. | string |
Groups
A group is a class of headers that relate to one another, and may allow for multiple pieces of information to be presented. For example, a customer can have multiple emails, addresses, phone numbers, and more.
Customer groups include:
- Emails
- Phone Numbers
- Addresses
- Important Dates
- Customer Tiers
- Social Profiles
- Privacy Regions
- Custom Attributes(Optional)
Emails
There are two ways that emails can be formatted in your CSV file: A Multi-Row Approach or Multi-Column Approach.
Multi-Row Approach
In this approach, one set of column headers is used alongside multiple rows of data. To allow for multiple rows of data, additional rows must include the same Required Headers fields.
Multi-Column Approach
In this approach, multiple sets of column headers may be used alongside one row (the first row) of a customer instance. To use these columns multiple times, an identifying number must exist for N and be unique for every new set of columns.
Columns from the Multi-Row Approach cannot be mixed with columns from the Multi-Column Approach in a CSV file for the Emails group.
The following columns may be included:
| Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|
Email ID | Email N ID | Identifier of an email. If any part of an Email is present then this field must be present | string |
Email (Required)* | Email N | The email address itself | string |
Email Disabled | Email N Disabled | Whether or not the email is disabled. Send False if active. | boolean |
Email is Primary | Email N is Primary | Whether or not this is the primary email address. If multiple email addresses are provided and primary is not specified, the first email address instance will be set to primary. | boolean |
Where N is some positive integer.
Note: * means the field is required if the group is being sent in the file.
Phone Numbers
There are two ways that phone numbers can be formatted in your CSV file: A Multi-Row Approach or Multi-Column Approach.
Multi-Row Approach
In this approach, one set of column headers is used alongside multiple rows of data. To allow for multiple rows of data, additional rows must include the same Required Headers fields.
Multi-Column Approach
In this approach, multiple sets of column headers may be used alongside one row (the first row) of a customer instance. To use these columns multiple times, an identifying number must exist for N and be unique for every new set of columns.
Columns from the Multi-Row Approach cannot be mixed with columns from the Multi-Column Approach in a CSV file for the Phone Numbers group.
The following columns may be included:
| Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|
Phone Number ID | Phone Number N ID | Identifier of a phone number. If any part of a Phone Number is present then this field must be present | string |
Phone Number(Required)* | Phone Number N | The phone number. Format: E.164. Must be E.164 Format for SMS functionality within Tulip | string |
Phone Number Type(Required)* | Phone Number N Type | Type of Phone Number: Home, Mobile, Work, etc (case-insensitive) | string |
Phone Number Disabled | Phone Number N Disabled | Whether or not this phone number is disabled | boolean |
Phone Number is Primary | Phone Number N is Primary | Whether or not this is a primary phone number. If multiple phone numbers are provided and primary is not specified, the first phone number instance will be set to primary. | boolean |
Phone Number Country ID(Required)* | Phone Number N Country ID | Country of this phone number (ISO 3166 Code Format) Integers will be resolved to internal identifiers | integer, string |
Where N is some positive integer.
Note: * means the field is required if the group is being sent in the file.
Addresses
There are two ways that addresses can be formatted in your CSV file: A Multi-Row Approach or Multi-Column Approach.
Multi-Row Approach
In this approach, one set of column headers is used alongside multiple rows of data. To allow for multiple rows of data, additional rows must include the same Required Headers fields.
Multi-Column Approach**
In this approach, multiple sets of column headers may be used alongside one row (the first row) of a customer instance. To use these columns multiple times, an identifying number must exist for N and be unique for every new set of columns.
Columns from the Multi-Row Approach cannot be mixed with columns from the Multi-Column Approach in a CSV file for the Addresses group.
The following columns may be included:
| Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|
Address ID | Address N ID | Identifier of this address. If any part of an Address is present then this field must be present | string |
Address (Required)* | Address N | Street number and name | string |
Address City (Required)* | Address N City | City name | string |
Address Suburb | Address N Suburb | Address line 2, typically used for Unit #, Apt#, etc. | string |
Address Zone ID (Required)* | Address N Zone ID | ID of the State/Province/County in ISO 3166-2:2020 format. Examples here Integers will be resolved to internal identifiers | integer, string |
Address Postcode (Required)* | Address N Postcode | Postal code of the address | string |
Address Country ID (Required)* | Address N Country ID | Country of the address (ISO 3166 Format) Integers will be resolved to internal identifiers | integer, string |
Address Phone Number | Address N Phone Number | Phone number relating to this address | string |
Address Disabled | Address N Disabled | Whether or not this address is disabled | boolean |
Address is Primary | Address N is Primary | Whether or not this is the primary address. If multiple addresses are provided and primary is not specified, the first address instance will be set to primary. | boolean |
Address Type (Required)* | Address N Type | Type of Address: Home, Work, etc (case-insensitive) | string |
Address First Name | Address N First Name | First/given name to be used with the address | string |
Address Last Name | Address N Last Name | Last/family name to be used with the address | string |
Where N is some positive integer
Note: * means the field is required if the group is being sent in the file.
Important Dates
There are two ways that important dates can be formatted in your CSV file: A Multi-Row Approach or Multi-Column Approach.
Multi-Row Approach
In this approach, one set of column headers is used alongside multiple rows of data. To allow for multiple rows of data, additional rows must include the same Required Headers fields.
Multi-Column Approach
In this approach, multiple sets of column headers may be used alongside one row (the first row) of a customer instance. To use these columns multiple times, an identifying number must exist for N and be unique for every new set of columns.
Columns from the Multi-Row Approach cannot be mixed with columns from the Multi-Column Approach in a CSV file for the Important Dates group.
The following columns may be included:
| Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|
Important Date ID (Required)* | Important Date N ID | Identifier of an important date. If any part of an Important Date is present then this field must be present | string |
Important Date (Required)* | Important Date N | The date in YYYY-MM-DD format | string:datetime |
Important Date Type (Required)* | Important Date N Type | Type of important date. 1 - Birthday and 2 - Wedding Anniversary | integer |
Important Date Title | Important Date N Title | Title of the important date | string |
Where N is some positive integer.
Note: * means the field is required if the group is being sent in the file.
Customer Tiers
There are two ways that customer tiers can be formatted in your CSV file: A Multi-Row Approach or Multi-Column Approach.
Multi-Row Approach
In this approach, one set of column headers is used alongside multiple rows of data. To allow for multiple rows of data, additional rows must include the same Required Headers fields.
Multi-Column Approach
In this approach, multiple sets of column headers may be used alongside one row (the first row) of a customer instance. To use these columns multiple times, an identifying number must exist for N and be unique for every new set of columns.
Columns from the Multi-Row Approach cannot be mixed with columns from the Multi-Column Approach in a CSV file for the Customer Tiers group.
The following columns may be included:
| Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|
Customer Tier | Customer Tier N | Customer tier value | integer |
Where N is some positive integer.
Social Profiles
There are two ways that social profiles can be formatted in your CSV file: A Multi-Row Approach or Multi-Column Approach.
Multi-Row Approach
In this approach, one set of column headers is used alongside multiple rows of data. To allow for multiple rows of data, additional rows must include the same Required Headers fields.
Multi-Column Approach
In this approach, multiple sets of column headers may be used alongside one row (the first row) of a customer instance. To use these columns multiple times, an identifying number must exist for N and be unique for every new set of columns.
Columns from the Multi-Row Approach cannot be mixed with columns from the Multi-Column Approach in a CSV file for the Social Profiles group.
The following columns may be included:
| Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|
Social Profile Disabled(Required)* | Social Profile N Disabled | Whether or not this social profile is disabled. Send False if active. | boolean |
Social Profile ID(Required)* | Social Profile N ID | Identifier of this social profile | string |
Social Profile Primary(Required)* | Social Profile N Primary | Whether or not this is the primary social profile | boolean |
Social Profile Type(Required)* | Social Profile N Type | Type of the social profile. 1 - whatsapp , 2 - wechat , 3 - line | integer |
Social Profile Value(Required)* | Social Profile N Value | Value of the social profile | string |
Where N is some positive integer.
Custom Attributes
There are two ways that custom attributes can be formatted in your CSV file: A Multi-Row Approach or Multi-Column Approach.
Multi-Row Approach
In this approach, one set of column headers is used alongside multiple rows of data. To allow for multiple rows of data, additional rows must include the same Required Headers fields.
Multi-Column Approach
In this approach, multiple sets of column headers may be used alongside one row (the first row) of a customer instance. To use these columns multiple times, an identifying number must exist for N and be unique for every new set of columns.
Columns from the Multi-Row Approach cannot be mixed with columns from the Multi-Column Approach in a CSV file for the Custom Attributes group.
The following columns may be included:
| Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|
Custom Attribute ID (Required)* | Custom Attribute N ID | Identifier of the custom attribute | string |
Custom Attribute Value (Required)* | Custom Attribute N Value | Value of the attribute | string |
Custom Attribute Language ID (Required)* | Custom Attribute N Language ID | Language of the attribute. Integers will be resolved to internal identifiers | integer, string |
Where N is some positive integer.
NOTE: Out of the box, Tulip leverages the following custom attributes for optin values:
- allow_email
- allow_mail
- allow_sms
- allow_call
- allow_whatsapp
- allow_line
- allow_wechat
- allow_kakaotalk
For instance, sending the below would allow the the associate to communicate with a client via whatsapp:
| Custom Attribute 1 ID | Custom Attribute 1 Value | Custom Attribute 1 Language ID | |
|---|---|---|---|
| allow_whatsapp | TRUE | en |
Privacy Regions
There are two ways that privacy regions can be formatted in your CSV file: A Multi-Row Approach or Multi-Column Approach.
Multi-Row Approach
In this approach, one set of column headers is used alongside multiple rows of data. To allow for multiple rows of data, additional rows must include the same Required Headers fields.
Multi-Column Approach
In this approach, multiple sets of column headers may be used alongside one row (the first row) of a customer instance. To use these columns multiple times, an identifying number must exist for N and be unique for every new set of columns.
Columns from the Multi-Row Approach cannot be mixed with columns from the Multi-Column Approach in a CSV file for the Custom Attributes group.
The following columns may be included:
| Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|
Privacy Regions | Privacy Regions N | Privacy Region associated to the customer | string, integer |
Where N is some positive integer.
Customer CSV Example
See the following Customer CSV sample.