Darscover Logo

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 listingId across all detail/amenity/requirement tables.