Importing your data

The importers under Settings, Imports bring existing staff, clients, returns and delivery locations into Journey from a spreadsheet. This page covers the order to do it in, the exact values Journey expects in each column, how to read the result screen, and the limits worth knowing before you start rather than halfway through.

If you are moving a whole practice across, read the two sections directly below first. They prevent most of the trouble firms run into.

Import in this order: staff, then clients, then returns

The importers depend on each other, in that direction:

Returns are matched to clients, so the clients have to exist first. A return whose client is not found fails with "Client not found. Import clients first."
Returns can name a preparer by email, and that preparer has to be a member of the firm already, which means staff first.

Delivery locations are your firm's offices. They do not depend on anything, but if your client file has an Office column, import the delivery locations before the clients, because each client's office has to exist already.

Check the file before you import it

Nothing is written until you press Import, and both importers check your whole file first. The check reads every row, matches each one against your existing records exactly as a real import would, and reports what would happen, without writing anything.

Clients: the check runs by itself when the preview opens, and each row shows its result: would create, would update, would skip, or would fail with the reason. Import stays grayed out until the check has seen the values you are about to import, so after you change anything on the preview, press Check again.
Returns: press Check without importing on the preview screen. If the result looks right, one more click imports the same file for real, with no need to upload or map it again.

Use it on the whole book, not a slice. It is the fastest way to find a wrong column mapping, a tier or client type spelled a way Journey does not accept, or rows that would be skipped as duplicates.

A clean check means your file is consistent with the data you already have. It does not promise that nothing can go wrong, because a few things are only decided when a row is actually saved. For returns that includes who each one is assigned to and whether it is escalated, since those are worked out at the moment the return is created.

If something does go wrong anyway, importing the same file again is safe. Journey detects duplicates and will skip or update rather than create a second copy.

File types: CSV or Excel

The clients and returns importers read:

Excel workbooks (.xlsx). Journey reads the first visible sheet, and only the values stored in it: formulas are not run (a formula cell reads as the result Excel last saved), and macros are never opened. Older .xls files, and password-protected workbooks, need saving again as .xlsx or CSV first.
CSV and text files (.csv, .tsv, .txt) separated by commas, semicolons or tabs, in UTF-8, UTF-16 (Excel's "Unicode Text") or the older Windows encoding. Journey works out which, so accented names come through intact.

If your file has a title or a note above the column names, Journey finds the row with the column names and says which row it used; the Up and Down buttons next to it pick a different row if it guessed wrong. Rows with only one filled cell (a title, a note, "Total clients: 12") are left out, and the screen says how many and shows what they were. On the clients importer, a row with only a client's name is kept as long as that column is chosen for Full name, unless it reads as a total or a label (it has a colon, or starts with "Total"). Two columns with the same name are kept apart, as "Phone" and "Phone (2)". Files are limited to 10 MB.

The staff and delivery locations importers still read .csv only, as UTF-8: in Excel, choose "CSV UTF-8 (Comma delimited)" when saving.

Quoted fields, commas inside quotes, and line breaks inside quoted cells are all handled correctly, so you do not need to strip commas out of company names.

Matching your columns

After you upload a client file, Journey suggests a column for each field from the column headings, and you can change any of them before you continue. It recognizes the usual spellings from practice management exports and spreadsheets, such as "Contact name", "Account name", "State/Province", "Postcode" and "Cell Phone". Capitals, spaces and punctuation in a heading do not matter. A heading ending in a question mark, such as "Email?", is treated as a yes/no question and not suggested.

First and last name in separate columns. Full name can be built from a first name column and a last name column, joined with a space. Journey picks both when it recognizes them. They are used when Full name is not mapped, or when a row's Full name cell is blank. Journey needs both columns picked to do this. On a row where only one of the two cells is filled in, that one is used on its own as the full name, and the result list shows that row under that one name.
More than one phone column. When your file has several phone columns, Journey picks them in this order, whatever order they are in your file: the main phone column, then mobile or cell, then home, then work or business. The first becomes Phone and the others are listed under it as fallbacks, and you can add, change or remove them. A fallback is used only when every column above it is blank on that row, so a client whose number is only in a Mobile column still gets it. That also means a work or business number can end up as the client's phone, which is the number Journey texts once the client has agreed to text messages. If that matters, map Phone to the number you want texted and remove the fallbacks you do not want used.
One address, never two mixed. If your file has both an address and a mailing address, Journey keeps the address lines, city, state and ZIP from the same one: it uses the mailing columns for them only when the first address line is the mailing one.
State is only suggested when the column holds states. Some exports have a column called State that means an account status, such as Active. Journey suggests a State column only when most of its values are US states, and leaves it for you to choose otherwise.
Nothing changes your values here. Matching decides which column feeds which field. Name order, capitals and address formats come through as they are in your file, unless you accept a proposed change on the preview (below).

The clients preview: every row, and every proposed change

After you match your columns, the preview lists your rows as they will be sent, with the check's result for each one. It opens on the rows that need a decision: any row that would fail, and any row where Journey proposes a change. You can also show only the rows that would fail, the ones you changed, or all of them.

Journey proposes changes for common clean-up, and changes a value only when you accept it:

Proposed changes are ones it is sure of: "SMITH, JANE" becomes "Jane Smith", "Fla." becomes FL, a ZIP that lost its leading zero gets it back, a phone number is written as (555) 010-0100, and a whole address typed into the street column is split into street, city, state and ZIP. Each shows the old value crossed out above the new one. Accept it, or Keep as in file. Accept all accepts every proposed change at once.
Values to look at are ones it is unsure of, with the reason: a business name in capitals (it cannot tell USAA from a word), a name like "Lee, Kim", a state Journey does not cover. Where it has a reading, Use suggestion applies it. Accept all never touches these; each one needs you to look at the row.
Some changes only make sense together, so they move together. With Skip duplicates, "SMITH, JANE & JOHN" becomes "Jane Smith" and adds "Spouse: John" to Notes; a split address fills street, city, state and ZIP at once. Undo, or editing any of them, undoes all of them.

With "Update existing clients", Journey does not add a spouse to a blank Notes. Updating replaces an existing client's notes whenever a row carries any, and the preview cannot see what those notes say, so a spouse note there could wipe notes someone typed into Journey. Instead, Notes shows a value to look at naming the spouse, and the name becomes a suggestion (it would leave the spouse out). Add the spouse by hand. If your file does carry notes for that row, those notes replace the client's notes either way, so the spouse line is still offered as a change. Switching between Skip and Update recalculates only these spouse proposals: a name and spouse note you accepted under the other choice has to be decided again, and every other change you accepted stays accepted.

Updating also replaces an existing client's address. Every address field a row carries replaces the client's own. So with Update existing clients, accepting a split address replaces the client's street, city, state and ZIP with the ones read from your file's address line, where leaving the split alone replaces only the street line, with the whole address in it. A part the split leaves blank, such as a ZIP when the address line had none, leaves the client's own value unchanged.

Click any value to edit it; press Enter to save or Escape to cancel. The box opens on the value shown. Undo puts back what your file had. A proposal you leave alone changes nothing: the cell is imported as the preview shows it, your file's value or your own edit. A column only appears in the preview if you mapped it, or if a proposed change would fill it, such as Notes for a spouse.

If you go back and change the column mapping, your changes stay on the columns you did not remap. Changes on a remapped column are cleared, and Journey says how many before you continue.

After any change, press Check again so the check sees the values you are about to import. Your edits live only on this screen: the file on your computer is not changed, and the error report after an import holds your original rows.

Reading the results

Every row lands in exactly one of four buckets, and the list underneath the counts tells you which, per row, with the reason:

Created. A new record was added.
Updated. An existing record was matched and changed. Only appears if you chose "Update existing clients" on the preview screen.
Skipped. A duplicate was found and left alone. The reason names what matched.
Failed. The row was rejected. The reason says why, in plain terms.

If anything failed, a Download error report button appears. That file is your original rows, only the failed ones, with an extra Error column. Fix them in that file and import it on its own rather than re-running the whole book.

How Journey decides something is a duplicate

For clients, by email, case-insensitively. If a row has no email, by full name instead. Email is the stronger signal, so a row that has one is never matched on name alone, which is what stops two different people who happen to share a name from being merged.

Two situations get reported differently, on purpose:

The client already existed before this import. You control what happens with the "When a client already exists" choice on the preview screen: skip, which is the default and leaves the existing record untouched, or update, which overwrites its details with the values in your file.
The client appears twice in the file you just uploaded, usually because your export listed someone twice. Journey sends your file in batches of 100 rows, and it spots this within a batch: the first row is created, the later ones are skipped, and the reason tells you which row won, for example "duplicate email earlier in the same import batch: pat@example.com, first used on row 1". That happens regardless of the skip or update choice. If the two rows land in different batches, the later one finds the client the earlier one just created and is treated as an existing client, so your skip or update choice applies to it, and a check (which saves nothing) reports both rows as would create. Removing repeats from the file before importing avoids all of this.

For returns, a duplicate is the same client, return type and tax year.

The values Journey expects

Capitalization and surrounding spaces never matter in any of these. What matters is that the word itself is one Journey recognizes. Anything it does not recognize fails that row and says so, rather than being quietly replaced with a default.

Client tier: platinum, gold, silver, standard. Leave it blank if you do not use tiers.

Client type: one of these, or blank for individual:

Write	Journey shows
individual	Individual
schedule_c	Sole proprietor (Schedule C)
s_corp	S corporation
partnership	Partnership
c_corp	C corporation
estate_trust	Trust or estate
non_profit	Non-profit
business	Business, type not set

The words in the right-hand column are accepted too, so "S corporation" works as well as s_corp. Use business only when you do not know the entity type yet: Journey shows those clients as "Business, type not set" until someone picks the real one.

For anything other than an individual, put the business name in company_name and the contact person in full_name. Journey then displays it as "Company Name (Contact Person)". A sole proprietor's business name is optional.

Practice management exports often use other words here: LLC, S-Corp, trust, corporation. Journey does not read those, and it will not guess. A row using one fails and names the word it did not recognize, so find and replace that column with one of the values above before you import.

Services: comma-separated. Write any of Tax preparation, Bookkeeping, Advisory or Payroll, or one of your firm's own service type names from Settings. A fixed Service links the client through the service type your firm has set to count as it; if none has been set yet, that name is skipped.

Office: the office of your firm that serves the client, written as one of your delivery location codes or names from Departments, Delivery Locations (capitalization does not matter). Leave it blank for no office. A row naming an office your firm does not have fails and names it. New returns, requests and tasks for the client start with its office, and so do returns you import for that client.

Watch the Client type mapping if your file has a column called "Type". In most practice management exports, including Drake, "Type" is the return type: 1040, 1120S, 1065. It is not a client type. Journey will not map it to Client type for you, so that column stays unmapped and every client comes in as an individual unless you say otherwise.

If your file records the entity only through the return type, you can derive the client type from it in your spreadsheet before importing. Add a column, fill in the client type that matches each row's return, and map Client type to your new column.

Keep the Type column in the file. The returns importer uses it, so it is what you need if you also bring last season's returns across.

Staff role: general_manager, manager, supervisor, staff. Owner cannot be assigned by import. Adding an owner stays a deliberate one-at-a-time action, so create those from the Staff page.

Return type: 1040, 1040-SR, 1120-S, 1065, 1120, 990, 941, 940, 1041, other. Hyphens and spaces are ignored, so 1120S, 1120 S and 1040SR all arrive correctly.

Return status: either a pipeline status, which is received, waiting_on_client, in_preparation, in_review, ready_for_client_signature, ready_for_filing, filed or completed, or one of the friendlier names Journey also accepts: documents, in_progress, review, signature, filing, complete. Leave it blank and the return starts at received, which is normally what you want for a book you are bringing in fresh.

Limits

Clients and returns: no practical row limit. These two send the columns you mapped to the server in batches of 100 automatically, so a file of several hundred rows is fine and does not need splitting. A larger file simply takes longer, and the results list still shows every row. Columns you leave unmapped, such as a Social Security number or date of birth column, are not sent to Journey.
Staff and delivery locations: 500 rows per file. These two send the whole file in one go. A larger file is rejected before anything is written, so nothing is half-imported, but you do have to split it yourself.
One file at a time, per importer.
Only owners and general managers can import clients, returns and delivery locations. Staff imports additionally allow managers.

Known limitations

These are current, deliberate gaps rather than faults, and knowing them beforehand saves working them out the hard way:

A check cannot see everything. Covered above. It runs the same matching a real import does, so it catches anything to do with your file or your existing records, but not the handful of things decided at the moment a row is saved. Staff and delivery location imports have no check at all.
Nothing warns you in advance that a file is too long. You find out at upload.
An unmatched preparer does not stop the import. If preparer_email does not match a member of the firm, the return is still created, unassigned, and the row says "preparer not found, left unassigned". Assign it afterwards from the Returns page.
Automations still run on imported records. A rule that assigns new returns will assign imported ones too, so a return can arrive unassigned per the import and show an assignee moments later. Both are correct, at different moments.
Delivery locations have no skip option. Re-running the same file reports every row as a duplicate failure instead of skipping. Import them once.
A staff row whose email already has a Journey account fails. This includes someone who already belongs to another firm. Add those people from the Staff page instead.
The returns preview does not validate. It shows your first five rows so you can check the column mapping, and it will happily display a value that is going to be rejected until you press Check without importing. The clients preview checks every row as it opens.

If a row fails with something not covered here, the error text is the actual reason it was rejected. Download the error report, and if it still does not make sense, use Contact support and paste the distinct values from the Error column. Those are Journey's own messages and they describe the problem completely.

Please do not send the error report file itself. It is your original spreadsheet with an extra column, so it carries your clients' names and contact details, and we do not need any of that to work out why a row was rejected.