#Geofence import

Geofence import allows creating many circle geofences at once from a spreadsheet file. Upload the XLSX, XLS, or CSV file with the /data/spreadsheet/parse method first: it converts the spreadsheet to a TSV (tab-separated values) file stored on the server and returns its name as file_id. Pass that name to start as filename. The import runs as a background process: start it with start, track it with read or list, download the rows that failed validation with download_failed, and mark the completed process as finished with finish.

Only circle geofences can be imported. Address and coordinates complete each other: if only the address is given, the coordinates is obtained by geocoding. If only the coordinates are given, the address is obtained by reverse geocoding.

Tags that don't exist yet are created automatically (within the user's quota for tags).

#Import process object

{
  "id": 7,
  "user_id": 231485,
  "created": "2026-07-02 10:15:32",
  "type": "zone",
  "params": {
    "headers": ["label", "address", "lat", "lng", "radius", "tags"],
    "user_headers": ["Label", "Address", "Latitude", "Longitude", "Radius", "Tags"]
  },
  "filename": "tmp-sheet640571613016981796.tsv",
  "status": "in_progress",
  "status_change_date": "2026-07-02 10:15:40",
  "progress": {
    "imported": 90,
    "failed": 10,
    "percent": 50,
    "processed_lines": 100,
    "warnings": [{"line": 5, "message": "Tags limit exceeded"}],
    "errors": [{"line": 12, "message": "label: Should not be empty"}]
  }
}

• id - int. Import process ID.
• user_id - int. Master user ID.
• created - date/time. When the import process was created.
• type - string. Import type, always zone.
• params - object. Import parameters.
  • headers - string array. List of the file's headers.
  • user_headers - optional string array. User labels for headers.
• filename - string. Name of the preloaded TSV file.
• status - string. Import status: created | in_progress | done | failed | finished.
• status_change_date - date/time. When the status changed last time.
• progress - object. Import progress.
  • imported - int. Count of successfully imported geofences.
  • failed - int. Count of rows that did not pass validation.
  • percent - int. Approximate percentage of processed rows.
  • processed_lines - int. Count of processed lines.
  • warnings - array of objects. First 25 warnings, each with line and message.
  • errors - array of objects. First 25 errors, each with line and message.

#API actions

API path: /zone/import/.

#start Not available

Starts the background process of importing circle geofences.

required sub-user rights: zone_update.

Parameters

Available fields:

• label
• address
• lat
• lng
• radius (default is 100 if not specified)
• tags
• undefined (if a meaning of a field is not known)

Response

{
  "success": true,
  "id": <int>
}

• id - int. An ID of the created import process.

Example

cURL

curl -X POST "https://api.mergroup.be/zone/import/start" \
    -H "Content-Type: application/json" \
    --data-binary @- << EOF
{
    "hash": "a6aa75587e5c59c32d347da438505fc3",
    "filename": "tmp-sheet640571613016981796.tsv",
    "headers": ["label", "address", "lat", "lng", "radius", "tags"],
    "user_headers": ["Label", "Address", "Latitude", "Longitude", "Radius", "Tags"]
}
EOF

Errors

• 15 - Too many requests (rate limit exceeded) - if too many imports in progress
• 233 - No data file - if the preloaded file is not found
• 234 - Invalid data format - if the file is not a TSV
• 247 - Entity already exists - there is another identical import with the same file

#read Not available

Returns an import process with specified ID.

Parameters

Response

{
  "success": true,
  "value": <import_process>
}

• value - Import process object.

Example

cURL

curl -X POST "https://api.mergroup.be/zone/import/read" \
    -H "Content-Type: application/json" \
    -d '{"hash": "a6aa75587e5c59c32d347da438505fc3", "process_id": 7}'

Errors

• 201 – Not found in database (if import is not found)

#list Not available

Returns the list of the user's unfinished geofence import processes (with statuses created, in_progress, done or failed).

Response

{
  "success" : true,
  "list" : [ <import_process>, ... ]
}

• list - array of Import process objects.

Example

cURL

curl -X POST "https://api.mergroup.be/zone/import/list" \
    -H "Content-Type: application/json" \
    -d '{"hash": "a6aa75587e5c59c32d347da438505fc3"}'

#download_failed Not available

Retrieve a file with lines that contained errors and did not pass validation.

Parameters

Response

File (standard file download).

Example

cURL

curl -X POST "https://api.mergroup.be/zone/import/download_failed" \
    -H "Content-Type: application/json" \
    -d '{"hash": "a6aa75587e5c59c32d347da438505fc3", "process_id": 7}'

Errors

• 201 – Not found in database (if import is not found)
• 204 – Entity not found (if file is not found)

#finish Not available

Marks an import process as finished. Finished processes are not returned by list.

Parameters

Response

{
  "success": true
}

Example

cURL

curl -X POST "https://api.mergroup.be/zone/import/finish" \
    -H "Content-Type: application/json" \
    -d '{"hash": "a6aa75587e5c59c32d347da438505fc3", "process_id": 7}'

Errors

• 201 – Not found in database (if import is not found)
• 280 – Invalid import request state (if the import process is still in progress)