Create a listing
Request, parameters, response and errors of POST /v1/listings.
Last updated:
Creates a listing. The body is the OpenImmo 2.0 listing; it is complete unless draft=true, which requires only metadata.source. Creating does not publish. An address with its unit, staircase and entrance belongs to one listing per office (409 address_already_exists, naming the listing that holds it); send data.location.unit to have several listings in one house; metadata.source.offererMarketingKey must be unique in the office (409 reference_already_exists). The plan limits the number of listings (403 plan_required). media names files uploaded with POST /medias (in order), contact is the contact person. Send Idempotency-Key to make a retry safe. Needs write access to listings.
Requires the scope propose.
Request
POST https://api.athaus.ai/v1/listingsParameters
Query
| Name | Type | Required | Description |
|---|---|---|---|
draft | string | no | Accept an incomplete listing: only metadata.source is required, and the rest is checked when the listing is published. Ours, not OpenImmo. Default false. |
Header
| Name | Type | Required | Description |
|---|---|---|---|
Athaus-Version | string | no | Optional and carries nothing a client needs: the version is the path. Accepted when it says v1 or 1. Any other value is a 400 api_version_unsupported. |
Idempotency-Key | string | no | Makes a retry safe: the same key with the same body returns the first answer and writes nothing twice. A random value of at least 128 bits, for example a UUID, 1 to 255 characters. The key is kept for 24 hours and scoped to the API key and this operation. The same key with a different body is a 422; while the first request still runs it is a 409. Only successful answers are kept: after an error the key is free again. |
Request body
JSON with Content-Type: application/json. A field the API does not know is a 400, and errors[].name names the field. The body is required.
| Field | Type | Description |
|---|---|---|
data | object | |
data.estateType | string | One of HOUSE, APARTMENT, PLOT, OFFICE, TRADING, GASTRONOMY_HOTEL, STORAGE_PRODUCTION, AGRICULTURE_FORESTRY, PARKING, SENIOR, PROJECT, MISCELLANEOUS. |
data.estateSubType | object | |
data.distributionType | string | One of BUY, RENT, COMPULSORY_AUCTION, BUY_AUCTION. |
data.location | object | |
data.location.postalcode | string | |
data.location.city | string | |
data.location.street | string | |
data.location.houseNumber | string | |
data.location.unit | string | |
data.location.staircase | string | |
data.location.floorNumber | integer | -5 to 999. |
data.location.entrance | string | |
data.location.state | string | |
data.location.country | string | One of 249 values from the list in the standard. |
data.location.geometry | object | |
data.location.geometry.type | string | Always Point. |
data.location.geometry.coordinates | number[] | |
data.location.showAddress | boolean | Default true. |
data.location.locationNote | map<string> | |
data.prices | object | |
data.prices.currency | string | One of 180 values from the list in the standard. Default EUR. |
data.prices.buy | object | |
data.prices.buy.price | any | |
data.prices.buy.isLeaseBuyCombi | boolean | |
data.prices.buy.leasehold | object | |
data.prices.buy.operatingCosts | any | |
data.prices.buy.rentalIncome | any | |
data.prices.buy.rentalIncomeExpect | any | |
data.prices.buy.isParkingPriceIncluded | boolean | |
data.prices.buy.parkingPrices | any[] | |
data.prices.buy.pricePerSqUnit | any | |
data.prices.buy.yieldFactor | number | 0 to 9999999999999. |
data.prices.buy.countrySpecific | object | |
data.prices.rent | object | |
data.prices.rent.baseRent | any | |
data.prices.rent.baseRentPerYear | any | |
data.prices.rent.totalRent | any | |
data.prices.rent.lease | any | |
data.prices.rent.operatingCosts | any | |
data.prices.rent.heatingCosts | any | |
data.prices.rent.isHeatingIncludedInOC | boolean | |
data.prices.rent.isHeatingIncludedInTR | boolean | |
data.prices.rent.pricePerSqUnit | any | |
data.prices.rent.pricePerSqUnitPerYear | any | |
data.prices.rent.priceTimeUnit | string | One of DAY, WEEK, MONTH, YEAR. Default MONTH. |
data.prices.rent.isParkingPriceIncluded | boolean | |
data.prices.rent.parkingPrices | any[] | |
data.prices.rent.depositNote | map<string> | |
data.prices.rent.countrySpecific | object | |
data.prices.compulsoryAuction | object | |
data.prices.compulsoryAuction.auctionProceeds | any | |
data.prices.compulsoryAuction.biddingGuarantee | any | |
data.prices.compulsoryAuction.marketValue | any | |
data.prices.compulsoryAuction.minimumBid | any | |
data.prices.buyAuction | object | |
data.prices.buyAuction.minPrice | object | |
data.prices.buyAuction.startOfferPhase | string (date) | |
data.prices.buyAuction.endOfferPhase | string (date) | |
data.prices.brokerageFee | any | |
data.prices.showPrice | boolean | |
data.prices.priceNote | map<string> | |
data.prices.countrySpecific | object | |
data.prices.countrySpecific.fr | object | |
data.spaces | object | |
data.spaces.spaceMeasureUnit | string | One of SQUARE_METER, SQUARE_INCH, SQUARE_FOOT, SQUARE_YARD, HECTARE, ACRE. Default SQUARE_METER. |
data.spaces.buildingFront | number | 0 to 99999999. |
data.spaces.kitchenSpace | number | 0 to 99999999. |
data.spaces.overallSpace | number | 0 to 99999999. |
data.spaces.usableFloorSpace | number | 0 to 99999999. |
data.spaces.spaceMax | number | 0 to 99999999. |
data.spaces.spaceMin | number | 0 to 99999999. |
data.spaces.plotSpace | number | 0 to 99999999. |
data.spaces.plotFront | number | 0 to 99999999. |
data.spaces.additionalSpace | number | 0 to 99999999. |
data.spaces.residential | object | |
data.spaces.residential.livingSpace | number | 0 to 99999999. |
data.spaces.residential.livingRoomSpace | number | 0 to 99999999. |
data.spaces.residential.atticSpace | number | 0 to 99999999. |
data.spaces.residential.balconySpace | number | 0 to 99999999. |
data.spaces.residential.cellarSpace | number | 0 to 99999999. |
data.spaces.residential.gardenSpace | number | 0 to 99999999. |
data.spaces.residential.terraceSpace | number | 0 to 99999999. |
data.spaces.commercial | object | |
data.spaces.commercial.maxDivisible | number | 0 to 99999999. |
data.spaces.commercial.minDivisible | number | 0 to 99999999. |
data.spaces.commercial.commercialSpace | number | 0 to 99999999. |
data.spaces.commercial.shopSpace | number | 0 to 99999999. |
data.spaces.commercial.storageSpace | number | 0 to 99999999. |
data.spaces.commercial.sellSpace | number | 0 to 99999999. |
data.spaces.commercial.officeSpace | number | 0 to 99999999. |
data.spaces.commercial.officePartSpace | number | 0 to 99999999. |
data.spaces.commercial.managementSpace | number | 0 to 99999999. |
data.spaces.commercial.restaurantSpace | number | 0 to 99999999. |
data.spaces.commercial.countrySpecific | object | |
data.conditions | object | |
data.conditions.buildState | string | One of FIRST_TIME_USE, FIRST_TIME_USE_AFTER_REFURBISHMENT, MINT_CONDITION, MODERNISED, REFURBISHED, FULLY_RENOVATED, PARTLY_RENOVATED, NEED_OF_RENOVATION, WELL_KEPT, NEGOTIABLE, RIPE_FOR_DEMOLITION, PROJECTED, NO_INFORMATION, RESTRUCTURED, TO_RESTORE, TO_REFURBISH. |
data.conditions.ageState | string | One of OLD, NEW. |
data.conditions.lastModernisation | integer | |
data.conditions.constructionStyle | string | One of PREFABRICATED, SOLID, SOLID_PREFABRICATED, TIMBERHOUSE, WOOD_PREFABRICATED, UNSPECIFIED. |
data.conditions.yearOfConstruction | integer | 1000 to 3000. |
data.energy | object | |
data.energy.energyType | object | |
data.energy.energyType.heatMethod | string | One of CENTRAL, INDIVIDUAL, STOREY. |
data.energy.energyType.heatForm | object | |
data.energy.energyType.energySource | object | |
data.energy.energyType.energyGeneration | object | |
data.energy.energyType.maxElectricalPower | integer | |
data.energy.countrySpecific | object | |
data.energy.countrySpecific.de | object | |
data.features | object | |
data.features.accessibleFromStreet | string | One of YES, NO, NOT_APPLICABLE. |
data.features.aircondition | string | One of YES, PART, NO, NOT_APPLICABLE. |
data.features.entranceHall | string | One of YES, NO, NOT_APPLICABLE. |
data.features.floorCovering | object | |
data.features.floorCovering.tiles | string | One of YES, NO, NOT_APPLICABLE. |
data.features.floorCovering.stone | string | One of YES, NO, NOT_APPLICABLE. |
data.features.floorCovering.carpet | string | One of YES, NO, NOT_APPLICABLE. |
data.features.floorCovering.parquet | string | One of YES, NO, NOT_APPLICABLE. |
data.features.floorCovering.laminate | string | One of YES, NO, NOT_APPLICABLE. |
data.features.floorCovering.synthetic | string | One of YES, NO, NOT_APPLICABLE. |
data.features.floorCovering.screed | string | One of YES, NO, NOT_APPLICABLE. |
data.features.floorCovering.linoleum | string | One of YES, NO, NOT_APPLICABLE. |
data.features.floorCovering.marble | string | One of YES, NO, NOT_APPLICABLE. |
data.features.floorCovering.terracotta | string | One of YES, NO, NOT_APPLICABLE. |
data.features.floorCovering.granite | string | One of YES, NO, NOT_APPLICABLE. |
data.features.floorCovering.raisedFloor | string | One of YES, NO, NOT_APPLICABLE. |
data.features.floorCovering.quartz | string | One of YES, NO, NOT_APPLICABLE. |
data.features.floorCovering.concrete | string | One of YES, NO, NOT_APPLICABLE. |
data.features.floorCovering.antiDustConcrete | string | One of YES, NO, NOT_APPLICABLE. |
data.features.floorCovering.woodenPlank | string | One of YES, NO, NOT_APPLICABLE. |
data.features.floorCovering.antiStatic | string | One of YES, NO, NOT_APPLICABLE. |
data.features.floorCovering.vinyl | string | One of YES, NO, NOT_APPLICABLE. |
data.features.furnished | string | One of PART, FULL, NO, NOT_APPLICABLE. |
data.features.garden | object | |
data.features.garden.part | boolean | |
data.features.garden.private | boolean | |
data.features.garden.shared | boolean | |
data.features.gym | string | One of YES, NO, NOT_APPLICABLE. |
data.features.internet | object | |
data.features.internet.internetSpeedMbit | integer | 0 to . |
data.features.internet.internetAvailability | object | |
data.features.internet.propertyInternetAccess | object | |
data.features.lighting | object | |
data.features.lighting.ceiling | string | One of YES, NO, NOT_APPLICABLE. |
data.features.lighting.led | string | One of YES, NO, NOT_APPLICABLE. |
data.features.lighting.window | string | One of YES, NO, NOT_APPLICABLE. |
data.features.mezzanine | string | One of YES, NO, NOT_APPLICABLE. |
data.features.propertyOrientation | string | One of NORTH, EAST, SOUTH, WEST, NORTH_EAST, SOUTH_EAST, SOUTH_WEST, NORTH_WEST. |
data.features.receptionist | string | One of YES, NO, NOT_APPLICABLE. |
data.features.security | object | |
data.features.security.buildingIntercom | string | One of YES, NO, NOT_APPLICABLE, VIDEO, DOOR_PHONE. |
data.features.security.cam | string | One of YES, NO, NOT_APPLICABLE. |
data.features.security.custodian | string | One of YES, NO, NOT_APPLICABLE. |
data.features.security.custodianRoom | string | One of YES, NO, NOT_APPLICABLE. |
data.features.security.digitalLock | string | One of YES, NO, NOT_APPLICABLE. |
data.features.security.emergencyCall | string | One of YES, NO, NOT_APPLICABLE. |
data.features.security.fireSprinkler | string | One of YES, NO, NOT_APPLICABLE. |
data.features.security.fireAlarm | string | One of YES, NO, NOT_APPLICABLE. |
data.features.security.intruderAlarm | string | One of YES, NO, NOT_APPLICABLE. |
data.features.security.reinforcedDoor | string | One of YES, NO, NOT_APPLICABLE. |
data.features.security.safe | string | One of YES, NO, NOT_APPLICABLE. |
data.features.wheelchairUse | string | One of YES, NO, NOT_APPLICABLE. |
data.features.wineCellar | string | One of YES, NO, NOT_APPLICABLE. |
data.features.residential | object | |
data.features.residential.assistedLiving | string | One of YES, NO, NOT_APPLICABLE. |
data.features.residential.chimney | string | One of YES, NO, NOT_APPLICABLE. |
data.features.residential.flatSharePossible | string | One of YES, NO, NOT_APPLICABLE. |
data.features.residential.hammam | string | One of YES, NO, NOT_APPLICABLE. |
data.features.residential.houseCleaningService | string | One of YES, NO, NOT_APPLICABLE. |
data.features.residential.jacuzzi | string | One of YES, NO, NOT_APPLICABLE. |
data.features.residential.loggia | string | One of YES, NO, NOT_APPLICABLE. |
data.features.residential.sauna | string | One of YES, NO, NOT_APPLICABLE. |
data.features.residential.swimmingPool | string | One of YES, NO, INSIDE, OUTSIDE, INSIDE_AND_OUTSIDE, NOT_APPLICABLE. |
data.features.residential.tennisField | string | One of YES, NO, NOT_APPLICABLE, PRIVATE, SHARED. |
data.features.residential.tv | string | One of SAT, CABLE, OTHER. |
data.features.residential.veranda | string | One of YES, NO, NOT_APPLICABLE. |
data.features.residential.laundryRoom | string | One of YES, NO, NOT_APPLICABLE. |
data.features.residential.countrySpecific | object | |
data.features.commercial | object | |
data.features.commercial.accessibleByTrucks | string | One of YES, NO, NOT_APPLICABLE, SEPARATED_TRUCK_ACCESS. |
data.features.commercial.auditorium | string | One of YES, NO, NOT_APPLICABLE. |
data.features.commercial.bar | string | One of YES, NO, NOT_APPLICABLE. |
data.features.commercial.buildingVentilation | string | One of YES, NO, NOT_APPLICABLE. |
data.features.commercial.cafeteria | string | One of YES, NO, NOT_APPLICABLE. |
data.features.commercial.coldStore | string | One of YES, NO, NOT_APPLICABLE. |
data.features.commercial.companyRestaurant | string | One of YES, NO, NOT_APPLICABLE. |
data.features.commercial.droppedCeiling | string | One of YES, NO, NOT_APPLICABLE. |
data.features.commercial.engineGenerator | string | One of YES, NO, NOT_APPLICABLE. |
data.features.commercial.exhaustHood | string | One of YES, NO, NOT_APPLICABLE. |
data.features.commercial.flexibleRoomLayout | string | One of YES, NO, NOT_APPLICABLE. |
data.features.commercial.heatedTerrace | string | One of YES, NO, NOT_APPLICABLE. |
data.features.commercial.liftingPlatform | string | One of YES, NO, NOT_APPLICABLE. |
data.features.commercial.numberOfStorageCells | integer | 0 to 999999. |
data.features.commercial.overheadCrane | string | One of YES, NO, NOT_APPLICABLE. |
data.features.commercial.restaurantSeats | integer | 0 to 999999. |
data.features.commercial.restaurantSeatsOutside | integer | 0 to 999999. |
data.features.commercial.teaKitchen | string | One of YES, NO, NOT_APPLICABLE. |
data.features.commercial.truckManeuveringArea | string | One of YES, NO, NOT_APPLICABLE. |
data.features.commercial.verticalSlidingDoor | string | One of YES, NO, NOT_APPLICABLE. |
data.features.commercial.wallSiding | string | One of YES, NO, NOT_APPLICABLE, DOUBLE, DECORATIVE. |
data.features.commercial.countrySpecific | object | |
data.features.parking | object | |
data.features.parking.chargingStation | string | One of YES, NO, NOT_APPLICABLE. |
data.features.parking.bikeParking | string | One of YES, NO, NOT_APPLICABLE. |
data.features.plot | object | |
data.features.plot.usageFor | object | |
data.features.plot.developmentInfrastructure | object | |
data.features.plot.shortTermConstructible | string | One of YES, NO, NOT_APPLICABLE. |
data.features.plot.brownfield | string | One of YES, NO, NOT_APPLICABLE. |
data.features.plot.buildingPermission | string | One of YES, NO, NOT_APPLICABLE. |
data.features.plot.demolitionSuggested | string | One of YES, NO, NOT_APPLICABLE. |
data.features.plot.fencedPlot | string | One of YES, NO, NOT_APPLICABLE. |
data.features.plot.isTerracedArea | boolean | |
data.features.plot.tilt | string | One of NONE, MINOR, SIGNIFICANT, STEEP. |
data.features.plot.countrySpecific | object | |
data.structure | object | |
data.structure.building | object | |
data.structure.building.attic | string | One of CONVERTED, PART_CONVERTED, CONVERTIBLE, ISOLATED, ACCESSIBLE_WITH_FIXED_STAIRS. |
data.structure.building.balconyDirection | string | One of NORTH, EAST, SOUTH, WEST, NORTH_EAST, SOUTH_EAST, SOUTH_WEST, NORTH_WEST. |
data.structure.building.gardenOrientation | string | One of NORTH, EAST, SOUTH, WEST, NORTH_EAST, SOUTH_EAST, SOUTH_WEST, NORTH_WEST. |
data.structure.building.barrierFree | string | One of YES, NO, NOT_APPLICABLE. |
data.structure.building.bath | object | |
data.structure.building.cellar | string | One of YES, NO, PART, NOT_APPLICABLE. |
data.structure.building.elevator | object | |
data.structure.building.kitchen | object | |
data.structure.building.numberOfFloors | integer | 1 to 999. |
data.structure.building.numberOfFacades | integer | 1 to 999999. |
data.structure.building.roomHeight | number | 0 to . |
data.structure.building.offeredFloors | integer | 1 to 5. |
data.structure.building.roofStyle | string | One of HALF_HIPPED_ROOF, GAMBREL, MONO_PITCHED_ROOF, GABLE, HIP_ROOF, FLAT_ROOF, PYRAMIDAL_ROOF, OTHER. |
data.structure.building.locationInBuilding | string | One of GROUNDFLOOR, HALF_BASEMENT, ROOF_STOREY. |
data.structure.building.locationAtCorner | string | One of YES, NO, NOT_APPLICABLE. |
data.structure.building.calm | string | One of YES, NO, NOT_APPLICABLE. |
data.structure.building.withView | object | |
data.structure.building.luminous | string | One of YES, NO, NOT_APPLICABLE. |
data.structure.building.window | object | |
data.structure.building.shape | string | One of L_SHAPE, U_SHAPE, V_SHAPE, RECTANGULAR, SQUARE, OTHER. |
data.structure.building.hasSplitFloor | boolean | |
data.structure.building.wallConstructionMaterial | string[] | One of MASSIVE_WOOD, CINDER_BLOCK, INSULATING_CINDER_BLOCK, CELLULAR_CONCRETE, BRICK, HONEYCOMB_BRICK, LIMESTONE, WOOD_FRAME, METAL_FRAME. |
data.structure.rooms | object | |
data.structure.rooms.numberOfRooms | number | 0 to 999999. |
data.structure.rooms.numberOfBedRooms | integer | 0 to 999999. |
data.structure.rooms.numberOfBathRooms | integer | 0 to 999999. |
data.structure.rooms.numberOfToilets | integer | 0 to 999999. |
data.structure.rooms.numberOfBalconies | integer | 0 to 999999. |
data.structure.rooms.numberOfTerraces | integer | 0 to 999999. |
data.structure.rooms.numberOfKitchens | integer | 0 to 999999. |
data.structure.rooms.numberOfUnits | integer | 0 to 999999. |
data.structure.commercial | object | |
data.structure.commercial.floorLoad | integer | |
data.structure.commercial.floorLoadUpperFloors | number | |
data.structure.commercial.hallHeight | number | 0 to . |
data.structure.commercial.numberOfBeds | integer | 0 to 999999. |
data.structure.commercial.numberOfLoadingDocks | integer | 0 to 999999. |
data.structure.commercial.numberOfDesks | integer | 0 to 999999. |
data.structure.commercial.numberOfMeetingRooms | integer | 0 to 999999. |
data.structure.commercial.numberOfOfficeRooms | integer | 0 to 999999. |
data.structure.commercial.windowFront | number | 0 to . |
data.structure.parkingLots | object | |
data.structure.parkingLots.outside | integer | 0 to 999999. |
data.structure.parkingLots.streetParking | integer | 0 to 999999. |
data.structure.parkingLots.carport | integer | 0 to 999999. |
data.structure.parkingLots.garage | integer | 0 to 999999. |
data.structure.parkingLots.doubleGarage | integer | 0 to 999999. |
data.structure.parkingLots.duplex | integer | 0 to 999999. |
data.structure.parkingLots.garageArea | integer | 0 to 999999. |
data.structure.parkingLots.parkingArea | integer | 0 to 999999. |
data.structure.parkingLots.carPark | integer | 0 to 999999. |
data.structure.parkingLots.underground | integer | 0 to 999999. |
data.structure.parkingLots.boatDock | integer | 0 to 999999. |
data.texts | object | |
data.texts.headline | map<string> | |
data.texts.description | map<string> | |
data.texts.features | map<string> | |
data.texts.extendedInformation | map<string> | |
data.texts.area | map<string> | |
data.management | object | |
data.management.isImmediatelyAvailable | boolean | |
data.management.availableFrom | string (date) | |
data.management.availableUntil | string (date) | |
data.management.isForInvestment | boolean | |
data.management.heritageProtected | string | One of YES, NO, NOT_APPLICABLE. |
data.management.marketStatus | string | One of SOLD, RENTED, REFERENCE, RESERVED, UNDER_OFFER. |
data.management.projectStatus | string | One of BUILDING_PERMISSION, COMMERCIAL_LAUNCH, CONSTRUCTION_START, UNDER_CONSTRUCTION, SHELL_WORKS, FINISHING_WORKS, LAST_CHANCE, PROJECT_ENDED. |
data.management.marketLabel | string | |
data.management.isRented | boolean | |
data.management.useFor | string | One of LIVING, COMMERCIAL, MIXED, OFFICE, INDUSTRIAL. |
data.management.isForHolidayRental | boolean | |
data.management.rent | object | |
data.management.rent.favouredGender | string | One of MALE, FEMALE, OTHER. |
data.management.rent.minRentalTime | integer | |
data.management.rent.maxRentalTime | integer | |
data.management.rent.rentalTimeUnit | string | One of DAY, WEEK, MONTH, YEAR. |
data.management.rent.certificateOfEligibilityNeeded | string | One of YES, NO, NOT_APPLICABLE. |
data.management.rent.maxPersons | integer | |
data.management.rent.nonSmoker | string | One of YES, NO, NOT_APPLICABLE. |
data.management.rent.petsAllowed | string | One of YES, NO, NOT_APPLICABLE. |
data.management.rent.isShortTimeRental | boolean | |
data.management.compulsoryAuction | object | |
data.management.compulsoryAuction.auctionLocation | string | |
data.management.compulsoryAuction.auctionSpace | string | |
data.management.compulsoryAuction.cancellationDate | string (date) | |
data.management.compulsoryAuction.coOwnership | string | |
data.management.compulsoryAuction.countyCourt | string | |
data.management.compulsoryAuction.dateOfAuction | string (date) | |
data.management.compulsoryAuction.isDiscretionarySale | boolean | |
data.management.compulsoryAuction.distributionPlanNumber | string | |
data.management.compulsoryAuction.fileReferenceAtCountyCourt | string | |
data.management.compulsoryAuction.lastChangeDate | string (date) | |
data.management.compulsoryAuction.insolvencyAdministrator | string | |
data.management.compulsoryAuction.owner | string | |
data.management.compulsoryAuction.recordationDate | string (date) | |
data.management.compulsoryAuction.additionalDate | string (date) | |
data.management.compulsoryAuction.isWithoutValueLimits | boolean | |
data.management.compulsoryAuction.isSplittingAuction | boolean | |
data.countrySpecific | object | |
data.countrySpecific.de | object | |
data.countrySpecific.fr | object | |
data.countrySpecific.fr.business | object | |
data.contact | object | |
data.contact.salutation | string | One of Mr, Mrs, Miss, Ms, Mx, Sir, Dame, Dr, Cllr, Lady, Lord. |
data.contact.firstName | string | |
data.contact.lastName | string | |
data.contact.name | string | |
data.contact.emailAddress | string | |
data.contact.phoneNumber | string | |
data.contact.mobilePhoneNumber | string | |
data.contact.imageURL | string | |
data.contact.userHomepage | string | |
data.contact.postalCode | string | |
data.contact.city | string | |
data.contact.street | string | |
data.contact.houseNumber | string | |
data.contact.country | string | |
data.contact.preferredContactType | string | One of ANONYMOUS, BY_PHONE, BY_EMAIL, OWN_WEBSITE. |
data.contact.contactNote | map<string> | |
data.contact.displayedInformation | object | |
data.contact.displayedInformation.mainContactPerson | object | |
data.contact.displayedInformation.additionalContactPerson | object | |
data.links | object | |
data.links.externalLinks | object[] | |
data.links.externalLinks[].url | string | |
data.links.externalLinks[].urlType | string | One of MAP, MOVIE, PANORAMA, REVOCATION_INSTRUCTION, OFFERER_DETAIL_PAGE. |
data.links.externalLinks[].title | string | |
data.links.virtualTours | object[] | |
data.links.virtualTours[].url | string | |
data.links.virtualTours[].provider | string | |
data.links.virtualTours[].title | string | |
metadata | object | |
metadata.source | object | |
metadata.source.offererMarketingKey | string | |
metadata.source.offererEstateId | string | |
metadata.source.offererEstateGroupId | string | |
metadata.portalWebKey | string | |
userDefined | object[] | |
userDefined[].name | string | |
userDefined[].value | string | |
userDefined[].utyp | string | One of string, integer, boolean, decimal. |
userDefined[].modus | string | |
media | object[] | |
media[].externalMediaId | string | |
media[].title | string | |
contact | object | |
contact.salutation | string | One of Mr, Mrs, Miss, Ms, Mx, Sir, Dame, Dr, Cllr, Lady, Lord. |
contact.firstName | string | |
contact.lastName | string | |
contact.name | string | |
contact.emailAddress | string | |
contact.phoneNumber | string | |
contact.mobilePhoneNumber | string | |
contact.imageURL | string | |
contact.userHomepage | string | |
contact.postalCode | string | |
contact.city | string | |
contact.street | string | |
contact.houseNumber | string | |
contact.country | string | |
contact.preferredContactType | string | One of ANONYMOUS, BY_PHONE, BY_EMAIL, OWN_WEBSITE. |
contact.contactNote | map<string> | |
contact.displayedInformation | object | |
contact.displayedInformation.mainContactPerson | object | |
contact.displayedInformation.mainContactPerson.name | boolean | |
contact.displayedInformation.mainContactPerson.phone | boolean | |
contact.displayedInformation.mainContactPerson.mobilePhone | boolean | |
contact.displayedInformation.mainContactPerson.email | boolean | |
contact.displayedInformation.mainContactPerson.address | boolean | |
contact.displayedInformation.mainContactPerson.companyName | boolean | |
contact.displayedInformation.mainContactPerson.fax | boolean | |
contact.displayedInformation.additionalContactPerson | object | |
contact.displayedInformation.additionalContactPerson.name | boolean | |
contact.displayedInformation.additionalContactPerson.phone | boolean | |
contact.displayedInformation.additionalContactPerson.mobilePhone | boolean | |
contact.displayedInformation.additionalContactPerson.email | boolean | |
contact.displayedInformation.additionalContactPerson.address | boolean | |
contact.displayedInformation.additionalContactPerson.companyName | boolean | |
contact.displayedInformation.additionalContactPerson.fax | boolean |
Example
curl -X POST "https://api.athaus.ai/v1/listings" \
-H "Authorization: Bearer ath_live_..." \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"data":{"estateType":"APARTMENT","estateSubType":{"apartment":"MULTI_STOREY"},"distributionType":"BUY","location":{"postalcode":"10435","city":"Berlin","street":"Kastanienallee","houseNumber":"12","country":"DEU","floorNumber":3,"geometry":{"type":"Point","coordinates":[13.4128,52.5395]}},"prices":{"currency":"EUR","buy":{"price":{"amount":350000}}},"spaces":{"spaceMeasureUnit":"SQUARE_METER","residential":{"livingSpace":62}},"structure":{"rooms":{"numberOfRooms":2,"numberOfBedRooms":1,"numberOfBathRooms":1}},"conditions":{"yearOfConstruction":1998},"texts":{"headline":{"de":"Helle Zweizimmerwohnung am Kastanienallee-Kiez","en":"Bright two-room flat"},"description":{"de":"Ruhige Wohnung im dritten Stock mit Balkon zum Hof."}}},"metadata":{"source":{"offererEstateId":"WE-12","offererMarketingKey":"WE-12"}},"userDefined":[{"name":"de.livingSpaceStandard","value":"WOFLV","utyp":"string"},{"name":"price.associationFee","value":"285.50","utyp":"decimal"}]}'Response
On success the status is 202 with ListingReceipt.
ListingReceipt
| Field | Type | Description |
|---|---|---|
requestId | string | |
listingId | string | |
externalListingId | string | |
warnings | object[] | |
warnings[].type | string | |
warnings[].message | string |
Response headers
| Header | Description |
|---|---|
Request-Id | Identifies this request. Quote it in a support request. |
Athaus-Version | The API version of this response: v1. |
Athaus-Release | The release of v1 that answered, for example 1.0. A label for support and changelogs; no request can select it. |
RateLimit-Policy | The quota policy of the bucket that applies. |
RateLimit | Remaining quota and seconds until the bucket is full again. |
Idempotent-Replayed | true when this is the stored answer to an earlier request with the same Idempotency-Key. |
Errors
Every error arrives as problem details. Branch on code, not on title or detail.
| Status | Codes | Meaning |
|---|---|---|
400 | invalid_query, api_version_unsupported, invalid_body, profile_unsupported | Invalid request. |
401 | unauthorized | Missing or invalid API key. |
403 | insufficient_permissions, plan_required | The key lacks a right, or the plan does not include API access. |
404 | not_found | Nothing under this ID. |
409 | address_already_exists, reference_already_exists, idempotency_key_in_use, idempotency_outcome_unknown | The request conflicts with the state of the resource (for example a duplicate), or with an idempotency key. |
413 | payload_too_large | The request body is larger than 512 KB. |
415 | invalid_input | The request body is not JSON. Send Content-Type: application/json. |
422 | idempotency_key_reused | The idempotency key was already used with a different request body. |
429 | rate_limited | Rate limit exceeded. |
500 | internal_error | Server error. |
Keep reading
REST API: authentication with an API key
Every call to /v1 carries an API key as a bearer token. Where to get one, which scopes it carries and what does not work.
REST API: errors as problem details
Every error from /v1 is an RFC 9457 problem with a real HTTP status, a code to branch on and a request id for support.