Darscover Listing API Documentation
This is the official and only source of truth for working with Darscover's listing API. It includes all required input fields, response structures, enums, and authentication requirements.
🔐 Authentication
All API calls require an x-api-key header. You can generate and manage your API key from the Darscover Admin Portal.
x-api-key: your-api-key-here
📄 Endpoints
GET /api/v1/listings/:id
Retrieve a full listing by ID.
Headers:
x-api-key: your-api-key-here
Response Example:
{
"id": "listing-id",
"userId": "...",
"agencyId": "...",
"categoryType": "residential",
"transactionType": "for_sale",
"price": "450000",
"location": { ... },
"propertyDetails": {
"details": { ... },
"amenities": { ... },
"requirements": { ... }
},
"listingMedia": [ ... ]
}
POST /api/v1/listings
Create a new listing.
Body:
{
listings: [
{
listing: {
categoryType:
| "residential"
| "room"
| "office"
| "commercial"
| "parking"
| "storage"
| "building"
| "airRights";
transactionType: "for_sale" | "for_rent";
price: string;
deposit?: string;
sellingCondition?: "new" | "used";
availableFrom?: string; // ISO date string
description?: string;
};
location: {
locality: string; // area e.g. "St. Julian's"
subLocality: string | null;
number: number;
street: string;
postCode: string;
floor?: FLOOR;
door?: DOOR;
doorDetail?: string;
};
details: { ... };
amenities: { ... };
requirements: { ... };
images?: string[];
},
{ ... }
]
}
Response:
{ "success": true }
PUT /api/v1/listings/:id
Update an existing listing.
Body:
{
listing: {
categoryType: "residential" | "room" | "office" | "commercial" | "parking" | "storage" | "building" | "airRights";
transactionType: "for_sale" | "for_rent";
price: string;
deposit?: string;
sellingCondition?: "new" | "used";
availableFrom?: string; // ISO date string
description?: string;
};
location: {
locality: string; // area e.g. "St. Julian's"
subLocality: string | null;
number: number;
street: string;
postCode: string;
floor?: FLOOR;
door?: DOOR;
doorDetail?: string;
};
details: { ... };
amenities: { ... };
requirements: { ... };
images?: string[];
}
Response:
{ "success": true }
DELETE /api/v1/listings/:id
Deletes a listing by ID.
DELETE /api/v1/listings/abc-123
Response: 204 No Content
🏠 Listing Category Breakdown
Residential
- Details:
{
propertyType: ResidentialPropertyType; // Required
condition: Condition; // Required
floors?: number;
builtArea: number; // Required
usableArea?: number;
plotSize?: number;
orientation?: Orientation;
bedrooms: number; // Required
bathrooms: number; // Required
energyCertificateRating: EnergyCertificate; // Required
minimumAreaForSale?: number;
}
- Amenities:
{
lift?: boolean;
airConditioning?: boolean;
terrace?: boolean;
balcony?: boolean;
cleaningService?: boolean;
doorman?: boolean;
garden?: boolean;
pool?: boolean;
roofAccess?: RoofAccess;
heatingType?: HeatingType;
bedType?: BedType;
fittedWardrobe?: boolean;
privateBathroom?: boolean;
parking?: boolean;
storeRoom?: boolean;
}
- Requirements:
{
furnished?: boolean;
equippedKitchen?: boolean;
internet?: boolean;
disabledAccess?: boolean;
pets?: boolean;
maxTenants?: number;
suitableForChildren?: boolean;
}
Room
- Details:
{
propertyType?: ResidentialPropertyType;
builtArea?: number;
bedrooms?: number;
bathrooms?: number;
roomView?: RoomView;
sharedWith?: number;
ownerOccupied?: boolean;
currentTenants?: boolean;
}
-
Amenities: (Same as Residential)
-
Requirements:
{
smoking?: boolean;
pets?: boolean;
couples?: boolean;
internet?: boolean;
furnished?: boolean;
equippedKitchen?: boolean;
minors?: boolean;
gender?: Gender[];
disabledAccess?: boolean;
minDesiredAge?: number;
maxDesiredAge?: number;
occupation?: Occupation;
lgbtFriendly?: boolean;
minMonthsStay?: number;
}
Office
- Details:
{
condition?: Condition;
builtArea?: number;
usableArea?: number;
floors?: number;
lifts?: number;
bathrooms?: number;
parkingSpaces?: number;
layout?: Layout;
energyCertificateRating?: EnergyCertificate;
}
- Amenities:
{
airConditioning?: boolean;
securityDoor?: boolean;
cctv?: boolean;
alarmSystem?: boolean;
accessControl?: boolean;
onlyOfficeUse?: boolean;
smokeDetectors?: boolean;
fireExtinguishers?: boolean;
sprinklers?: boolean;
fireDoor?: boolean;
emergencyExitLights?: boolean;
hotWater?: boolean;
heating?: boolean;
kitchen?: boolean;
doubleWindow?: boolean;
doorman?: boolean;
storeRoom?: boolean;
suspendedCeiling?: boolean;
raisedAccessFloor?: boolean;
adaptedForDisabled?: boolean;
}
Commercial
- Details:
{
propertyType: CommercialPropertyType; // Required
condition?: Condition;
builtArea?: number;
usableArea?: number;
rooms?: number;
bathrooms?: number;
floors?: number;
shopWindows?: number;
facadeLength?: number;
businessLocation?: BusinessLocation;
previousBusiness?: PreviousBusiness;
energyCertificateRating?: EnergyCertificate;
}
- Amenities:
{
airConditioning?: boolean;
heating?: boolean;
extractorFan?: boolean;
onCorner?: boolean;
securityDoor?: boolean;
storeRoom?: boolean;
cctv?: boolean;
alarmSystem?: boolean;
equippedKitchen?: boolean;
}
Parking
- Details:
{
propertyType: ParkingPropertyType; // Required
maxCapacity: MaxCapacity; // Required
sizeOfSpace?: number;
}
- Amenities:
{
coveredParkingSpace?: boolean;
automaticDoor?: boolean;
lift?: boolean;
cctv?: boolean;
securityPersonnel?: boolean;
}
Storage
- Details:
{
storageArea?: number;
height?: number;
}
- Amenities:
{
accessible24h?: boolean;
loadingUnloadingArea?: boolean;
surveillance24h?: boolean;
}
Building
- Details:
{
builtArea?: number;
homes?: number;
typeOfUse?: TypeOfBuilding[];
condition?: Condition;
energyCertificateRating?: EnergyCertificate;
floors?: number;
lifts?: number;
parkingSpaces?: number;
yearOfConstruction?: number;
tenants?: boolean;
}
- Amenities:
{
}
AirRights
- Details:
{
type: AirRightsType; // Required
landType: LandType; // Required
typeOfUse: TypeOfAirRights[]; // Required
maxFloors?: number;
totalSurface?: number;
buildableSurface?: number;
maxFloor?: number;
}
- Amenities:
{
roadAccess?: boolean;
water?: boolean;
electricity?: boolean;
sewerSystem?: boolean;
naturalGas?: boolean;
streetLighting?: boolean;
pavements?: boolean;
}
🏢 Agency Endpoints
GET /api/v1/agency
Returns agency details for the current API key.
GET /api/v1/agency
Response:
{
"id": "agency-id",
"name": "Example Agency",
"status": "active"
}
🧾 Enum Reference
All enum types used in the request bodies are documented in the Enums Documentation.
📌 Notes
- All date values must be ISO strings (e.g.
"2025-01-01T00:00:00Z"). - Enums must match expected string values (e.g.,
"for_sale","rented", etc.). - Listings are linked by
listingIdacross all detail/amenity/requirement tables.