curl --request GET \
--url https://api.ctrl-hub.com/v3/location-imports/{location_import_id} \
--header 'X-Session-Token: <api-key>'import requests
url = "https://api.ctrl-hub.com/v3/location-imports/{location_import_id}"
headers = {"X-Session-Token": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-Session-Token': '<api-key>'}};
fetch('https://api.ctrl-hub.com/v3/location-imports/{location_import_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.ctrl-hub.com/v3/location-imports/{location_import_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-Session-Token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.ctrl-hub.com/v3/location-imports/{location_import_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-Session-Token", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.ctrl-hub.com/v3/location-imports/{location_import_id}")
.header("X-Session-Token", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.ctrl-hub.com/v3/location-imports/{location_import_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-Session-Token"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "location-imports",
"attributes": {
"status": "processing",
"filename": "enwl-poles-2026-09.csv",
"column_mapping": {
"reference": "POLE_NO",
"name": "NAME",
"description": "<string>",
"location_type": "ASSET_TYPE",
"latitude": "<string>",
"longitude": "<string>",
"easting": "<string>",
"northing": "<string>",
"address_number": "<string>",
"address_name": "<string>",
"address_thoroughfare": "<string>",
"address_post_town": "<string>",
"address_postcode": "<string>"
},
"progress": {
"total_rows": 30000,
"processed_rows": 12500
},
"results": {
"inserted": 29850,
"updated": 146,
"skipped": 4,
"row_error_count": 4
},
"row_errors": [
{
"row": 4512,
"reason": "the latitude \"53.4o8\" is not a number",
"reference": "POLE-004512"
}
],
"error": "<string>"
},
"meta": {
"requested_at": "2023-11-07T05:31:56Z",
"completed_at": "2023-11-07T05:31:56Z"
},
"relationships": {
"organisation": {
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "organisations"
}
},
"requester": {
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "users"
}
},
"default_location_type": {
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "location-types"
}
}
}
},
"jsonapi": {
"version": "1.0"
},
"included": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "organisations",
"attributes": {
"name": "Acme Construction Ltd",
"slug": "acme-construction",
"sandbox": false,
"description": "Leading construction company specializing in infrastructure projects",
"settings": {
"teams": {
"customer_representatives": [
"b234c567-8901-2345-6789-abcdef012345"
]
}
}
},
"meta": {
"v3": true,
"status": "active",
"created_at": "2023-01-15T10:30:00.000Z",
"updated_at": "2023-02-20T14:45:00.000Z",
"features": [
{
"name": "advanced_reporting",
"enabled": true,
"limit": 1000
}
]
},
"relationships": {
"users": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "users"
}
]
},
"service_accounts": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "service-accounts"
}
]
},
"groups": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "groups"
}
]
},
"teams": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "teams"
}
]
},
"nomenclature": {
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "nomenclature"
}
}
}
}
]
}{
"id": "98ca4a78-b66f-4234-9719-aaf832ee6669",
"status": "400",
"title": "A validation error was encountered",
"source": {
"parameter": "include"
},
"meta": {
"resource": "wrong_value"
}
}{
"id": "05fc9c8d-73b9-4697-9337-57f7a567a48f",
"status": "401",
"title": "You are not authorised to access this resource",
"detail": "In order to access this resource, you need the 'admin' role.",
"code": "AUTH.001"
}{
"id": "7b4c8f12-3e9a-4d5b-8c6f-1a2b3c4d5e6f",
"status": "404",
"title": "Resource not found",
"detail": "The requested resource could not be found or does not exist.",
"code": "NOT_FOUND.001"
}{
"id": "fe9d9a69-f0a7-4fdc-bb2c-176027f316c5",
"status": "500",
"title": "Internal Server Error",
"detail": "An unexpected error occurred on the server."
}Get a location import
Retrieve a location import by its unique identifier.
This is what a caller polls while an import runs. progress gives processed against total rows,
results gives the running inserted, updated and skipped counts, and row_errors gives the
reasons rows were left out. Stop polling when status is completed or failed; a failed import
is deliberately distinguishable from one still running, so a caller is not left waiting for
something that is not coming.
Authorised by locations:view in the import’s organisation, at the organisation level rather than
against the record: somebody whose locations grant is narrowed to particular places still has to
be able to watch the import they started.
curl --request GET \
--url https://api.ctrl-hub.com/v3/location-imports/{location_import_id} \
--header 'X-Session-Token: <api-key>'import requests
url = "https://api.ctrl-hub.com/v3/location-imports/{location_import_id}"
headers = {"X-Session-Token": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-Session-Token': '<api-key>'}};
fetch('https://api.ctrl-hub.com/v3/location-imports/{location_import_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.ctrl-hub.com/v3/location-imports/{location_import_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-Session-Token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.ctrl-hub.com/v3/location-imports/{location_import_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-Session-Token", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.ctrl-hub.com/v3/location-imports/{location_import_id}")
.header("X-Session-Token", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.ctrl-hub.com/v3/location-imports/{location_import_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-Session-Token"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "location-imports",
"attributes": {
"status": "processing",
"filename": "enwl-poles-2026-09.csv",
"column_mapping": {
"reference": "POLE_NO",
"name": "NAME",
"description": "<string>",
"location_type": "ASSET_TYPE",
"latitude": "<string>",
"longitude": "<string>",
"easting": "<string>",
"northing": "<string>",
"address_number": "<string>",
"address_name": "<string>",
"address_thoroughfare": "<string>",
"address_post_town": "<string>",
"address_postcode": "<string>"
},
"progress": {
"total_rows": 30000,
"processed_rows": 12500
},
"results": {
"inserted": 29850,
"updated": 146,
"skipped": 4,
"row_error_count": 4
},
"row_errors": [
{
"row": 4512,
"reason": "the latitude \"53.4o8\" is not a number",
"reference": "POLE-004512"
}
],
"error": "<string>"
},
"meta": {
"requested_at": "2023-11-07T05:31:56Z",
"completed_at": "2023-11-07T05:31:56Z"
},
"relationships": {
"organisation": {
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "organisations"
}
},
"requester": {
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "users"
}
},
"default_location_type": {
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "location-types"
}
}
}
},
"jsonapi": {
"version": "1.0"
},
"included": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "organisations",
"attributes": {
"name": "Acme Construction Ltd",
"slug": "acme-construction",
"sandbox": false,
"description": "Leading construction company specializing in infrastructure projects",
"settings": {
"teams": {
"customer_representatives": [
"b234c567-8901-2345-6789-abcdef012345"
]
}
}
},
"meta": {
"v3": true,
"status": "active",
"created_at": "2023-01-15T10:30:00.000Z",
"updated_at": "2023-02-20T14:45:00.000Z",
"features": [
{
"name": "advanced_reporting",
"enabled": true,
"limit": 1000
}
]
},
"relationships": {
"users": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "users"
}
]
},
"service_accounts": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "service-accounts"
}
]
},
"groups": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "groups"
}
]
},
"teams": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "teams"
}
]
},
"nomenclature": {
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "nomenclature"
}
}
}
}
]
}{
"id": "98ca4a78-b66f-4234-9719-aaf832ee6669",
"status": "400",
"title": "A validation error was encountered",
"source": {
"parameter": "include"
},
"meta": {
"resource": "wrong_value"
}
}{
"id": "05fc9c8d-73b9-4697-9337-57f7a567a48f",
"status": "401",
"title": "You are not authorised to access this resource",
"detail": "In order to access this resource, you need the 'admin' role.",
"code": "AUTH.001"
}{
"id": "7b4c8f12-3e9a-4d5b-8c6f-1a2b3c4d5e6f",
"status": "404",
"title": "Resource not found",
"detail": "The requested resource could not be found or does not exist.",
"code": "NOT_FOUND.001"
}{
"id": "fe9d9a69-f0a7-4fdc-bb2c-176027f316c5",
"status": "500",
"title": "Internal Server Error",
"detail": "An unexpected error occurred on the server."
}Authorizations
Session token for authentication.
Path Parameters
The unique identifier for the location import.
Query Parameters
A comma separated list of related resources to include.
requester names who uploaded the file, which an import history is mostly read for, and
default_location_type names the type the import applied to untyped rows. Both save a caller
resolving an id it would otherwise have to fetch separately.
organisation, requester, default_location_type Response
An individual location import.
JSON API response object
One bulk load of locations from an uploaded CSV, and what became of every row.
The record is the import's audit trail, and that is by design rather than by accident: the bulk write path emits no per-row events, because a per-row event for a 30,000-row file would put 30,000 messages on the platform's bus for one upload. So this record answers "who loaded what, and what did it do" on its own.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Related resources that can be included when a location import is returned.
An organisation
- Option 1
- Option 2
- Option 3
Show child attributes
Show child attributes