AthausDoku

Publish a listing

Aufruf, Parameter, Antwort und Fehler von POST /v1/listings/{externalListingId}/publish.

Zuletzt aktualisiert:

Puts a listing online on athaus.ai and on its connected portals. The same checks apply as for the button in the app: the plan, the mandatory details, the energy certificate, a photo. With the scope approve AND the office's automation for publishing set to automatic, the listing goes online now and the answer is 200 with the listing, whose status is active. Otherwise nothing goes online: a proposal waits for a person in the office to say yes in the app, and the answer is 202 with the proposal and a Location header; poll GET /proposals/{id} or the listing's status. A listing that is online already answers 200 unchanged. A sold or rented listing (409 listing_closed) and a reserved one (409 listing_reserved) do not go online. A listing that is not complete answers 409 listing_incomplete with errors naming what is missing. If the office switched publishing off, the answer is 409 automation_disabled. Idempotency-Key is required. A test key never publishes: it answers 409 listing_blocked at every level. Needs write access to listings and the scope propose.

Braucht den Scope propose.

Aufruf

POST https://api.athaus.ai/v1/listings/{externalListingId}/publish

Parameter

Pfad

NameTypPflichtBeschreibung
externalListingIdstringjaYour 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.

Kopf

NameTypPflichtBeschreibung
Athaus-VersionstringneinOptional 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-KeystringjaRequired: this operation reaches people outside the office, and a message cannot be taken back. Send a fresh UUID per message and reuse it only to retry the same request: the same key with the same body returns the first answer (a stored 202 stays a 202 with the same proposal) and sends nothing twice. 1 to 255 characters, kept for 24 hours, scoped to the API key and this operation. A different body under the same key is a 422; while the first request still runs it is a 409. Without the header the answer is 400 idempotency_key_missing.

Beispiel

curl -X POST "https://api.athaus.ai/v1/listings/WE-12/publish" \
  -H "Authorization: Bearer ath_live_..." \
  -H "Idempotency-Key: $(uuidgen)"

Antwort

Bei Erfolg kommt 200 oder 202 mit ListingResponse.

ListingResponse

FeldTypBeschreibung
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.estateTypestringEines von HOUSE, APARTMENT, PLOT, OFFICE, TRADING, GASTRONOMY_HOTEL, STORAGE_PRODUCTION, AGRICULTURE_FORESTRY, PARKING, SENIOR, PROJECT, MISCELLANEOUS.
listing.data.estateSubTypeobject
listing.data.distributionTypestringEines von 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 bis 999.
listing.data.location.entrancestring
listing.data.location.statestring
listing.data.location.countrystringEine von 249 Angaben der Liste im Standard.
listing.data.location.geometryobject
listing.data.location.showAddressbooleanVorgabe true.
listing.data.location.locationNotemap<string>
listing.data.pricesobject
listing.data.prices.currencystringEine von 180 Angaben der Liste im Standard. Vorgabe 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.spaceMeasureUnitstringEines von SQUARE_METER, SQUARE_INCH, SQUARE_FOOT, SQUARE_YARD, HECTARE, ACRE. Vorgabe SQUARE_METER.
listing.data.spaces.buildingFrontnumber0 bis 99999999.
listing.data.spaces.kitchenSpacenumber0 bis 99999999.
listing.data.spaces.overallSpacenumber0 bis 99999999.
listing.data.spaces.usableFloorSpacenumber0 bis 99999999.
listing.data.spaces.spaceMaxnumber0 bis 99999999.
listing.data.spaces.spaceMinnumber0 bis 99999999.
listing.data.spaces.plotSpacenumber0 bis 99999999.
listing.data.spaces.plotFrontnumber0 bis 99999999.
listing.data.spaces.additionalSpacenumber0 bis 99999999.
listing.data.spaces.residentialobject
listing.data.spaces.commercialobject
listing.data.conditionsobject
listing.data.conditions.buildStatestringEines von 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.ageStatestringEines von OLD, NEW.
listing.data.conditions.lastModernisationinteger
listing.data.conditions.constructionStylestringEines von PREFABRICATED, SOLID, SOLID_PREFABRICATED, TIMBERHOUSE, WOOD_PREFABRICATED, UNSPECIFIED.
listing.data.conditions.yearOfConstructioninteger1000 bis 3000.
listing.data.energyobject
listing.data.energy.energyTypeobject
listing.data.energy.countrySpecificobject
listing.data.featuresobject
listing.data.features.accessibleFromStreetstringEines von YES, NO, NOT_APPLICABLE.
listing.data.features.airconditionstringEines von YES, PART, NO, NOT_APPLICABLE.
listing.data.features.entranceHallstringEines von YES, NO, NOT_APPLICABLE.
listing.data.features.floorCoveringobject
listing.data.features.furnishedstringEines von PART, FULL, NO, NOT_APPLICABLE.
listing.data.features.gardenobject
listing.data.features.gymstringEines von YES, NO, NOT_APPLICABLE.
listing.data.features.internetobject
listing.data.features.lightingobject
listing.data.features.mezzaninestringEines von YES, NO, NOT_APPLICABLE.
listing.data.features.propertyOrientationstringEines von NORTH, EAST, SOUTH, WEST, NORTH_EAST, SOUTH_EAST, SOUTH_WEST, NORTH_WEST.
listing.data.features.receptioniststringEines von YES, NO, NOT_APPLICABLE.
listing.data.features.securityobject
listing.data.features.wheelchairUsestringEines von YES, NO, NOT_APPLICABLE.
listing.data.features.wineCellarstringEines von 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.heritageProtectedstringEines von YES, NO, NOT_APPLICABLE.
listing.data.management.marketStatusstringEines von SOLD, RENTED, REFERENCE, RESERVED, UNDER_OFFER.
listing.data.management.projectStatusstringEines von 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.useForstringEines von 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.salutationstringEines von 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.preferredContactTypestringEines von 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.salutationstringEines von 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.preferredContactTypestringEines von 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[].kindstringEines von 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[].utypstringEines von 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.statusstringEines von draft, active, paused, reserved, closed.
listing.createdAtstring (date-time)
listing.updatedAtstring (date-time)

Köpfe der Antwort

KopfBeschreibung
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.
LocationThe proposal: /v1/proposals/{id}.

Fehler

Jeder Fehler kommt als Problem Details. Verzweige auf code, nicht auf title oder detail.

StatusCodesBedeutung
400api_version_unsupported, idempotency_key_missingInvalid request.
401unauthorizedMissing or invalid API key.
403insufficient_permissions, plan_required, plan_requiredThe key lacks a right, or the plan does not include API access.
404not_foundNothing under this ID.
409listing_incomplete, listing_reserved, listing_closed, listing_blocked, automation_disabled, idempotency_key_in_use, idempotency_outcome_unknownThe request conflicts with the state of the resource (for example a duplicate), or with an idempotency key.
422The idempotency key was already used with a different request body.
429rate_limitedRate limit exceeded.
500internal_errorServer error.

Weiter lesen

Auf dieser Seite