Batch import

Load plots, policies, clients and claims through the API, with a per-row report.

POST /v1/import/{aois|policies|clients|claims} enqueues on /v1/jobs, the same async contract as the footprint computation. There is no second mechanism: two ways of asking "is it done?" guarantee you learn the wrong one half of the time.

Fuente del diagrama (mermaid)

flowchart TD
    F[Archivo] --> P[Parseo por fila]
    P --> V{¿validate_only?}
    V -- sí --> R1[200 · reporte, nada escrito]
    V -- no --> J[202 · job + preview]
    J --> W[Worker aplica las filas aceptadas]
    W --> R2[GET /v1/jobs/id/result]

bash

curl -sS "$SBOX/v1/import/clients?validate_only=true" -X POST \
  -H "authorization: Bearer $TOKEN" \
  -H "idempotency-key: import-clients-dryrun-1" \
  -H "content-type: application/json" \
  -d '{"format":"csv","columnMapping":{"displayName":"nombre","contactEmail":"mail"},"content":"nombre,mail\nCoop Uno,uno@sbox.invalid\nSin mail,\n"}'

Per row, not per file

An insurer uploads three hundred policies and three come in broken. Rejecting the whole file forces them to find those three by eye; accepting it whole puts invalid data into contracts that will later be adjusted. The 297 go in, and the 3 come back with their row number and their reason.

atomic: true exists for the opposite case and is opt-in: if it were the default, the frequent case — a large file with typos — would be the expensive case.

Formats

GeoJSON, KML and CSV-with-WKT for AOIs; CSV or JSON with columnMapping for the rest. The CSV supports what Spanish-language Excel actually writes: BOM, ; as delimiter, quotes with commas inside, and CRLF.

What breaks

`code`	What happened
`missing_required_field`	A required field for the type is missing
`invalid_field_value`	Malformed email, non-positive number
`invalid_geometry`	Says the evaluator shared with the console
`duplicate_in_payload`	The row repeats within the same file
`duplicate_in_tenant`	That natural id already exists in the organization
`unknown_reference`	Points to a `clientId`/`aoiId` that does not exist
`row_limit_exceeded`	More than 5,000 rows
`atomic_batch_aborted`	The row was valid but the atomic batch failed

Limits: 5,000 rows, 8 MiB (413 above that). The permission is decided by the type: importing policies requires underwriting:write, importing plots portfolio:write.

Batch import

Per row, not per file

Formats

What breaks

Endpoints in this guide

On this page