API Reference

Technical specification for every Intelomatic 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: every tenant API depends on the token it issues.

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.

Credentials

What a call needs depends on the API's access type. Every operation on an API page states it in its Auth line.

Access	Credentials on every call	URL
API key only	`api-key` query parameter. No bearer token.	`https://api-gw.sovereignsolutions.com/gateway/<path>`
Requires Intelomatic tenant	`Authorization: Bearer <access_token>` header and `api-key` query parameter	`https://api-gw.sovereignsolutions.com/gateway/{tenant}/<path>`
Token call (`POST /oauth/token`)	`api-key` query parameter only - it issues the bearer token	`https://api-gw.sovereignsolutions.com/gateway/authen/oauth/token`

Credential	What it is	Where it comes from
`api-key`	Your tenant key	Issued by Intelomatic during onboarding
`Authorization`	OAuth2 access token, tenant APIs only	`POST /oauth/token`

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
API-key-only APIs	`https://api-gw.sovereignsolutions.com/gateway`
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

How the catalogue is organised​

Credentials​

Getting a token​

Base URLs​

Conventions​

Status markers​

Authentication​

Location and Address Intelligence APIs​

Map Visualization​

Route and Journey Intelligence APIs​

Field Force Mobility Execution APIs​

Custom Integrations​