QuickStart Data Feed Specifications
CSV Format
CSV files must be well-formed. The requirements for CSV files are:
- Each record is one line (however, line-breaks can be embedded where necessary)
- Fields are separated by commas
- Fields with embedded commas must be delimited with double-quote characters.
- Fields with embedded double-quote characters must be delimited with double-quote characters, and the embedded double-quote characters must be represented by a pair of double-quote characters.
- Fields with embedded line breaks must be delimited by double-quote characters.
- Fields may always be delimited by double-quote characters, whether necessary or not.
*Leading and trailing spaces in any field will be trimmed prior to processing
Header Validation
The first line of the file (the Header) specifies how data in the file maps to client employee data.
Fields defined in the Header:
- can be in any order
- can be empty; if empty, no data from this field will be used as part of the feed
- if non-empty, must be unique; no field names can be repeated
- must map to either one of the standard field names, or one of the custom field names for the client
- can specify the primary key for the feed by prefixing a field name with '*'; if no primary key is specified, we default to 'email'. If there is no field with the name 'email', the feed cannot be processed
Field Names
Standard Fields
- address1: the first address line
- address2: the second address line
- address3: the third address line
- city: the city
- delete: whether or not to delete the record. Records will only be deleted if the value is 'true'; any other value will be ignored. Case does not matter; for example, "TRUE", "true", "True", or "tRuE" will all be treated as a deletion record.
- email: the volunteer's email address. If specified, email addresses must be unique.
- region: the home state or region or province. If the country is 'US', we test this against 2-character (US Postal Service codes) and full-name US states. If country is not US, this will populate into the Province field on the Profile page - you don't need a separate province column.
- country: the home country, in standard 2-character (ISO_3166-1 alpha-2), 3-character (ISO_3166-1 alpha-3), or English full-name form. If this is not specified, we default to US.
- firstname: the volunteer's first name
- lastname: the volunteer's last name
- password: a temporary password for the account
- phone: the phone number
- postalcode: the postalcode. If the country is 'US', we make sure that the given postalcode is nominally
- valid – we assume values with fewer than 5 digits are meant to have leading zeroes, and we validate that the postalcode is 5 digits (Only '12345' or 5 digits is acceptable).
All standard fields have a limit of 50 characters, except postalcode (30) and email (100).
Custom Fields
Each client can specify their own set of custom fields. The only requirement for QuickStart is that custom field names cannot conflict with standard field names. Custom fields must be manually added to the Client's service prior to running a feed that references that field.
All custom fields have a limit of 500 characters.
