FAQs
1. Are there specific restrictions or mandatory requirements applied to location data?
Answer: Yes, specific restrictions and validations apply to location data, as explained below -
- Mandatory Field: Location fields are sometimes required (e.g., when subject to regulatory compliance checks).
- Off-Plan vs. Ready: Validation rules differ based on whether the location is designated as off-plan or ready.
- Specificity Required: Locations must resolve to a deep or exact address; Area or Emirate-level locations are rejected.
2. Is the Regulatory-Issued Permit Number always optional, or is it required in specific locations for activation?
Answer: The Regulatory-Issued Permit Number is always optional at the point of initial creation of the property (i.e., it is nullable). However, the field becomes mandatory with specific length and format rules when you attempt to activate (publish) a property in the following regulated locations: Dubai, Abu Dhabi, or Al Ain. This location-specific enforcement explains why some properties may bypass the requirement while others cannot.
3. Can we validate the permit number using a standalone API before creating the property, or is the validation tied to an existing Property ID?
Answer: The permit validation functionality is not available via a standalone API that operates without a property identifier. The only existing validation route is POST /properties/{property_id}/permit/validate.
This means you must successfully create the property first to obtain the required {property_id} selector, which is necessary for the validator endpoint to function.
4. What is the policy regarding optional parameters, and will the system reject the request if optional fields are included but left empty (null)?
Answer: Yes, the system will reject the request. You must not include the optional field entirely in the payload if its value is null or empty.
5. Is the Property Create + Publish process synchronous or asynchronous?
Answer: The publish endpoint is not synchronous, it returns the message that property will be made live once permit is validated.
6. How will the CRM receive real-time updates when a published property is modified?
Answer: Currently, the CRM must periodically re-sync the property data to check for and capture any modifications made after initial publication. We are planning to implement a subscription events mechanism. This means we will expose events upon modification, and any external service that has subscribed to these specific events will automatically receive the updates in near real-time.
7. Can you provide a complete, comprehensive list of all potential error messages and corresponding codes?
Answer: The required information is already available as:
- API Response: Every failed API request returns a specific, associated error code and a corresponding descriptive message within the response body.
- This API Documentation: A comprehensive list detailing the full range of error codes and their meanings is provided within the respective endpoint explanations.
8. How often is the location data updated?
Answer: We update the location data only rarely. To prevent synchronization issues and ensure data integrity, we strongly recommend performing a full quarterly data sync on a designated day. Furthermore, implementing a local cache is highly recommended, as this will significantly reduce the number of API calls and improve overall performance.
9. Does the Delete Property API permanently remove the property, or does it only unpublish it from the portal?
Answer: The delete endpoint validates optional portals, the API simply marks the property inactive on the requested portals without removing or hard deleting the record.
9.1 Re-publishing Deleted PRoperties
You can reuse the existing Property ID to republish a deleted property without creating a new record.If you previously deleted a property and want to republish it, you can use the same Property ID.
Endpoint: POST /properties/{property_id}/products/attach
What to do:
Use the Property ID from the property you want to republish
The property will be republished automatically with:
The same Property ID
All your existing property information (images, descriptions, etc.)
The same reference number
10. Do numeric fields accept decimal values, or are certain fields limited to integers?
Answer: Numeric fields (such as price, rent, area, plot_area, and maintenance_fee) accept decimal values. However, fields designated for counts (like bedroom or bathroom) require integer-only values; submitting decimals will result in a 422 Unprocessable Entity error.
11. Is there a dedicated Lead API?
Answer: Yes. Dedicated Lead Pull APIs have been implemented and are available. Please refer to the Lead Pull API documentation for usage and endpoints.
12. For properties eligible to be published on both Bayut and Dubizzle:
12.1. How is the publishing process handled when multiple portals are selected?
Answer: When publishing a property to multiple portals, the same property_id is used for all supported portals. The POST /api/v1/properties/{property_id}/products/attach endpoint allows a single property to be published to both bayut and dubizzle in one request by providing a portals array.
The portals field is applicable only at the time of publishing a property. It cannot be combined with the portal field in the same request, as both fields are mutually exclusive.
If no product is explicitly specified in the request, the system will automatically default to publishing the property, ensuring the property is successfully published without additional configuration.
12.2. Will the same property ID be used across both portals?
Answer: Yes, the property ID (which may also be referred to as the selector or reference number) remains the same across both portals.
12.3. If a property is initially published to one portal and later needs to be published to another, what is the required process?
Answer: You can publish the property to the second portal anytime by utilizing the same Publish property API endpoint again, specifying the new portal in the payload.
13. What is the location hierarchy structure?
Our location data structure supports up to eight hierarchy levels (loc_1 through loc_8). This structure exposes both ID-based arrays and human-readable breadcrumbs, giving ample room for mapping. The standard hierarchy is as follows:
Country → Emirate → Area → Community → Sub-community → Building/etc.
The hierarchy arrays (loc_*) are the primary keys, and the breadcrumb arrays include localized strings, ensuring alignment with DLD names for consistency.
{
"data": [
{
"id": 18014,
"level": 8,
"title": {
"en": "La Sirene Tower 4",
"ar": "برج لا سيرين 4"
},
"hierarchy": [
5001,
5002,
5687,
11908,
12076,
14347,
18017,
18014
],
"breadcrumb": {
"en": [
"UAE",
"Dubai",
"Jumeirah",
"La Mer",
"Port de La Mer",
"La Sirene",
"La Sirene 2",
"La Sirene Tower 4"
],
"ar": [
"الإمارات",
"دبي",
"جميرا",
"لا مير",
"بورت دو لا مير",
"لا سيرين",
"لا سيرين 2",
"برج لا سيرين 4"
]
}
}
]
}14: When is the 'value' field required for amenities?
Answer: The 'value' field is required whenever an amenity is included in the submission. The field is needed to indicate the presence or quantity of that amenity. The content of the 'value' field depends on the nature of the amenity:
- Boolean Value: Used for simple presence. For instance, if the amenity exists, the value is true (e.g., Gym: true).
- Numeric Value: Used to specify a count or quantity. For example, to indicate how many units of that amenity are available (e.g., Elevators in Building: 23).
15: :Primary/Unique identifiers in Property
Each property has two identifiers:
Property ID – A system-generated, permanent ID used for all API operations (view, update, delete, publish). It is unique.
Reference Number – A user-defined identifier. It must be unique among active properties within the agency, can be edited, and may be reused once the previous property is deleted.