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
Spec
The following table shows the accepted CSV columns for the customers entity. Note that any columns including N denote a dynamic integer. A column specified as Field N signifies that you can use columns Field 1, Field 2, …, Field N to allow for multiple values per record of the given field, similar to an array.
| CSV Header | Data Type | Group | Required | Description |
|---|---|---|---|---|
UUID | string | No | 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. | |
Customer ID | string | Yes | External identifier of the record | |
First Name | string | No | Customer’s first/given name | |
Last Name | string | No | Customer’s last/family name | |
Disabled | boolean | No | Whether or not the Customer is disabled | |
Image | string | No | URL of an image to use for this Customer | |
Email | string | Email Addresses | No | |
Email Disabled | boolean | Email Addresses | No | Whether or not the Customer is disabled |
Email ID | string | Email Addresses | No | External identifier of the record |
Email is Primary | boolean | Email Addresses | No | |
Email N | string | Email Addresses N | No | |
Email N Disabled | boolean | Email Addresses N | No | Whether or not the Customer is disabled |
Email N ID | string | Email Addresses N | No | External identifier of the record |
Email N is Primary | boolean | Email Addresses N | No | |
Email N Type | string | Email Addresses N | No | |
Phone Number ID | string | Phone Numbers | No | External identifier of the record |
Phone Number | string | Phone Numbers | No | The Phone Number (using E164 format) |
Phone Number Type | string | Phone Numbers | No | Type of this Phone Number |
Phone Number Disabled | boolean | Phone Numbers | No | Whether or not this Phone Number is disabled |
Phone Number is Primary | boolean | Phone Numbers | No | Whether or not this is a primary Phone Number |
Phone Number Country ID | integerORstring | Phone Numbers | No | Country ID of this Phone Number (externalId resolvable) |
Phone Number N ID | string | Phone Numbers N | No | External identifier of the record |
Phone Number N | string | Phone Numbers N | No | |
Phone Number N Type | string | Phone Numbers N | No | |
Phone Number N Disabled | boolean | Phone Numbers N | No | Whether or not the Customer is disabled |
Phone Number N is Primary | boolean | Phone Numbers N | No | |
Phone Number N Country ID | integerORstring | Phone Numbers N | No | |
Address ID | string | Addresses | No | External identifier of the record |
Address Type | string | Addresses | No | |
Address | string | Addresses | No | |
Address Zone ID | integerORstring | Addresses | No | |
Address Suburb | string | Addresses | No | |
Address Postcode | string | Addresses | No | |
Address City | string | Addresses | No | |
Address Country ID | integerORstring | Addresses | No | |
Address Disabled | boolean | Addresses | No | Whether or not the Customer is disabled |
Address is Primary | boolean | Addresses | No | |
Address Phone Number | string | Addresses | No | |
Address First Name | string | Addresses | No | Customer’s first/given name |
Address Last Name | string | Addresses | No | Customer’s last/family name |
Address N ID | string | Addresses N | No | External identifier of the record |
Address N Type | string | Addresses N | No | |
Address N | string | Addresses N | No | |
Address N Zone ID | integerORstring | Addresses N | No | |
Address N Suburb | string | Addresses N | No | |
Address N Postcode | string | Addresses N | No | |
Address N City | string | Addresses N | No | |
Address N Country ID | integerORstring | Addresses N | No | |
Address N Disabled | boolean | Addresses N | No | Whether or not the Customer is disabled |
Address N is Primary | boolean | Addresses N | No | |
Address N Phone Number | string | Addresses N | No | |
Address N First Name | string | Addresses N | No | Customer’s first/given name |
Address N Last Name | string | Addresses N | No | Customer’s last/family name |
Important Date ID | string | Important Dates | No | External identifier of the record |
Important Date | string | Important Dates | No | |
Important Date Type | integer | Important Dates | No | |
Important Date Title | string | Important Dates | No | |
Important Date N ID | string | Important Dates N | No | External identifier of the record |
Important Date N | string | Important Dates N | No | |
Important Date N Type | integer | Important Dates N | No | |
Important Date N Title | string | Important Dates N | No | |
Customer Tier | integerORstring | Loyalty Tiers | No | |
Customer Tier N | integerORstring | Loyalty Tiers N | No | |
Custom Attribute ID | string | Attribute Values | No | Attribute to be used as key in the key/value pair (externalId resolvable) |
Custom Attribute Value | string | Attribute Values | No | Value to appear in this key/value pair |
Custom Attribute Language ID | integerORstring | Attribute Values | No | Language ID for the language in which this value appears; use 0 if it is not localized (externalId resolvable) |
Custom Attribute N ID | string | Attribute Values N | No | |
Custom Attribute N Value | string | Attribute Values N | No | |
Custom Attribute N Language ID | integerORstring | Attribute Values N | No | |
Customer Preference Value ID | integer | Customer Preferences | No | |
Customer Preference Is Dislike | boolean | Customer Preferences | No | |
Customer Preference N Value ID | integer | Customer Preferences N | No | |
Customer Preference N Is Dislike | boolean | Customer Preferences N | No | |
Social Profile Disabled | boolean | Social Profiles | No | Whether or not the Customer is disabled |
Social Profile ID | string | Social Profiles | No | External identifier of the record |
Social Profile Primary | boolean | Social Profiles | No | |
Social Profile Type | integer | Social Profiles | No | |
Social Profile Value | string | Social Profiles | No | |
Social Profile N Disabled | boolean | Social Profiles N | No | Whether or not the Customer is disabled |
Social Profile N ID | string | Social Profiles N | No | External identifier of the record |
Social Profile N Primary | boolean | Social Profiles N | No | |
Social Profile N Type | integer | Social Profiles N | No | |
Social Profile N Value | string | Social Profiles N | No | |
Privacy Regions | string | Privacy Regions | No | |
Privacy Regions N | string | Privacy Regions | No |
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.
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:
| Required | Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|---|
| No | Email ID | Email N ID | Identifier of an email. If any part of an Email is present then this field must be present | string |
| Yes* | Email | Email N | The email address itself | string |
| No | Email Disabled | Email N Disabled | Whether or not the email is disabled. Send False if active. | boolean |
| No | 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:
| Required | Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|---|
| No | 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 |
| Yes* | Phone Number | Phone Number N | The phone number. Format: E.164. Must be E.164 Format for SMS functionality within Tulip | string |
| Yes* | Phone Number Type | Phone Number N Type | Type of Phone Number: Home, Mobile, Work, etc (case-insensitive) | string |
| No | Phone Number Disabled | Phone Number N Disabled | Whether or not this phone number is disabled | boolean |
| No | 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 |
| Yes* | Phone Number Country ID | 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:
| Required | Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|---|
| No | Address ID | Address N ID | Identifier of this address. If any part of an Address is present then this field must be present | string |
| Yes* | Address | Address N | Street number and name | string |
| Yes* | Address City | Address N City | City name | string |
| No | Address Suburb | Address N Suburb | Address line 2, typically used for Unit #, Apt#, etc. | string |
| Yes* | Address Zone ID | 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 |
| Yes* | Address Postcode | Address N Postcode | Postal code of the address | string |
| Yes* | Address Country ID | Address N Country ID | Country of the address (ISO 3166 Format) Integers will be resolved to internal identifiers | integer, string |
| No | Address Phone Number | Address N Phone Number | Phone number relating to this address | string |
| No | Address Disabled | Address N Disabled | Whether or not this address is disabled | boolean |
| No | 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 |
| Yes* | Address Type | Address N Type | Type of Address: Home, Work, etc (case-insensitive) | string |
| No | Address First Name | Address N First Name | First/given name to be used with the address | string |
| No | 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:
| Required | Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|---|
| Yes* | Important Date ID | 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 |
| Yes* | Important Date | Important Date N | The date in YYYY-MM-DD format | string:datetime |
| Yes* | Important Date Type | Important Date N Type | Type of important date. 1 - Birthday and 2 - Wedding Anniversary | integer |
| No | 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:
| Required | Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|---|
| No | 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:
| Required | Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|---|
| Yes* | Social Profile Disabled | Social Profile N Disabled | Whether or not this social profile is disabled. Send False if active. | boolean |
| Yes* | Social Profile ID | Social Profile N ID | Identifier of this social profile | string |
| Yes* | Social Profile Primary | Social Profile N Primary | Whether or not this is the primary social profile | boolean |
| Yes* | Social Profile Type | Social Profile N Type | Type of the social profile. 1 - whatsapp , 2 - wechat , 3 - line | integer |
| Yes* | Social Profile Value | 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:
| Required | Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|---|
| Yes* | Custom Attribute ID | Custom Attribute N ID | Identifier of the custom attribute | string |
| Yes* | Custom Attribute Value | Custom Attribute N Value | Value of the attribute | string |
| Yes* | Custom Attribute Language ID | 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.