When shipping orders to Saudi Arabia, you need to include a National Address Code for regulatory compliance. This article explains how to add these codes through the API and configure validation rules. You'll need API access and Order Rules permissions to complete these tasks.
Add the National Address Code to your order
When you create an order using the PUT /api/Order request, include the NationalAddressField property in your request payload for orders shipping to Saudi Arabia.
To add a National Address Code:
Set the Country value to SA in your order payload.
Add the NationalAddressField property.
Enter the 8-character alphanumeric code as the value.
Tip: The field only applies to orders where the destination country is Saudi Arabia.
Get the National Address Code
You can obtain National Address Codes from Saudi National Address lookup services. The code appears as the ShortAddress value in the response from these services.
Important: You need your own access credentials from the Saudi National Address service provider to retrieve codes.
Understand the validation process
The system validates National Address Codes at two levels when you configure the appropriate Order Rules:
Format validation - Confirms the code contains exactly 8 alphanumeric characters.
API validation - Verifies the code against the official Saudi National Address service.
Configure validation rules
You can set up validation through the Order Rules system in Mintsoft. To learn more, please review our Validate National Address Code help guide.
Note: Common conditions include Country = SA to target Saudi Arabia shipments specifically.
Handle validation failures
When validation fails, the system automatically tags the order with one of two tags:
InvalidNationalAddressCode-Format - The code doesn't match the required 8-character alphanumeric format.
InvalidNationalAddressCode-Lookup - The code failed verification against the Saudi National Address API.
You can configure additional Order Rules to manage these tagged orders according to your business requirements. Common actions include holding orders for review, cancelling orders, or marking them as awaiting confirmation.
Courier integration
Valid National Address Codes are automatically included in courier shipment requests where your shipping provider supports this feature. This ensures the code transmits to your courier for regulatory compliance.