Objective

Use Import/Export to add Staff in bulk to your instance of Coconut or perform a mass update on existing Staff records.

Steps

To perform a Staff import, download the .csv template file, complete the file as indicated, and import it into your instance of Coconut.

NOTE: Coconut currently supports a maximum import limit of up to 1500 Staff records at one time, although Coconut recommends ~500 records for optimal performance.

Download the .csv template file

From the navigation menu, click Import/Export
From Data Type, select Staff
Click Export Data to download a template in the supported format to use for the Staff import

NOTE: If you have not added a Staff to your instance of Coconut, the download will include only the column headers

When Export Data is clicked, an audit operation is performed on the Staff data that exists in your instance of Coconut. If this is not the first time you are adding Staff to your instance of Coconut and you have received an error message, skip ahead to Resolve formatting errors.

Complete the .csv file

For a sample Staff CSV, jump to the end of the article.

Navigate to where the downloaded .csv template is located on your device
Save the .csv template file to your desired location, based on your organization’s best practices and/or policies
Open the .csv file and complete based on the following parameters:

NOTE: Your .csv template may include additional fields depending on your Coconut package and what add-ons (if any) are included; furthermore, values included in the table below may or may not apply to your instance of Coconut, depending on your package

Field	Description	Required/Optional
external_id	A unique identifier that represents the Staff outside of your instance of Coconut	Required NOTE: If using the import to complete an update, leave this field as is and enter the info to be updated in the new_external_id field Otherwise, duplicate records will be created
new_external_id	Used to update the external_id to a new value (leave blank if no update required)	Optional NOTE: If using the import to complete an update, enter any updates to the user's external ID in this field and NOT the external_id field noted above Otherwise, duplicate records will be created
first_name	The Staff’s first name	Required
last_name	The Staff’s last name	Required
email	The Staff’s email address	Optional
bcc	The email address where communication sent to the Staff will also be forwarded	Optional
username	The Staff’s username	Required
cell_phone	The Staff’s cell phone number (digits only)	Optional
slug	An identifier (for example, the Staff’s name); the slug is what is appended to booking shortcut links instead of the Staff’s ID	Optional
visibility	A code that indicates the Staff’s availability to take an appointment 0 = Public 1 = Private 2 = Invite Only	Required
role_id	A code that corresponds to the Staff’s role in Coconut 5 = Contact Centre 10 = Staff 13 = Staff Plus 15 = Staff Advanced 20 = Manager 30 = Admin	Required
timezone	The Staff’s timezone (enter in PHP format; for reference: https://www.php.net/manual/en/timezones.php)	Optional
lang	A 2-character code indicating the Staff’s primary language (EN, FR, and ES are available for English, French, and Spanish respectively)	Required
job_title	The Staff’s job title	Optional
supported_locale	A 2-character code indicating the language(s) in which the Staff will support clients (EN, FR, and ES are available for English, French, and Spanish respectively)	Required
meeting_methods	A code indicating what meeting methods the Staff will use 1 = Business Location 2 = Phone Call 3 = Video Call 4 = Client Location	Required
group_external_id	The external ID for the staff group the Staff belongs to, if applicable (this is found by navigating to the Group field in a Staff’s profile)	Optional
video_integration_provider	The video provider that the Staff will use 1 = Microsoft Teams 2 = Zoom 3 = Coconut Connect 4 = Other	Optional

Import the .csv file

From the navigation menu, click Import/Export
From Data Type, select Staff
Do one of the following:

Drag and drop the completed .csv file onto the upload target
Click or select from your computer to upload the .csv file
Verify the .csv file is without errors by reviewing the confirmation message that displays upon upload

NOTE: If the Import button does not activate, it indicates there are errors in the .csv file; click Show Errors to review a list of row items in the .csv file that require correction, correct the errors, and re-upload the corrected .csv file (review Resolve formatting errors for more info)
NOTE: If the Import button activates, it indicates that the .csv file is formatted correctly; details of what will be imported display for your review
Click Import

The Staff are imported, and can be accessed by navigating to Staff.

Resolve formatting errors

For tips to resolve the most common formatting errors, please visit this article.

From the error message, click Show All
A details list displays; review the details to confirm what updates are required to which Staff
Complete the required updates by navigating to the existing Staff and updating required fields or updating within the .csv file

Resolve external_id errors

An external_id is required for each Staff. This identifier enables a database restore should any error occur during the import process. If the error message notes that external_ids are missing, they can be added by either auto-generating an ID or manually inputting an ID.

Auto-generate an external_id

From the error message that displays, click Generate external IDs
An external_id is automatically generated for each item missing the field

Example of an auto-generated external_id: coco_staff_da62fc03-986a-4184-a8aa-c44ccf108891

You can now continue with the import process.

Manually generate an external_id

From the error message that displays, click Show All
Note the Staff where an external_id is required
From the navigation menu, click Staff
Navigate to a Staff that requires updating

Click Profile
Navigate to the External ID field and click the Lock (🔒) icon to unlock the field
Click OK
Enter your desired External ID
Click Save
Repeat steps 4 and 5 for each Staff that requires updating

You can now continue with the import process.