API Reference

Technical specification for every Sovereign Solutions REST endpoint: paths, parameters, request and response bodies. For solution overviews and use cases, see Solutions.

Machine-readable spec: openapi.yaml · openapi.json - import either into Postman, Insomnia or Swagger UI.

---

How the catalogue is organised

APIs are grouped by solution area, matching the Solutions catalogue. Authentication sits on its own because every other API depends on it.

Access differs per API, not per group:

Access	What it means
API key only	Available to any authenticated caller with an API key. No Intelomatic tenant and no data upload required.
Requires Intelomatic tenant	Require an Intelomatic tenant. Register a tenant, upload your data, and these endpoints operate within your own workspace - most of them read or write the data you have uploaded, and several are scoped to your tenant's configured country.

Each reference page carries its own access badge, and the tables below list it per API.

---

Authentication

Every endpoint, including the token call, requires a bearer token and the api-key query parameter.

Authorization: Bearer <access_token>

?api-key=<apiKey>

Credential	What it is	Where it comes from
Authorization	OAuth2 access token	POST /oauth/token
api-key	Your tenant key	Issued by Sovereign Solutions during onboarding

Getting a token

curl -X POST 'https://api-gw.sovereignsolutions.com/gateway/authen/oauth/token?api-key=$API_KEY' \
  -d 'grant_type=password' \
  -d 'username=$USERNAME' \
  -d 'password=$PASSWORD'

{
  "access_token": "<JWT>",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "<token>"
}

---

Base URLs

Service	Base URL
Tenant API gateway	https://api-gw.sovereignsolutions.com/gateway/{tenant}
Identity / OAuth2	https://api-gw.sovereignsolutions.com/gateway/authen

{tenant} is your assigned tenant code.

---

Conventions

These hold across the whole platform.

Search responses are always wrapped in the same envelope:

{
  "data": [ /* records */ ],
  "total": 42
}

Pagination uses skip and take in the request body. take: -1 returns all matches.

Deletes return a count rather than the deleted object:

{ "count": 1 }

---

Status markers

Marker	Meaning
Ready	Verified contract, safe to integrate against
Planned	Contract agreed, endpoint not built yet
TBD	Contract not established; earlier path was incorrect and was removed
Coming soon	Planned capability, contract not yet published
Deferred	Exists internally; external exposure decision pending
Pending	Internal path; external availability unconfirmed

---

Authentication

API	Operations	Access	Status
Authentication (OAuth2 Token)	2	API key only	Ready

Location and Address Intelligence APIs

API	Operations	Access	Status
Batch Geocoding API	-	API key only	Coming soon
Batch Reverse Geocoding API	1	API key only	Ready
DigiPin API	3	API key only	Ready
Geocode API	3	API key only	Ready
Geocode Suggest API	1	API key only	Ready
Reverse Geocode API	1	API key only	Ready

Map Visualization

API	Operations	Access	Status
Elevation API	6	API key only	Ready
Map Base Tiles API	9	API key only	Ready

Route and Journey Intelligence APIs

API	Operations	Access	Status
Distance API	2	API key only	Ready
Isochrone API	2	API key only	Ready
Optimal Routes API	1	API key only	Ready
Route API	1	API key only	Ready
Route Matrix API	1	API key only	Ready
Snap to Road API	2	API key only	Ready

Field Force Mobility Execution APIs

API	Operations	Access	Status
Customer API	6	Requires tenant	Ready
Employee Management API	8	Requires tenant	Ready
Events API	2	Requires tenant	Ready
PJP (Permanent Journey Plan) API	9	Requires tenant	Ready
Tracking API	3	Requires tenant	Ready

Custom Integrations

API	Operations	Access	Status
Custom Data Layers API	6	Requires tenant	Ready