API reference
Every endpoint, and what each one costs. The whole API is one base URL:
https://isitapproved.co.za/api/v1
Only one endpoint uses your allowance
1 billable
Almost every endpoint needs your API key. Only this one spends a call:
POST /api/v1/lookups.
Needing a key and costing a call are not the same thing, and the other
9 endpoints are free however often you call them.
Every endpoint, paid or free, is rate limited per key.
Authenticating
Send your key as a bearer token on every request except
GET /api/v1/health:
Authorization: Bearer iia_live_...
Keys are created on your API page. We store only a one-way hash, so a key is shown once and cannot be recovered.
Endpoints that use your allowance
Only these two spend calls. Everything else on this page is free, however often you call it.
/api/v1/lookups
Uses allowance
Look up one reference
1 call per lookup. The only endpoint that costs anything.
Submits a single reference to SAPS and returns the result. The call is RESERVED when you submit and only becomes SPENT once SAPS actually answers. If the enquiry service is unreachable the reservation is released and you are not charged.
| Field | Meaning |
|---|---|
reference | The SAPS reference number to look up. |
serial | Optional firearm serial, when the reference alone is ambiguous. |
curl -X POST https://isitapproved.co.za/api/v1/lookups \
-H "Authorization: Bearer iia_live_..." \
-H "Content-Type: application/json" \
-d '{"reference": "123456789"}'
Free, with your API key
These need the same bearer key as the ones above, but never deduct from your allowance.
/api/v1/lookups/{job_id}
Free
Fetch a single lookup's result
Free. Poll as often as you like.
Polling a result you have ALREADY paid for costs nothing. Charging for retrieval would mean a customer whose connection dropped pays twice for one answer.
/api/v1/account
Free
Your plan and current allowance
Free.
The same figures the account page shows: plan, calls remaining, calls reserved, and when the cycle ends.
/api/v1/usage
Free
Your usage history
Free.
Per-day call counts, for reconciling against your own records.
/api/v1/saps/status
Free
Whether SAPS is answering right now
Free. Check it before a big batch.
Our own live view of the SAPS enquiry service. This is the endpoint to poll when a batch is failing, because it distinguishes 'SAPS is down' from 'something is wrong with my request'.
/api/v1/saps/uptime
Free
SAPS availability over time
Free.
Historical availability, for choosing when to run bulk work.
/api/v1/reference/pipelines
Free
The application pipelines we recognise
Free.
Reference data. Stable, and safe to cache on your side.
/api/v1/reference/statuses
Free
The status values a lookup can return
Free.
Every status string this API can return, so you can map them once rather than discovering them in production.
/api/v1/approvals/stats
Free
Site-wide approval statistics
Free.
Aggregate figures across the whole site. No personal data, and nothing tied to your own account's lookups.
Free, no key needed
Callable without an account at all.
/api/v1/health
Free
Is this API up
Free, and the only endpoint needing no key.
Liveness of THIS API, deliberately not of SAPS. If you want to know whether SAPS is answering, that is /saps/status, a different question with a different answer.
Limits and failures
A lookup is RESERVED when you submit it and only becomes SPENT once SAPS actually answers. If SAPS is unreachable the reservation is released and you are not charged, so an outage costs you nothing.
We give no uptime promise, no response-time guarantee and no credit for downtime. The whole platform is rate-limited against SAPS on purpose, and a request we cannot serve is refused rather than queued indefinitely. See our terms, sections 3 and 9.