#POI import

POI import allows creating many places 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.

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": "place",
  "params": {
    "headers": ["label", "address", "lat", "lng", "radius", "description", "tags", "131312"],
    "user_headers": ["Label", "Address", "Latitude", "Longitude", "Radius", "Description", "Tags", "Responsible employee"]
  },
  "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 place.
• 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 POIs.
  • 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: /place/import/.

#start Not available

Starts the background process of importing POIs.

required sub-user rights: place_update.

Parameters

Available fields:

• label
• address
• lat
• lng
• radius (default is 100 if not specified)
• description
• tags
• custom field ID as a string, e.g. "131312" (see entity/fields)
• undefined (if a meaning of a field is not known)

For custom fields of type employee and multi_employee, values are matched with the user's employees by full name. For multi_employee fields, multiple names can be listed separated by commas or semicolons.

A POI will not be imported if a required custom field is missing or has an invalid value. Invalid values of non-required custom fields are skipped with a warning.

Response

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

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

Example

cURL

curl -X POST "https://api.mergroup.be/place/import/start" \
    -H "Content-Type: application/json" \
    --data-binary @- << EOF
{
    "hash": "a6aa75587e5c59c32d347da438505fc3",
    "filename": "tmp-sheet640571613016981796.tsv",
    "headers": ["label", "address", "lat", "lng", "radius", "description", "tags", "131312"],
    "user_headers": ["Label", "Address", "Latitude", "Longitude", "Radius", "Description", "Tags", "Responsible employee"]
}
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/place/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 POI 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/place/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/place/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/place/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)