Bulk Import CSV Schema

The bulk import feature accepts a CSV file (or pasted rows) where each row becomes one geocoded geofence. The geocoder resolves each address to a latitude/longitude centroid and creates a circular geofence around it. For the raw API endpoint shape and programmatic access, see the Bulk Create Geofences API reference.

CSV Columns

Column Name	Type	Required	Description
address	string	Yes	Full street address to geocode (e.g., 123 Main St, Austin TX 78701). The geocoder resolves this to a lat/lng centroid.
name	string	No	Display name for the geofence. Defaults to the address string if omitted.
buffer_meters	integer	No	Radius of the circular geofence in meters. Defaults to the workspace default (typically 100 m). Minimum: 10. Maximum: 50000.
tags	string	No	Comma-separated tag names (e.g., warehouse,priority-a). Tags are created if they do not exist. Spaces are trimmed. If a tag name itself contains a comma, wrap it in double quotes.

Example CSV

address,name,buffer_meters,tags
"123 Main St, Austin TX 78701",Austin Office,150,"office,southwest"
"456 Commerce St, Dallas TX 75201",Dallas Depot,200,depot
"789 Peachtree St, Atlanta GA 30308",,100,warehouse

The third row omits name — the geofence will be named 789 Peachtree St, Atlanta GA 30308.

Accepted Formats

UI Upload or Paste

The dashboard import dialog accepts:

• CSV file upload — drag-and-drop or browse a .csv file with the columns listed above.
• Direct paste — paste rows directly into the text area; the first row must be a header.

Column order does not matter as long as the headers match exactly (address, name, buffer_meters, tags). Extra columns are ignored.

API

The API endpoint accepts two input shapes:

• multipart/form-data with a file field containing the CSV file — useful for scripted uploads.
• JSON body with a rows array — useful for programmatic generation without writing a file to disk.

For full details on the JSON shape, authentication, and rate limits, see the Bulk Create Geofences API reference.

Dedup Strategies

The dedup_strategy field is passed at import time (not per-row) and controls what happens when a row's geofence name already exists in the workspace.

Strategy	Behavior
skip (default)	Duplicate rows are skipped silently. The existing geofence is unchanged. The row appears in the results with outcome duplicate. Re-importing the same CSV is safe and idempotent.
override	The existing geofence's geometry and tags are updated with the imported row's values. Use this for nightly syncs where addresses may have moved or been corrected.
fail	Any duplicate row causes the entire import to be rejected — no geofences are created. Use this for strict transactional imports where you need an all-or-nothing guarantee.

Dedup matching is by name, not by address or geometry. Two rows with different names but the same address are not considered duplicates.

Per-Row Outcome States

After a commit (or preview), every row carries an outcome state indicating how it was handled. Six states are possible:

Outcome	Meaning
success	Address geocoded with high confidence. Geofence created at the resolved location.
low-confidence	Geocoder returned a match below the confidence threshold. Geofence is created but flagged — review the pin location on the map before relying on it for triggers.
interpolated	Address was resolved by street interpolation (no rooftop-level match available). Geofence is created at the estimated midpoint of the block. Accuracy is lower than a rooftop match.
no-match	Address could not be geocoded. The row is excluded from the commit and appears in the error export with error_reason: no-match. Correct the address and re-import.
ambiguous	Multiple geocoder candidates were found with similar confidence scores. The row is excluded from the commit and appears in the error export with candidate addresses listed so you can pick the right one.
duplicate	The geofence name already exists in the workspace. Behavior depends on the active dedup_strategy (skip, override, or fail).

Rows with success, low-confidence, and interpolated outcomes result in a created geofence. Rows with no-match, ambiguous, and fail-triggered outcomes do not.

Error CSV Export

After an import completes, rows that could not be created (no-match, ambiguous, or rows rejected by dedup_strategy: fail) are available as a downloadable error CSV from the import results panel.

The error CSV contains all original columns (address, name, buffer_meters, tags) plus one additional column:

Column	Description
error_reason	Machine-readable outcome for the row: no-match, ambiguous, or duplicate. For ambiguous rows, the candidate addresses suggested by the geocoder are included in parentheses.

Correcting and Re-importing

1. Download the error CSV from the import results panel.
2. Correct the address values in a spreadsheet or text editor.
3. Re-upload the corrected file. Only the rows that failed need to be re-imported.

This round-trip workflow lets large imports (hundreds or thousands of addresses) proceed without blocking on a small number of bad addresses.

---

See also:

• Bulk Create Geofences API Reference — endpoint shape, JSON schema, rate limits, and SDK examples
• TMS/CRM to Geofences Recipe — end-to-end walkthrough: export addresses from your TMS, import via the bulk API, and trigger workflows on the resulting geofences