For developers

NeighbourhoodIQ API v1

Integrate organisation leads, claims and neighbourhood scores into your own workflow. Access requires an eligible organisation account and API key. Confirm data coverage, permitted commercial use and licensing terms with us before building a production dependency.

Ask about API access Organisation features

Base URL

https://neighbourhoodiq.co.za/api/v1

All endpoints return JSON. Use HTTPS for every request.

Authentication and limits

Send the organisation key in the Authorization: Bearer … header. The current route limit is 60 requests per minute per token. Organisations with a monthly request allowance receive X-Quota-Limit, X-Quota-Remaining and X-Quota-Reset headers; server errors and refused requests do not count towards it. Keep keys on your server, rotate them if exposed, and never place them in browser code or public repositories.

Available endpoints

Each key has explicit abilities. The organisation token page lists the abilities on its current key.

Method	Path	Ability	Purpose
GET	`/leads`	`leads:read`	List this organisation’s leads; supports `status` and `per_page` (max 100).
POST	`/leads`	`leads:write`	Create a lead for a suburb or complex claimed by this organisation.
GET	`/claims`	`claims:read`	List this organisation’s claims; supports `status` and `per_page` (max 100).
GET	`/suburbs/{slug}`	`scores:read`	Read a public active suburb score profile.
GET	`/complexes/{slug}`	`scores:read`	Read an approved, active complex score profile.

Read a score

curl "https://neighbourhoodiq.co.za/api/v1/suburbs/<suburb-slug>" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $NEIGHBOURHOODIQ_API_KEY"

Replace the slug with an active published suburb. The response includes place fields, score dimensions, computation date and public URL; score data can be null when no score exists.

List your leads

curl "https://neighbourhoodiq.co.za/api/v1/leads?status=new&per_page=25" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $NEIGHBOURHOODIQ_API_KEY"

Lists are paginated and scoped to the authenticated organisation.

Create a lead

The referenced suburb or complex must already be claimed by your organisation. This endpoint accepts JSON fields claimable_type (suburb or complex), claimable_id, name, email, and optional phone/message. A successful response uses HTTP 201.

curl -X POST "https://neighbourhoodiq.co.za/api/v1/leads" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEIGHBOURHOODIQ_API_KEY" \
  -d '{"claimable_type":"suburb","claimable_id":123,"name":"Example Person","email":"person@example.com"}'

Replace the numeric ID and sample contact fields with an approved, consented lead referencing a place your organisation owns.

Errors

Errors use a JSON error object with a code and message. Validation failures return HTTP 422 and field errors; missing or invalid keys return 401; missing ability or plan access returns 403; unknown/inactive records return 404; rate limiting returns 429, and an exhausted monthly allowance returns 429 with the code quota_exceeded.

Commercial use

The API exposes only the endpoints listed here. Do not assume a dataset can be redistributed or republished. Country coverage, source rights, retention, rate/price, service levels and permitted use must be agreed before production use. We will confirm these for your use case before quoting.