Import Clients

What it is

Import Clients takes a spreadsheet saved as a CSV file and turns each row into a client in your Joby address book. It is built for the one-off job of getting your existing customer list in — from an old system, a phone export, or a spreadsheet someone in the office has been keeping for years.

You find it at Settings›Developer Reference›Import Clients. It is not in the left menu. If you have an old bookmark to a standalone Import Clients page, it still works — Joby forwards it to this tab.

The screen walks you through three stages, in order:

Three things happen automatically while it runs, which is most of the value:

When to use it

• Moving in from another system. Export your contacts from your old CRM, phone system or accounting package and load them here so your team can search, call and text them from day one.
• Loading a list you already keep in a spreadsheet. The office address book, a maintenance-contract list, a route list — anything with names and phone numbers.
• Adding a purchased or partner contact list before a marketing campaign. Tag the whole batch in your spreadsheet first, and you can filter to exactly that group afterwards.

When not to use it:

• A handful of contacts. Faster to click New Client on the Work›Clients page.
• Fixing clients that already exist. This tool only ever creates. It does not look for matches and it does not update anything — re-importing the same file gives you a second copy of every client. Edit existing clients on the Clients page instead.
• Contacts with job history you want to keep. If your spreadsheet has past jobs, amounts, statuses or field workers in it, use Settings›Developer Reference›Import Leads instead. That tool creates the job and the client together.

Before you start

Who can do this

Import Clients sits inside Settings, and this part of Settings is admin only. Office agents and field workers cannot reach it, no matter what their role allows elsewhere — the Clients permission on a role controls the Clients page, not the importer.

Open Settings and look under the Admin group for Developer Reference. If it is not there, you are not an admin — ask one to run the import for you.

What your file needs

• A .csv file. The picker only accepts .csv; anything else gets “Please upload a CSV file”. In Excel or Google Sheets choose Save as → CSV.
• A heading row as the very first row. Joby reads row 1 as your column names and everything below it as data. Completely blank rows are ignored.
• A name or a company on every row. A row with no first name, no last name and no company is dropped quietly — it never even reaches the count.
• A phone number or an email on every row. Joby will not store a client it has no way of reaching. Rows missing both are counted and reported to you before you import, not silently swallowed.

Column headings do not have to be exact

You are never forced to rename your columns. Joby guesses a mapping from your headings and you fix anything it got wrong in the next step. The guesses it makes:

• First name — “First name”, “First”, “Fname”
• Last name — “Last name”, “Last”, “Lname”, “Surname”
• Full name (split into first + last) — “Full name”, “Name”
• Company — “Company name”, “Company”, “Business name”, “Organization”
• Phone — “Mobile”, “Cell”, “Primary phone”, “Phone number”, “Home phone”, “Work phone”, “Telephone”, “Phone”
• Second phone — “Second phone”, “Secondary phone”, “Alt phone”, “Other phone”, “Phone 2”
• Email — “Email”, “E-mail”
• Address — “Address”, “Street”
• City, State (also “Region”, “Province”), Country
• Zip / Postal code — “Zip”, “Zipcode”, “Postcode”, “Postal code”
• Lead source — “Lead source”, “Source”
• Customer type — “Customer type”, “Client type”, “Type”
• Note — “Note”, “Notes”, “Comment”, “Comments”
• Tags — “Tag”, “Tags”, “Labels”

Upper and lower case do not matter, and a heading only has to contain the word — “Customer Email Address” still lands on Email. Anything Joby cannot place is left on — Skip — for you to deal with.

Set these up first (optional)

• Client custom fields, if your list has columns Joby has no home for — “Gate code”, “Referred by”, “Account number”. Add them in advance at Settings›Custom Fields›Clients (there is also a Custom fields shortcut button on the Work›Clients page), or create them right inside the importer while you are mapping.
• Nothing else. Tags do not need to exist first — the import creates any it does not recognise. Lead source and Customer type are plain text, so no setup is needed there either.

Step-by-step

1. Open the importer

Go to Settings›Developer Reference and click the Import Clients tab. You should see a card headed Import Clients from CSV.

2. Get the template

Click Download Template. You get a file called clients-template.csv containing the heading row Joby expects plus one filled-in example row:

First Name, Last Name, Company Name, Phone, Second Phone, Email, Address, City, State, Zip, Country, Tag, Lead Source, Customer Type, Note

Delete the example row, paste your own data in, and save it as CSV. Using the template is the fastest route because every column maps itself correctly.

3. Choose your file

Click Choose CSV and pick the file. There is no drag-and-drop — use the button. The file name appears beside it once selected. Then click Next: map columns; it briefly reads Reading… while Joby opens the file.

4. Map the columns

A line at the top confirms what was found: “Found 12 columns and 843 rows.” Check that row count against your spreadsheet before you go any further.

Below it is a table with three columns — CSV column (your heading), Sample (the first few real values from that column, so you can tell what it actually holds) and Map to. Work down the Map to dropdowns. Each one offers:

• — Skip this column — — the data is thrown away. This is the default for anything Joby did not recognise.
• Standard fields — the built-in client fields listed above. Each one can only be used once.
• Custom fields — your existing client custom fields. This group only appears if you have some.
• ➕ Create custom field… — see the next step.

One special option is worth knowing: Full name (split into first + last). Map a single “Name” column to it and Joby puts the first word in First name and everything after it in Last name. It is only used when you have not mapped First name or Last name separately.

5. Create a custom field, if you need one

Pick ➕ Create custom field… on a column and a small Create custom field window opens with two boxes:

• Field name — pre-filled with your CSV heading. Change it to whatever you want your team to see, for example Referred by.
• Field type — one of Text, Long text, Number, Dropdown, Date or Checkbox (Yes/No). Joby guesses this from your sample values and tells you so: “Auto-detected from the sample values — change if needed.”

Click Create & map. The field is created for your whole company and the column is pointed at it in one go. From then on it also shows up on the client form and in the Clients filters.

6. Read the warnings

Three messages can appear under the table, and they matter:

• “Map at least a Name (or Company) column to continue.” In red. The import button stays switched off until you map First name, Last name, Full name or Company.
• “No phone or email mapped — every row will be skipped (clients require a contact).” In amber. You mapped a name but no way to reach anybody, so nothing would come in.
• “N rows will be skipped — no phone or email…” In amber, with the exact count. Those particular rows have neither. Fix them in your spreadsheet and re-upload if you need them, or accept the loss and carry on.

Finally, check the line that reads “Ready to import N clients.” That N is the real number — rows with no name and no company, and rows with no contact details, have already been taken off it.

7. Run the import

Click Import N clients. The button changes to Importing… and a progress bar with a percentage appears. Joby works through the file in blocks of 250, so a big list moves in visible jumps.

How to check it worked

When you are happy, click Import Another File to clear the screen and start the next one. Note that inside the Settings tab there is no “Go to Clients” shortcut — use the left menu.

Common mistakes

Looking for Import Clients in the left menu

It is not there. The path is Settings›Developer Reference›Import Clients. Old links to the standalone page redirect there on their own.

Running the same file twice

This is the big one. There is no duplicate check, so a second run creates a second copy of every client. If an import half-finished, do not simply re-run the whole file — remove the rows that already came in first.

“Ready to import” is far lower than your row count

Rows are being dropped for one of two reasons:

• No name and no company. These vanish without a message. Sort your spreadsheet by name and check for blanks at the bottom.
• No phone and no email. These are counted for you in the amber warning above the button.

The phone column was not picked up

If your file has two phone-ish columns — say “Mobile” and “Phone” — the first match becomes Phone and the leftover one becomes Second phone. That is usually right, but check the Sample column and swap them in the dropdowns if Joby guessed backwards. If a row's main phone is empty but the second one is filled, Joby promotes the second number to be the primary rather than dropping the client.

Zip codes and phones turned into nonsense in Excel

Excel likes to treat these as numbers. A zip saved as 62701.0 is repaired automatically, but a phone number turned into scientific notation (1.23457E+10) is not recoverable. Format those columns as Text in your spreadsheet before saving as CSV.

All the tags came in as one long tag

Separate multiple tags in a single cell with a comma, a semicolon or a pipe — VIP;Repeat or VIP, Repeat. A slash or the word “and” is treated as part of the tag name. Straight quotes around a tag are stripped for you.

Half the columns say “— Skip —” and you did not notice

Skip is the default for anything Joby could not place, and skipped data is gone for good — it is not stored anywhere for later. Scroll the whole mapping table before you press import, especially on a wide file.

A few rows failed while the rest came in

That is by design: when a block of rows is rejected, Joby narrows it down until only the genuinely bad rows are left out, so one broken row cannot cost you the other 249. The result screen tells you how many failed. Track them down by comparing your spreadsheet against the Clients page, fix them, and import just those rows in a small follow-up file.

Clients came in but their addresses did not

A location is only created when a row has at least one of address, city, state or zip mapped and filled in. If the pop-up mentioned locations that could not be created, the clients themselves are fine — add the addresses on each client's Addresses tab, or fix the file and re-import to a small test group first.

Expecting jobs, revenue or history to appear

This importer creates contact records only. No leads, no estimates, no invoices, no payments. If your spreadsheet has job history in it, that belongs in Settings›Developer Reference›Import Leads.

Everything came in as US

If you did not map a Country column, new locations are saved as US. Map the column if you work across borders. Phone numbers written without a country code are also treated as US/Canada numbers — write them as +44… style if they are not.