Get started with the API

1. Get a credential

Intellisol creates your tenant and issues API credentials from IDM Admin (API tenants). A credential is a pair:

Part	Looks like	Where it goes
Key ID	pk_test_… or pk_live_…	Sent with every request. Not secret.
Secret	sk_test_… or sk_live_…	Used to sign requests. Shown once, when it is issued. Never sent over the wire.

Store the secret in your server's secret store. If you lose it, ask for a new credential; nobody can show it to you again.

Keep the secret on your server

Never put a secret in a browser, a mobile app or any code a customer can download. IDM watches for this: when a signed request arrives with browser fetch headers, the credential is revoked automatically and your administrators are told. Call IDM from your backend, and have your own frontend talk to your backend.

2. Test and live

Each credential belongs to one environment, shown in its prefix.

• Test credentials (pk_test_) work against IDM's test environment, where SMS, push and payments go to stand-ins and deliveries are not real.
• Live credentials (pk_live_) move real items with real riders.
• A test key sent to production is refused with INVALID_API_CREDENTIAL and the attempt is logged.

Your onboarding contact gives you the API host for each environment. Every path in this manual is relative to that host, for example https://<api-host>/v1/delivery/quote.

3. Scopes

A credential carries only the scopes you asked for. A new credential is read-only unless more are granted.

Scope	Lets you
geography.read	Resolve locations, list suburbs and vehicle types
quotes.create	Ask for quotes
delivery.create	Confirm quotes into jobs, create Bulk deliveries
delivery.read	Read jobs, events, Bulk progress and analytics
delivery.cancel	Cancel jobs and Bulk deliveries
delivery.reassign	Send a held delivery back to dispatch
delivery.complete	Complete your own delivery where your contract allows it
partners.read	List the delivery companies available to you
tracking.read	Read tracking information
webhooks.manage	Register webhook endpoints and replay events

A call without the scope it needs is refused with SCOPE_MISSING.

4. Your first delivery

Each step below is a signed request (how to sign).

Resolve the places (optional but useful for showing the customer where IDM thinks a pin is):

POST /v1/geography/resolve
{"latitude": 5.6037, "longitude": -0.1870, "accuracy_m": 15}

Check which vehicles can do this delivery: GET /v1/vehicle-types?pickup=SUB-…&dropoff=SUB-….

Ask for a quote:

POST /v1/delivery/quote
Idempotency-Key: 6f1c2f0e-quote-order-1042

{
  "pickup":  {"latitude": 5.6037, "longitude": -0.1870, "accuracy_m": 15},
  "dropoff": {"latitude": 5.6500, "longitude": -0.1600, "accuracy_m": 20},
  "vehicle_type": "MOTORBIKE",
  "service_type": "EXPRESS",
  "external_order_reference": "order-1042"
}

The answer carries quote_reference, delivery_fee (a string such as "38.50"), currency, classification, pricing_version and expires_at. Show the customer that fee, exactly as sent.

Confirm it before it expires:

POST /v1/delivery/jobs
Idempotency-Key: 6f1c2f0e-book-order-1042

{
  "quote_reference": "QT-8J2K4M6P",
  "external_order_reference": "order-1042",
  "recipient": {"name": "Ama", "phone": "+233200000000"},
  "note": "Call before arrival."
}

You get back a delivery reference (DX-…) and its status. IDM now finds a delivery company and a rider. Follow along with webhooks or by reading the job.

5. Checklist before you go live

• Every request is signed on your server; no secret is anywhere a customer can reach.
• Each user action has one idempotency key, reused on retry.
• You show only the fee the server sent, never one you calculated.
• Your webhook endpoint verifies the signature on the raw body and deduplicates on event_id.
• You read the job before you act on an important event.
• You handle QUOTE_EXPIRED by asking for a new quote.
• You keep the X-Request-Id of failed calls for support.