Free Plan

Postal Codes

Look up South African suburb postal codes. Each record includes the suburb name, municipality, province, street delivery code, and P.O. box code. Over 20,000 suburbs covered.

Base URL: https://api.apply.org.za

Authentication: All requests require an X-API-Key header. Postal Codes endpoints are available on the Free plan and above. Get your free key →

GET/v1/postal-codes

Returns a paginated list of South African suburb postal codes. Filter by suburb name, area, or province.

Query Parameters

Parameter	Type	Description
`search`	string	Full-text search across suburb name and area.
`suburb`	string	Filter by suburb name (partial match, case-insensitive).
`area`	string	Filter by area / town name.
`province`	string	Filter by province name (e.g. "Gauteng").
`postal_code`	string	Look up by exact street or box postal code.
`page`	integer	Page number (default: 1).
`per_page`	integer	Results per page (default: 20, max: 100).

Example Request

# Search for suburbs in Sandton

curl https://api.apply.org.za/v1/postal-codes?search=sandton \
-H "X-API-Key: uafm_live_••••••••"

Example Response

{
  "data": [
    {
      "id": "bb3c1a2e-...",
      "suburb": "Sandown",
      "area": "Sandton",
      "province": "Gauteng",
      "street_code": "2196",
      "box_code": "2146"
    },
    {
      "id": "cc4d2b3f-...",
      "suburb": "Sandton",
      "area": "Sandton",
      "province": "Gauteng",
      "street_code": "2196",
      "box_code": "2146"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 12,
    "total_pages": 1
  }
}

GET/v1/postal-codes/:id

Retrieve a single postal code record by its UUID.

Path Parameters

Parameter	Type	Description
`id`	uuid	The unique identifier of the postal code record.

Example Request

curl https://api.apply.org.za/v1/postal-codes/bb3c1a2e-... \
-H "X-API-Key: uafm_live_••••••••"

Example Response

{
  "data": {
    "id": "bb3c1a2e-...",
    "suburb": "Sandown",
    "area": "Sandton",
    "province": "Gauteng",
    "street_code": "2196",
    "box_code": "2146"
  }
}

Error Codes

HTTP Status	Code	Description
401	`UNAUTHORIZED`	Missing or invalid API key.
403	`FORBIDDEN`	Your plan does not include postal_codes:read scope.
404	`NOT_FOUND`	The postal code record was not found.
429	`RATE_LIMITED`	Too many requests. Back off and retry.

Ready to start querying postal codes?

Get your free API key