Bulk import/export via API
These routes move one doctype’s documents out of Facet and back in as CSV or JSON. An export runs in a snapshot: it reads one point in time. An import runs in one transaction: every row lands, or none does.
For agents: Export:
POST /Api/<domain>/<doctype>/export?format=csvanswers202 {job_id, status_url}. PollGET /Api/<domain>/<doctype>/import_export/<job_id>, then download fromGET /Api/<domain>/<doctype>/import_export/<job_id>/download;wait=truereturns the file directly. Import:POST /Api/<domain>/<doctype>/importwith the CSV or JSON body; a422names the row and the problem. Upsert keys on theidcolumn; one transaction; the first failing row aborts all. POSTs needX-Requested-Withfor cookie sessions.
When to use this
Section titled “When to use this”Use the import/export routes when:
- You move a doctype into or out of a Facet instance.
- You hand a spreadsheet view of a doctype to someone who does not use Facet.
- You load an initial data set from another system.
Before you start
Section titled “Before you start”- Exports need
readrights on the doctype. An import needscreateandupdaterights, because an upsert can do either. - The routes refuse child doctypes (
member_of) and sidecar doctypes in both directions. - Cookie sessions must send
X-Requested-With: XMLHttpRequeston the POSTs. A bearer credential without a cookie is exempt.
Routes
Section titled “Routes”| Method | Route | Purpose |
|---|---|---|
POST |
/Api/<domain>/<doctype>/export |
Export a whole doctype. format=csv|json is required. wait=true and the list filters are optional. |
POST |
/Api/<domain>/<doctype>/export_view |
Export the current table view. JSON body: {columns, sort, filters, timezone}. |
POST |
/Api/<domain>/<doctype>/import |
Import a CSV or JSON file. The structural parse runs at enqueue. |
GET |
/Api/<domain>/<doctype>/import_export/<job_id> |
Job status: {id, status, error, result}. |
GET |
/Api/<domain>/<doctype>/import_export/<job_id>/download |
The result file. Succeeded exports only. |
1. Export a doctype
Section titled “1. Export a doctype”curl -s -X POST "https://facet.company.tld/Api/crm/Company/export?format=csv" \ -H "Authorization: Bearer $FACET_TOKEN" \ -H "X-Requested-With: XMLHttpRequest"The answer is 202:
{ "job_id": "01JBK2M4N6P8R0T2V4X6Z8B2D4", "status_url": "/Api/crm/Company/import_export/01JBK2M4N6P8R0T2V4X6Z8B2D4"}Poll the status route until status is succeeded or failed. Then
download the file from the download route. With wait=true the call
blocks until the job ends: on success the answer is the file itself, on
failure it is 500 with {"job_id", "error"}.
Filters ride the list grammar, for example filters[status__eq]=active.
sort, page, per_page, and items answer 422: the export is fixed
to id order.
2. Export the current table view
Section titled “2. Export the current table view”curl -s -X POST "https://facet.company.tld/Api/crm/Company/export_view" \ -H "Authorization: Bearer $FACET_TOKEN" \ -H "Content-Type: application/json" \ -H "X-Requested-With: XMLHttpRequest" \ -d '{"columns": ["name", "status", "amount"], "sort": ["-created_at", "id"], "filters": {"status__eq": "active"}, "timezone": "Europe/Paris"}'columnsis required. Each key must be a doctype field or a system column (id,created_at,updated_at). An unknown key answers422and names the key.sortuses the list grammar. A bad entry answers422.datetimecells render in the requestedtimezone. Without one they stay UTC.
3. Import a file
Section titled “3. Import a file”The route takes the format from a format= param, else from the
Content-Type, else from the body shape: a leading [ reads as JSON.
curl -s -X POST "https://facet.company.tld/Api/crm/Company/import" \ -H "Authorization: Bearer $FACET_TOKEN" \ -H "Content-Type: text/csv" \ -H "X-Requested-With: XMLHttpRequest" \ --data-binary @companies.csvThe answer is 202 with {"job_id", "row_count", "status_url"}.
The structural parse runs before the job. A malformed file answers 422
and names the row:
{ "error": "row 2: has 3 cells but the header declares 2 columns" }Bad quoting, an unknown header column, and a cell count that does not match the header all fail here. A cell-level problem, for example a bad money value in row 900, surfaces in the job result instead.
Example
Section titled “Example”An end-to-end round trip: export with wait=true, import the file back,
poll the job:
# 1. Export and wait: the call returns the CSV file directly.curl -s -X POST "https://facet.company.tld/Api/crm/Company/export?format=csv&wait=true" \ -H "Authorization: Bearer $FACET_TOKEN" \ -H "X-Requested-With: XMLHttpRequest" \ -o companies.csv
# 2. Import the file back.curl -s -X POST "https://facet.company.tld/Api/crm/Company/import" \ -H "Authorization: Bearer $FACET_TOKEN" \ -H "Content-Type: text/csv" \ -H "X-Requested-With: XMLHttpRequest" \ --data-binary @companies.csv
# 3. Poll the job status (the job_id from the import answer).curl -s "https://facet.company.tld/Api/crm/Company/import_export/01JBK2M4N6P8R0T2V4X6Z8B2D4" \ -H "Authorization: Bearer $FACET_TOKEN"A succeeded export job reports:
{ "id": "01JBK2M4N6P8R0T2V4X6Z8B2D4", "status": "succeeded", "error": null, "result": { "artifact_id": "01JARQ5G7X9K2M3N4P5Q6R7S8T", "row_count": 128, "format": "csv" }}The import contract
Section titled “The import contract”-
One transaction. The first failing row aborts the import. Zero rows persist.
-
The failure names the row. The report carries
{row, field, message}. -
Upsert by the
idcolumn. A live id updates the document. A tombstoned id is skipped; an import never resurrects a deleted document. An absent id creates one. -
Both rights are needed. The first row your role may not write fails the file.
-
Attribution. Every row records
actioner_id: "import"in the audit. -
genonlydoctypes refuse supplied ids. A doctype whose identifier is system-generated never creates a document from a supplied id.A wait-mode import answers
200with{row_count, created, updated, skipped}. An expected row failure answers422with the failing row.
Job model
Section titled “Job model”- A job runs once. Fix the input and submit again.
- The status and download routes answer only the requesting account.
Anyone else gets
404, so job ids do not leak. - Completion publishes an event on the doctype’s stream and sends the requesting account a notification with a download link.
CSV cell conventions
Section titled “CSV cell conventions”| Cell | Convention |
|---|---|
| Scalar text | As stored. |
| Structured types | JSON in the cell. |
| Money | USD 1.0 — the currency prefix is required on import. |
| Boolean | true / false. |
| Reference | Qualified id, for example crm.Company.abc. |
| File | The artifact id only; bytes do not move. |
| Empty cell | Decodes to null; it clears the field on update. |
| Missing column | Leaves the field untouched. |
Text starting =, +, -, @, or a tab |
Exports with a leading ' — the formula guard. Decode strips one leading '. |
Troubleshooting
Section titled “Troubleshooting”The import POST answers 413.
The body is over the upload cap. Split the file and import the parts.
The enqueue answers 422 and names a row.
The structural parse failed: bad quoting, an unknown header column, or a cell count that does not match the header. Fix that row and submit again.
The job fails on a money field.
A money cell needs the currency prefix: USD 1.0, not 1.0.
Some rows are skipped.
Their ids point at deleted documents. An import never resurrects a document. Remove the ids to create new documents.
The download answers 404.
The result file was pruned after the retention window — see Retention. Export again.
Related
Section titled “Related”- Use the REST API — the list filter grammar the export filters reuse.
- Uploading and serving files — how the result file is stored and read back.
- Retention — the window that bounds a download link.
- Internals on GitHub: import-export.md.