Bulk work order import format specification

Question

We are preparing to migrate approximately 12,000 historical work orders from our legacy system into FieldPulse. I have reviewed the Bulk Importing Inventory via CSV documentation, but I am seeking clarification on the specific schema requirements for work order imports, as the available documentation appears to focus on inventory rather than work order entities.

Specifically, I would appreciate confirmation on the following points:

Required vs. optional fields : Which fields are mandatory for a successful import? I assume work_order_number , customer_id (or customer_email ), and scheduled_date are required, but I would like explicit confirmation.

Date/time formats : The documentation references ISO 8601, but does not specify whether timezone offsets are supported (e.g., 2025-09-22T14:00:00-04:00 ) or if all timestamps must be normalized to UTC.

Status mapping : Our legacy system uses non-standard status values (e.g., "Dispatched," "In Progress," "Awaiting Parts"). Is there a defined mapping to FieldPulse's internal status enum, or must we pre-transform these values?

Technician assignment : Can we assign technicians via technician_email at import time, or does this require a separate API call post-import?

Custom fields : We have approximately 40 custom fields defined in our legacy system. Are these supported in the bulk import, and if so, what is the expected column naming convention (e.g., custom_field_{id} or cf_{name} )?

Validation and error reporting : Does the import process support partial success (i.e., importing valid rows while reporting errors for invalid rows), or is it atomic? What is the granularity of error reporting—row-level, field-level, or batch-level?

Rate limiting and throughput : Are there documented limits on import file size (rows or bytes) and concurrent import operations?

Additionally, I would like to understand whether there is a sandbox or staging environment where we can validate our transformation pipeline before performing the production import. Our migration window is constrained, and we would prefer to avoid iterative correction cycles against production data.

I have attached a sample of our transformed data structure below for reference. Any clarification on the above points would be greatly appreciated.

work_order_number,customer_email,scheduled_date,status,technician_email,custom_field_site_id,custom_field_equipment_type
WO-2019-0042,customer@example.com,2019-03-15T09:00:00,Dispatched,tech@company.com,SITE-442,HVAC-Commercial

Eli Torres (Staff) · Accepted Answer

Hey Omar, great questions—this is exactly the level of detail that makes migrations go smoothly. Let me work through these one by one.

Required fields : You've got the core three right. Minimum viable row needs work_order_number , customer_email ( customer_id also works if you've already synced customers), and scheduled_date . Everything else is optional, though I'd recommend including status so you're not left with 12,000 "Draft" orders to update later.

Date formats : Timezone offsets are supported and encouraged—much better than assuming UTC and having 6am jobs show up at the wrong time. The parser handles both 2025-09-22T14:00:00-04:00 and the Zulu format. If no offset is provided, it assumes the account's configured timezone, which has caused some fun surprises in the past.

Status mapping : This is where it gets tricky. FieldPulse's internal enum is draft , scheduled , dispatched , in_progress , completed , cancelled , and on_hold . Your "Dispatched" maps cleanly, "In Progress" → in_progress , but "Awaiting Parts" doesn't have a direct equivalent. Most folks map that to on_hold with a note in the internal comments. There's no automatic fuzzy matching—you'll need to pre-transform.

Technician assignment : Yes, technician_email works at import time, but the technician needs to exist in the system first. The importer won't auto-provision users. If you have multiple technicians per order, use technician_emails (plural) with comma-separated values.

Custom fields : Supported, but the naming convention is custom_{field_key} , not ID-based. You can find the field keys under Settings → Custom Fields → Work Orders —they're the URL-safe slugs, not the display names. So if your field is named "Equipment Type," the column might be custom_equipment_type or custom_equipment_type_2 depending on duplicates.

Validation : Partial success with row-level error reporting. You'll get a downloadable CSV with an __import_error column appended. Atomicity is per batch, and batches are chunked at 500 rows. So if row 501 fails, rows 1-500 still commit.

Limits : 50,000 rows or 10MB per file, whichever comes first. No hard limit on concurrent imports, but we throttle to 2 per account to avoid database contention. If you need more throughput, open a ticket and we can coordinate.

Sandbox : We don't have a public sandbox environment for imports specifically, but I'd recommend creating a trial account under a different email domain for validation. The importer behaves identically, and you can blow it away after testing. Just don't use your production customer/technician emails or you'll get deduplication weirdness.

Your sample looks structurally sound. One heads up: if that 2019 date is representative, check your account's data retention settings—importing very old orders can trigger archival rules you weren't expecting.

Full schema reference is at Bulk Importing Inventory via CSV (yes, the work order section is buried in there—we're fixing that). Also worth reading Duplicate Inventory Items Created During Import for common pitfalls that apply to work orders too.

Leo Nakamura · Answer

Supplemental notes from a recent migration:

Custom field keys are case-sensitive and underscore-normalized. "Equipment Type" becomes equipment_type , but if you created it as "Equipment-Type" originally, the key is equipment_type anyway—hyphens become underscores. Verify in the UI. 
 Technician email matching is case-insensitive but trailing-space sensitive . Strip whitespace in your transform. 
 Date parsing accepts YYYY-MM-DD without time, assumes 00:00:00 in account timezone. We used this for historical jobs where exact time was lost.

Documentation gaps: Using the FieldPulse API has a more complete field reference than the import docs, oddly.

Devon Marsh · Answer

Heads up on a gotcha we hit: the importer validates customer existence by email at import time, but if you have duplicate customers with the same email (e.g., from previous partial migrations or manual entry), the import will fail with AMBIGUOUS_CUSTOMER_REFERENCE even though the email exists.

We had to dedupe our customer base first. The API's /customers endpoint with ?email= returns all matches—worth checking programmatically before your import run.

YMMV, but we ended up doing customer sync via API first, then using customer_id in the work order import rather than email. Eliminated a whole class of reference errors.