National Address Verification

Overview

National Address Verification looks up the address registered with Saudi Post against a proof of identity. It accepts three kinds:

National ID (NationalID) — a Saudi citizen
Iqama (IqamaID) — a resident
Commercial registration (CRNumber) — a company, returning the address registered to the business along with its name

So you can confirm where someone lives, or where a company is registered, without asking them to supply a document.

Prerequisites

Authentication: Obtain an access token using the Client Credentials flow (see Getting Started → Authentication). Use scope national_address when generating the token.
Subscription: Subscribe to National Address Verification in your chosen environment.

This is a Premium product, not an Open Banking one, so it needs no Accounts Link and no customer consent flow.

GetNationalAddress

GEThttps://test.api.neotek.sa/saudi-post/v1/national-address/{POINumber}

Sandbox URL · in Production call https://api.neotek.sa

Path parameters:

Parameter	Required	Description
`POINumber`	Required	the ID number to look up: a national ID, iqama, or CR number

Query parameters:

Parameter	Required	Description
`POIType`	Required	which kind of ID it is: `NationalID`, `IqamaID` or `CRNumber`
`mpResponse`	Optional	`true` returns the ARB Marketplace response, `false` the Neotek response

Headers:

Parameter	Required	Description
`authorization`	Required	`Bearer <ACCESS_TOKEN>`, with scope `national_address`
`accept-language`	Optional	`ar` or `en`, defaulting to `en`. Every place name comes back in both languages, in a base field and a suffixed one
`x-request-id`	Optional	an RFC 4122 UUID you generate; quote it when raising a support ticket
`sub-client`	Optional	sub-channel id identifying the consumer

cURL

curl -G 'https://test.api.neotek.sa/saudi-post/v1/national-address/{POINumber}' \  -H 'Authorization: Bearer <ACCESS_TOKEN>' \  -H 'accept-language: ar' \  -d 'POIType=NationalID' \  -d 'mpResponse=true'

Response — individual lookup, NationalID or IqamaID

JSON

{    "Data": {        "AddressesList": [            {                "BuildingNumber": "1234",                "StreetName": "طريق الملك فهد",                "DistrictId": "10100001234",                "DistrictName": "حي العليا",                "CityName": "الرياض",                "PostCode": "12345",                "AdditionalNumber": "6789",                "CityNameAr": "RIYADH",                "StreetNameAr": "King Fahd Road",                "DistrictNameAr": "Al Olaya Dist.",                "Coordinates": "46.67500000 24.69000000",                "ShortAddress": "RRAA1234",                "IsPrimaryAddress": "true",                "AddressId": "1234512346789",                "CityId": "3",                "RegionId": "1",                "Address1": "1234 طريق الملك فهد - حي العليا",                "Address2": "الرياض 12345 - 6789",                "RegionName": "منطقة الرياض",                "RegionNameAr": "Riyadh",                "Latitude": "24.69000000",                "Longitude": "46.67500000"            }        ]    }}

Response — organisation lookup, CRNumber. Carries the company's identity and a UnitNumber, and drops the per-field Arabic street and district variants

JSON

{    "Data": {        "AddressesList": [            {                "TitleEn": "شركة الأمثلة للصيانة والتشغيل",                "TitleAr": "شركة الأمثلة للصيانة والتشغيل",                "Address1": "5678 King Abdulaziz Road - Al Olaya Dist.",                "Address2": "RIYADH 12345 - 6789",                "Coordinates": "46.71000000 24.71000000",                "BuildingNumber": "5678",                "StreetName": "King Abdulaziz Road",                "DistrictName": "Al Olaya Dist.",                "CityName": "RIYADH",                "PostCode": "12345",                "AdditionalNumber": "6789",                "RegionName": "Al Riyadh",                "IsPrimaryAddress": "false",                "UnitNumber": "23",                "Latitude": "24.71000000",                "Longitude": "46.71000000",                "CityId": "3",                "RegionId": "1",                "AddressId": "1234556786789",                "DistrictId": "",                "RegionNameAr": "الرياض",                "CityNameAr": "الرياض",                "CompanyName": "شركة الأمثلة للصيانة والتشغيل",                "CompanyNameAr": "شركة الأمثلة للصيانة والتشغيل"            }        ]    }}

Errors

Code	Status	Cause and Action
`400`	Bad Request	Missing required field, or a value that fails validation — check `Code` and `Path` in the body
`401`	Unauthorized	Token missing, expired, or invalid
`403`	Forbidden	Token doesn't carry the `national_address` scope
`404`	Not Found	No resource matches the identifier provided
`405`	Method Not Allowed	HTTP verb not supported on that path
`406`	Not Acceptable	`Accept` header doesn't match a supported representation — use `application/json`
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server error — retry with backoff, quote your `x-request-id`

Ready to build with National Address Verification?

Create a sandbox app, grab your credentials, and make your first call in minutes.

Start your first sandbox call Try it in the Playground

PreviousVerificationRequests NextFinancial Statement — Overview