Import Leads

What it is

Import Leads takes a spreadsheet saved as a CSV file and creates leads from it, hundreds or thousands at a time. For every phone number it has not seen before, it also creates a client record, so your customer list fills in at the same time.

It lives inside Settings›Developer Reference›Import Leads. It is not in the left sidebar. If you have an old bookmark to the standalone Import Leads page, it still works — Joby forwards it to the tab.

When to use it

• Moving in from another system. Load your completed job history so revenue and commission numbers cover the full year, not just the weeks since you switched.
• Fixing a batch of records. Export from Lead Reports, correct the data in a spreadsheet, then bring the corrected rows back in.
• Loading a purchased or partner list that already has phone numbers and addresses.

When not to use it:

• A handful of leads. Faster to use + New Lead on the Leads page.
• Correcting leads that already exist. The importer only creates new leads — it never updates an existing one.
• Contacts with no job history. Use the Import Clients tab beside it instead.

Before you start

Who can do this

Import Leads sits inside Settings, and Settings is admin-only. If you open Settings and do not see Developer Reference under the Admin group, you do not have access — ask an admin to run the import or to give you settings access.

What your file needs

• A .csv file. The upload box only accepts .csv. Save from Excel or Google Sheets using “CSV”.
• A heading row as the very first row.
• A phone number in every row. Phone is what Joby uses to match clients and to spot duplicates. Rows without a usable phone number are rejected.
• At least 11 columns. Rows with 10 cells or fewer are ignored without an error message. This is the single most common reason an import “does nothing”. Start from the sample file and you will never hit it.

Set these up first

• Lead statuses. Go to Settings›Lead Statuses and make sure every status wording used in your file exists. A status Joby does not recognize fails that row.
• Field workers, if your file assigns jobs or carries commission. Add them from the + button next to your company name in the sidebar → Field Worker. Names must match your file exactly.
• Lead custom fields are optional up front — you can create them during the import when you map an unrecognized column.

The column headings Joby reads

Easiest path: click Download Sample inside the importer, or go to Lead Reports›Export CSV, and use that heading row as your template. Headings are matched without regard to upper/lower case.

• Name — one column. The first word becomes the first name, everything after it becomes the last name.
• Phone — required. Reformatted to the standard +1… form.
• Email — optional.
• Address, City, State, Zip — full state names are shortened to two letters, and a 4-digit ZIP gets its leading zero back.
• Unit (also Apt, Apartment, Suite, Address 2) — the apartment or suite. It goes on the lead and on its client.
• Status — must match one of your lead statuses. Leave it blank and the lead comes in as Created.
• Sub Status — free text.
• Service Type (or Job Type) — free text.
• Ad Source, Call Group, Service Area — free text.
• Created At, Schedule Date, Closed Date — MM/DD/YYYY with an optional time, or YYYY-MM-DD.
• Total — the job amount. Dollar signs and commas are fine. Note that the importer also records this amount as fully paid.
• Field Worker — also accepted as Subcontractor, Technician, Tech or Contractor. Matched by exact name against your active field workers.
• Field Worker Cost (or Subcontractor Cost, or Parts) — subtracted from the total when commission is worked out.
• Commission Share — $50.00 for a flat dollar amount, 60% for a percentage, or - / blank to use that field worker’s usual percentage.
• Note — becomes the lead note.

Two things are deliberately not imported: the Office Agent column (imported leads are left unassigned) and the Lead Number column (every imported lead gets a fresh Joby number).

If your company renamed “Leads”, “Field Worker” or “Office Agent”, the tab name, the sample file and the headings all use your wording instead.

Step-by-step

1. Open the importer

Go to Settings›Developer Reference and click the Import Leads tab.

2. Get the sample file

Click Download Sample. You get leads-import-sample.csv with the exact heading row and two filled-in example rows. Replace the examples with your data and save it as CSV.

3. Upload

Click the large Click to upload CSV file box and choose your file. There is no drag-and-drop — use the button. While it reads the file the button says Parsing CSV….

4. Read the preview

A Preview (N leads) heading appears with the first 10 rows shown as Name, Phone, Status, Service Type, Total and Field Worker. Check the count first: if it is far lower than the number of rows in your spreadsheet, rows are being dropped — see Common mistakes.

5. Deal with extra columns

If your file has headings Joby did not recognize, an Extra columns box appears listing each one with a few sample values. For every column pick one of:

• — Skip this column — — the data is ignored (this is the default).
• An existing lead custom field, to drop the values into it.
• ➕ Create custom field… — opens a small window with Field name and Field type. The type is guessed from your sample values; change it if the guess is wrong, then click Create & map. The new field is created and selected for that column in one go.

6. Choose how duplicates are handled

Next to the import button there is an Allow duplicates checkbox.

• Left unchecked (recommended): a row is skipped if a lead already exists with the same phone number and the same address. Skipped rows are reported as failures with the reason “Duplicate”.
• Checked: every row is imported, creating a second lead even when a match exists.

7. Start the import

Click Import All Leads. While it runs you see a percentage bar, a batch counter, a rough time remaining, a line describing the current step (“Checking for duplicates…”, “Creating assignments…”), and a live tally of Imported / Failed / New Clients.

8. Pause, resume or cancel

• Pause stops after the current block and keeps everything already imported.
• Resume carries on from that point.
• Cancel stops the run. Leads already created stay — nothing is rolled back.
• You can also just close the page. When you come back and upload the same file, Joby tells you it found saved progress and the button changes to Resume Import.

How to check it worked

When you are done, click Import Another File to clear the screen and start the next file.

Common mistakes

Looking for Import Leads in the sidebar

It is not there. The path is Settings›Developer Reference›Import Leads. Old links to the standalone page redirect there automatically.

Nothing imports and there is no error

Almost always a file with too few columns — rows need more than 10 cells to be read at all. Build your file from Download Sample rather than typing a four-column list of names and phone numbers.

“Invalid phone number” on many rows

Every row needs a phone number Joby can read as a real US number. Watch for numbers Excel has turned into scientific notation, missing area codes, or a phone column that is actually empty for most rows.

“Unknown status …”

The wording in your Status column does not match any of your lead statuses. The error message lists everything that is accepted. Either correct the spelling in the spreadsheet, or add the status in Settings›Lead Statuses and re-run. Leaving the cell empty is also fine — those leads come in as Created.

Field workers came in unassigned

The name in your file must match an active field worker exactly (capitalization aside). “Osman J.” will not match “Osman Jobs”. Unmatched rows still import, but the lead has no field worker and will not appear in the commission report until you assign one.

Expecting existing leads to be updated

The importer only creates. Re-running a file either skips the matching rows (duplicate check) or creates second copies if Allow duplicates is checked. To change existing leads, edit them on the Leads page or use bulk actions there.

Everything landed on today’s date

Your Created At column was missing or in a format Joby could not read, so the import date was used instead. Use MM/DD/YYYY (time optional) or YYYY-MM-DD.

Revenue looks paid in full

Amounts in the Total column are recorded as collected. That is what you want for finished historical jobs, which is what this tool is designed for. Do not use it to load open jobs that still owe money.

Wondering why a column was ignored

Check the Extra columns box in the preview — anything Joby did not recognize is listed there, and it defaults to skip. Set it to a custom field if you want the data.