GET /v1/geography/suburbs
GET /v1/geography/suburbs
| Scope | Idempotency-Key | Operation ID |
|---|---|---|
geography.read | — | listSuburbs |
Serviceable suburbs, by name.
Active suburbs within the gateways and zones the tenant's configuration allows,
searchable by name or alias (q) and filterable by gateway code. The reference is the
handle clients use to name an area; database IDs never appear.
Request
Signed with your API credential: see Authentication.
| Parameter | In | Required | Description |
|---|---|---|---|
q | query | No | At most 80 characters. |
gateway | query | No | Pattern ^[A-Z0-9][A-Z0-9_]{0,39}$. |
cursor | query | No | Opaque cursor from a previous page's next_cursor. |
limit | query | No | 1–100. |
Responses
200
One page of suburbs.
| Field | Type | Required | Description |
|---|---|---|---|
items | array of object | Yes | |
items[].reference | string | Yes | Pattern ^SUB-[0-9A-HJKMNP-TV-Z]{8}$. |
items[].name | string | Yes | |
items[].zone | object | Yes | |
items[].zone.code | string | Yes | |
items[].zone.name | string | Yes | |
items[].gateway | object | Yes | |
items[].gateway.code | string | Yes | |
items[].gateway.name | string | Yes | |
next_cursor | string or null | Yes |
400
Structural validation failed or an Idempotency-Key is missing.
The error envelope: code, message, detail, request_id.
401
Unknown, revoked or wrong-environment credential, bad signature, or expired session.
The error envelope: code, message, detail, request_id.
403
Tenant access denied (existence is not disclosed), insufficient scope, MFA/step-up required, partner blocked or module disabled.
The error envelope: code, message, detail, request_id.
404
No such route, or no such resource visible to the caller.
The error envelope: code, message, detail, request_id.
429
Rate limit reached; honour Retry-After.
The error envelope: code, message, detail, request_id.
500
Unexpected failure. Only code and request_id are returned.
The error envelope: code, message, detail, request_id.
503
Pricing/routing unavailable, request timeout, retryable contention, or an operator must act first (ACCOUNTING_PERIOD_UNAVAILABLE, outcome REQUIRES_ADMIN), or the payment provider cannot start a payment (PAYMENT_PROVIDER_UNAVAILABLE, outcome REQUIRES_PAYMENT; nothing charged).
The error envelope: code, message, detail, request_id.