AthausDocs

Set the status of a unit

Request, parameters, response and errors of POST /v1/listings/{externalListingId}/unit-status.

Last updated:

Sets the status of a listing that is a unit of a project, as the buttons of the project's unit list do: free, option, reserved, sold or rented. The answer is 200 with the listing. Any status other than free takes a running listing off the market (its status becomes paused); reserved, sold and rented also set the listing's own reserved and closed state. A repeat with the same status changes nothing. A listing that is not a unit of a project answers 409 listing_not_unit; a status that does not fit the project (sold in a rental project, rented in a project for sale) answers 409 unit_status_invalid. A change emits the event unit.status_updated. Needs write access to listings.

Requires the scope propose.

Request

POST https://api.athaus.ai/v1/listings/{externalListingId}/unit-status

Parameters

Path

NameTypeRequiredDescription
externalListingIdstringyesYour reference of the listing: the value of metadata.source.offererMarketingKey. A listing without one has its own listingId here, and the listingId always works in the path. 1 to 128 letters, digits, dots, underscores or hyphens, not starting or ending with a dot.

Header

NameTypeRequiredDescription
Athaus-VersionstringnoOptional 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-KeystringnoMakes 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.

FieldTypeDescription
statusstringOurs, not OpenImmo. A rental project knows free, option, reserved and rented; a project for sale knows free, option, reserved and sold. One of free, option, reserved, sold, rented.

Example

curl -X POST "https://api.athaus.ai/v1/listings/WE-12/unit-status" \
  -H "Authorization: Bearer ath_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"status":"reserved"}'

Response

On success the status is 200 with ListingResponse.

ListingResponse

FieldTypeDescription
listingobjectThe listing as stored. data, metadata, contact and media are the OpenImmo 2.0 members; listingId, status, createdAt and updatedAt are our additive members (status: publication state in Athaus, closed means sold or let).
listing.dataobject
listing.data.estateTypestringOne of HOUSE, APARTMENT, PLOT, OFFICE, TRADING, GASTRONOMY_HOTEL, STORAGE_PRODUCTION, AGRICULTURE_FORESTRY, PARKING, SENIOR, PROJECT, MISCELLANEOUS.
listing.data.estateSubTypeobject
listing.data.distributionTypestringOne of BUY, RENT, COMPULSORY_AUCTION, BUY_AUCTION.
listing.data.locationobject
listing.data.location.postalcodestring
listing.data.location.citystring
listing.data.location.streetstring
listing.data.location.houseNumberstring
listing.data.location.unitstring
listing.data.location.staircasestring
listing.data.location.floorNumberinteger-5 to 999.
listing.data.location.entrancestring
listing.data.location.statestring
listing.data.location.countrystringOne of 249 values from the list in the standard.
listing.data.location.geometryobject
listing.data.location.showAddressbooleanDefault true.
listing.data.location.locationNotemap<string>
listing.data.pricesobject
listing.data.prices.currencystringOne of 180 values from the list in the standard. Default EUR.
listing.data.prices.buyobject
listing.data.prices.rentobject
listing.data.prices.compulsoryAuctionobject
listing.data.prices.buyAuctionobject
listing.data.prices.brokerageFeeany
listing.data.prices.showPriceboolean
listing.data.prices.priceNotemap<string>
listing.data.prices.countrySpecificobject
listing.data.spacesobject
listing.data.spaces.spaceMeasureUnitstringOne of SQUARE_METER, SQUARE_INCH, SQUARE_FOOT, SQUARE_YARD, HECTARE, ACRE. Default SQUARE_METER.
listing.data.spaces.buildingFrontnumber0 to 99999999.
listing.data.spaces.kitchenSpacenumber0 to 99999999.
listing.data.spaces.overallSpacenumber0 to 99999999.
listing.data.spaces.usableFloorSpacenumber0 to 99999999.
listing.data.spaces.spaceMaxnumber0 to 99999999.
listing.data.spaces.spaceMinnumber0 to 99999999.
listing.data.spaces.plotSpacenumber0 to 99999999.
listing.data.spaces.plotFrontnumber0 to 99999999.
listing.data.spaces.additionalSpacenumber0 to 99999999.
listing.data.spaces.residentialobject
listing.data.spaces.commercialobject
listing.data.conditionsobject
listing.data.conditions.buildStatestringOne 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.
listing.data.conditions.ageStatestringOne of OLD, NEW.
listing.data.conditions.lastModernisationinteger
listing.data.conditions.constructionStylestringOne of PREFABRICATED, SOLID, SOLID_PREFABRICATED, TIMBERHOUSE, WOOD_PREFABRICATED, UNSPECIFIED.
listing.data.conditions.yearOfConstructioninteger1000 to 3000.
listing.data.energyobject
listing.data.energy.energyTypeobject
listing.data.energy.countrySpecificobject
listing.data.featuresobject
listing.data.features.accessibleFromStreetstringOne of YES, NO, NOT_APPLICABLE.
listing.data.features.airconditionstringOne of YES, PART, NO, NOT_APPLICABLE.
listing.data.features.entranceHallstringOne of YES, NO, NOT_APPLICABLE.
listing.data.features.floorCoveringobject
listing.data.features.furnishedstringOne of PART, FULL, NO, NOT_APPLICABLE.
listing.data.features.gardenobject
listing.data.features.gymstringOne of YES, NO, NOT_APPLICABLE.
listing.data.features.internetobject
listing.data.features.lightingobject
listing.data.features.mezzaninestringOne of YES, NO, NOT_APPLICABLE.
listing.data.features.propertyOrientationstringOne of NORTH, EAST, SOUTH, WEST, NORTH_EAST, SOUTH_EAST, SOUTH_WEST, NORTH_WEST.
listing.data.features.receptioniststringOne of YES, NO, NOT_APPLICABLE.
listing.data.features.securityobject
listing.data.features.wheelchairUsestringOne of YES, NO, NOT_APPLICABLE.
listing.data.features.wineCellarstringOne of YES, NO, NOT_APPLICABLE.
listing.data.features.residentialobject
listing.data.features.commercialobject
listing.data.features.parkingobject
listing.data.features.plotobject
listing.data.structureobject
listing.data.structure.buildingobject
listing.data.structure.roomsobject
listing.data.structure.commercialobject
listing.data.structure.parkingLotsobject
listing.data.textsobject
listing.data.texts.headlinemap<string>
listing.data.texts.descriptionmap<string>
listing.data.texts.featuresmap<string>
listing.data.texts.extendedInformationmap<string>
listing.data.texts.areamap<string>
listing.data.managementobject
listing.data.management.isImmediatelyAvailableboolean
listing.data.management.availableFromstring (date)
listing.data.management.availableUntilstring (date)
listing.data.management.isForInvestmentboolean
listing.data.management.heritageProtectedstringOne of YES, NO, NOT_APPLICABLE.
listing.data.management.marketStatusstringOne of SOLD, RENTED, REFERENCE, RESERVED, UNDER_OFFER.
listing.data.management.projectStatusstringOne of BUILDING_PERMISSION, COMMERCIAL_LAUNCH, CONSTRUCTION_START, UNDER_CONSTRUCTION, SHELL_WORKS, FINISHING_WORKS, LAST_CHANCE, PROJECT_ENDED.
listing.data.management.marketLabelstring
listing.data.management.isRentedboolean
listing.data.management.useForstringOne of LIVING, COMMERCIAL, MIXED, OFFICE, INDUSTRIAL.
listing.data.management.isForHolidayRentalboolean
listing.data.management.rentobject
listing.data.management.compulsoryAuctionobject
listing.data.countrySpecificobject
listing.data.countrySpecific.deobject
listing.data.countrySpecific.frobject
listing.data.contactobject
listing.data.contact.salutationstringOne of Mr, Mrs, Miss, Ms, Mx, Sir, Dame, Dr, Cllr, Lady, Lord.
listing.data.contact.firstNamestring
listing.data.contact.lastNamestring
listing.data.contact.namestring
listing.data.contact.emailAddressstring
listing.data.contact.phoneNumberstring
listing.data.contact.mobilePhoneNumberstring
listing.data.contact.imageURLstring
listing.data.contact.userHomepagestring
listing.data.contact.postalCodestring
listing.data.contact.citystring
listing.data.contact.streetstring
listing.data.contact.houseNumberstring
listing.data.contact.countrystring
listing.data.contact.preferredContactTypestringOne of ANONYMOUS, BY_PHONE, BY_EMAIL, OWN_WEBSITE.
listing.data.contact.contactNotemap<string>
listing.data.contact.displayedInformationobject
listing.data.linksobject
listing.data.links.externalLinksobject[]
listing.data.links.virtualToursobject[]
listing.metadataobject
listing.metadata.sourceobject
listing.metadata.source.offererMarketingKeystring
listing.metadata.source.offererEstateIdstring
listing.metadata.source.offererEstateGroupIdstring
listing.metadata.portalWebKeystring
listing.contactobject
listing.contact.salutationstringOne of Mr, Mrs, Miss, Ms, Mx, Sir, Dame, Dr, Cllr, Lady, Lord.
listing.contact.firstNamestring
listing.contact.lastNamestring
listing.contact.namestring
listing.contact.emailAddressstring
listing.contact.phoneNumberstring
listing.contact.mobilePhoneNumberstring
listing.contact.imageURLstring
listing.contact.userHomepagestring
listing.contact.postalCodestring
listing.contact.citystring
listing.contact.streetstring
listing.contact.houseNumberstring
listing.contact.countrystring
listing.contact.preferredContactTypestringOne of ANONYMOUS, BY_PHONE, BY_EMAIL, OWN_WEBSITE.
listing.contact.contactNotemap<string>
listing.contact.displayedInformationobject
listing.contact.displayedInformation.mainContactPersonobject
listing.contact.displayedInformation.additionalContactPersonobject
listing.mediaobject[]
listing.media[].externalMediaIdstring
listing.media[].titlestring
listing.media[].idstring (uuid)The id of the file in /files.
listing.media[].kindstringOne of photo, floor_plan, document.
listing.media[].documentTypestring
listing.media[].fileNamestring
listing.media[].mimeTypestring
listing.media[].sizeBytesinteger
listing.media[].widthinteger
listing.media[].heightinteger
listing.media[].contentUrlstringThe address of the bytes; fetch it with the same API key.
listing.userDefinedobject[]
listing.userDefined[].namestring
listing.userDefined[].valuestring
listing.userDefined[].utypstringOne of string, integer, boolean, decimal.
listing.userDefined[].modusstring
listing.listingIdstring (uuid)
listing.projectIdstring (uuid)Present when the listing is a unit of a new-build project: the projectId of that project. Read-only; POST /projects/{externalProjectId}/assign moves a listing into a project.
listing.statusstringOne of draft, active, paused, reserved, closed.
listing.createdAtstring (date-time)
listing.updatedAtstring (date-time)

Response headers

HeaderDescription
Request-IdIdentifies this request. Quote it in a support request.
Athaus-VersionThe API version of this response: v1.
Athaus-ReleaseThe release of v1 that answered, for example 1.0. A label for support and changelogs; no request can select it.
RateLimit-PolicyThe quota policy of the bucket that applies.
RateLimitRemaining quota and seconds until the bucket is full again.
Idempotent-Replayedtrue 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.

StatusCodesMeaning
400api_version_unsupported, invalid_bodyInvalid request.
401unauthorizedMissing or invalid API key.
403insufficient_permissions, plan_requiredThe key lacks a right, or the plan does not include API access.
404not_foundNothing under this ID.
409listing_not_unit, unit_status_invalidThe request conflicts with the state of the resource (for example a duplicate), or with an idempotency key.
413payload_too_largeThe request body is larger than 512 KB.
415invalid_inputThe request body is not JSON. Send Content-Type: application/json.
422idempotency_key_reusedThe idempotency key was already used with a different request body.
429rate_limitedRate limit exceeded.
500internal_errorServer error.

Keep reading

On this page