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}/publishParameter
Pfad
| Name | Typ | Pflicht | Beschreibung |
|---|---|---|---|
externalListingId | string | ja | Your 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
| Name | Typ | Pflicht | Beschreibung |
|---|---|---|---|
Athaus-Version | string | nein | 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 | ja | Required: 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
| Feld | Typ | Beschreibung |
|---|---|---|
listing | object | The 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.data | object | |
listing.data.estateType | string | Eines von HOUSE, APARTMENT, PLOT, OFFICE, TRADING, GASTRONOMY_HOTEL, STORAGE_PRODUCTION, AGRICULTURE_FORESTRY, PARKING, SENIOR, PROJECT, MISCELLANEOUS. |
listing.data.estateSubType | object | |
listing.data.distributionType | string | Eines von BUY, RENT, COMPULSORY_AUCTION, BUY_AUCTION. |
listing.data.location | object | |
listing.data.location.postalcode | string | |
listing.data.location.city | string | |
listing.data.location.street | string | |
listing.data.location.houseNumber | string | |
listing.data.location.unit | string | |
listing.data.location.staircase | string | |
listing.data.location.floorNumber | integer | -5 bis 999. |
listing.data.location.entrance | string | |
listing.data.location.state | string | |
listing.data.location.country | string | Eine von 249 Angaben der Liste im Standard. |
listing.data.location.geometry | object | |
listing.data.location.showAddress | boolean | Vorgabe true. |
listing.data.location.locationNote | map<string> | |
listing.data.prices | object | |
listing.data.prices.currency | string | Eine von 180 Angaben der Liste im Standard. Vorgabe EUR. |
listing.data.prices.buy | object | |
listing.data.prices.rent | object | |
listing.data.prices.compulsoryAuction | object | |
listing.data.prices.buyAuction | object | |
listing.data.prices.brokerageFee | any | |
listing.data.prices.showPrice | boolean | |
listing.data.prices.priceNote | map<string> | |
listing.data.prices.countrySpecific | object | |
listing.data.spaces | object | |
listing.data.spaces.spaceMeasureUnit | string | Eines von SQUARE_METER, SQUARE_INCH, SQUARE_FOOT, SQUARE_YARD, HECTARE, ACRE. Vorgabe SQUARE_METER. |
listing.data.spaces.buildingFront | number | 0 bis 99999999. |
listing.data.spaces.kitchenSpace | number | 0 bis 99999999. |
listing.data.spaces.overallSpace | number | 0 bis 99999999. |
listing.data.spaces.usableFloorSpace | number | 0 bis 99999999. |
listing.data.spaces.spaceMax | number | 0 bis 99999999. |
listing.data.spaces.spaceMin | number | 0 bis 99999999. |
listing.data.spaces.plotSpace | number | 0 bis 99999999. |
listing.data.spaces.plotFront | number | 0 bis 99999999. |
listing.data.spaces.additionalSpace | number | 0 bis 99999999. |
listing.data.spaces.residential | object | |
listing.data.spaces.commercial | object | |
listing.data.conditions | object | |
listing.data.conditions.buildState | string | Eines 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.ageState | string | Eines von OLD, NEW. |
listing.data.conditions.lastModernisation | integer | |
listing.data.conditions.constructionStyle | string | Eines von PREFABRICATED, SOLID, SOLID_PREFABRICATED, TIMBERHOUSE, WOOD_PREFABRICATED, UNSPECIFIED. |
listing.data.conditions.yearOfConstruction | integer | 1000 bis 3000. |
listing.data.energy | object | |
listing.data.energy.energyType | object | |
listing.data.energy.countrySpecific | object | |
listing.data.features | object | |
listing.data.features.accessibleFromStreet | string | Eines von YES, NO, NOT_APPLICABLE. |
listing.data.features.aircondition | string | Eines von YES, PART, NO, NOT_APPLICABLE. |
listing.data.features.entranceHall | string | Eines von YES, NO, NOT_APPLICABLE. |
listing.data.features.floorCovering | object | |
listing.data.features.furnished | string | Eines von PART, FULL, NO, NOT_APPLICABLE. |
listing.data.features.garden | object | |
listing.data.features.gym | string | Eines von YES, NO, NOT_APPLICABLE. |
listing.data.features.internet | object | |
listing.data.features.lighting | object | |
listing.data.features.mezzanine | string | Eines von YES, NO, NOT_APPLICABLE. |
listing.data.features.propertyOrientation | string | Eines von NORTH, EAST, SOUTH, WEST, NORTH_EAST, SOUTH_EAST, SOUTH_WEST, NORTH_WEST. |
listing.data.features.receptionist | string | Eines von YES, NO, NOT_APPLICABLE. |
listing.data.features.security | object | |
listing.data.features.wheelchairUse | string | Eines von YES, NO, NOT_APPLICABLE. |
listing.data.features.wineCellar | string | Eines von YES, NO, NOT_APPLICABLE. |
listing.data.features.residential | object | |
listing.data.features.commercial | object | |
listing.data.features.parking | object | |
listing.data.features.plot | object | |
listing.data.structure | object | |
listing.data.structure.building | object | |
listing.data.structure.rooms | object | |
listing.data.structure.commercial | object | |
listing.data.structure.parkingLots | object | |
listing.data.texts | object | |
listing.data.texts.headline | map<string> | |
listing.data.texts.description | map<string> | |
listing.data.texts.features | map<string> | |
listing.data.texts.extendedInformation | map<string> | |
listing.data.texts.area | map<string> | |
listing.data.management | object | |
listing.data.management.isImmediatelyAvailable | boolean | |
listing.data.management.availableFrom | string (date) | |
listing.data.management.availableUntil | string (date) | |
listing.data.management.isForInvestment | boolean | |
listing.data.management.heritageProtected | string | Eines von YES, NO, NOT_APPLICABLE. |
listing.data.management.marketStatus | string | Eines von SOLD, RENTED, REFERENCE, RESERVED, UNDER_OFFER. |
listing.data.management.projectStatus | string | Eines von BUILDING_PERMISSION, COMMERCIAL_LAUNCH, CONSTRUCTION_START, UNDER_CONSTRUCTION, SHELL_WORKS, FINISHING_WORKS, LAST_CHANCE, PROJECT_ENDED. |
listing.data.management.marketLabel | string | |
listing.data.management.isRented | boolean | |
listing.data.management.useFor | string | Eines von LIVING, COMMERCIAL, MIXED, OFFICE, INDUSTRIAL. |
listing.data.management.isForHolidayRental | boolean | |
listing.data.management.rent | object | |
listing.data.management.compulsoryAuction | object | |
listing.data.countrySpecific | object | |
listing.data.countrySpecific.de | object | |
listing.data.countrySpecific.fr | object | |
listing.data.contact | object | |
listing.data.contact.salutation | string | Eines von Mr, Mrs, Miss, Ms, Mx, Sir, Dame, Dr, Cllr, Lady, Lord. |
listing.data.contact.firstName | string | |
listing.data.contact.lastName | string | |
listing.data.contact.name | string | |
listing.data.contact.emailAddress | string | |
listing.data.contact.phoneNumber | string | |
listing.data.contact.mobilePhoneNumber | string | |
listing.data.contact.imageURL | string | |
listing.data.contact.userHomepage | string | |
listing.data.contact.postalCode | string | |
listing.data.contact.city | string | |
listing.data.contact.street | string | |
listing.data.contact.houseNumber | string | |
listing.data.contact.country | string | |
listing.data.contact.preferredContactType | string | Eines von ANONYMOUS, BY_PHONE, BY_EMAIL, OWN_WEBSITE. |
listing.data.contact.contactNote | map<string> | |
listing.data.contact.displayedInformation | object | |
listing.data.links | object | |
listing.data.links.externalLinks | object[] | |
listing.data.links.virtualTours | object[] | |
listing.metadata | object | |
listing.metadata.source | object | |
listing.metadata.source.offererMarketingKey | string | |
listing.metadata.source.offererEstateId | string | |
listing.metadata.source.offererEstateGroupId | string | |
listing.metadata.portalWebKey | string | |
listing.contact | object | |
listing.contact.salutation | string | Eines von Mr, Mrs, Miss, Ms, Mx, Sir, Dame, Dr, Cllr, Lady, Lord. |
listing.contact.firstName | string | |
listing.contact.lastName | string | |
listing.contact.name | string | |
listing.contact.emailAddress | string | |
listing.contact.phoneNumber | string | |
listing.contact.mobilePhoneNumber | string | |
listing.contact.imageURL | string | |
listing.contact.userHomepage | string | |
listing.contact.postalCode | string | |
listing.contact.city | string | |
listing.contact.street | string | |
listing.contact.houseNumber | string | |
listing.contact.country | string | |
listing.contact.preferredContactType | string | Eines von ANONYMOUS, BY_PHONE, BY_EMAIL, OWN_WEBSITE. |
listing.contact.contactNote | map<string> | |
listing.contact.displayedInformation | object | |
listing.contact.displayedInformation.mainContactPerson | object | |
listing.contact.displayedInformation.additionalContactPerson | object | |
listing.media | object[] | |
listing.media[].externalMediaId | string | |
listing.media[].title | string | |
listing.media[].id | string (uuid) | The id of the file in /files. |
listing.media[].kind | string | Eines von photo, floor_plan, document. |
listing.media[].documentType | string | |
listing.media[].fileName | string | |
listing.media[].mimeType | string | |
listing.media[].sizeBytes | integer | |
listing.media[].width | integer | |
listing.media[].height | integer | |
listing.media[].contentUrl | string | The address of the bytes; fetch it with the same API key. |
listing.userDefined | object[] | |
listing.userDefined[].name | string | |
listing.userDefined[].value | string | |
listing.userDefined[].utyp | string | Eines von string, integer, boolean, decimal. |
listing.userDefined[].modus | string | |
listing.listingId | string (uuid) | |
listing.projectId | string (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.status | string | Eines von draft, active, paused, reserved, closed. |
listing.createdAt | string (date-time) | |
listing.updatedAt | string (date-time) |
Köpfe der Antwort
| Kopf | Beschreibung |
|---|---|
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. |
Location | The proposal: /v1/proposals/{id}. |
Fehler
Jeder Fehler kommt als Problem Details. Verzweige auf code, nicht auf title oder detail.
| Status | Codes | Bedeutung |
|---|---|---|
400 | api_version_unsupported, idempotency_key_missing | Invalid request. |
401 | unauthorized | Missing or invalid API key. |
403 | insufficient_permissions, plan_required, plan_required | The key lacks a right, or the plan does not include API access. |
404 | not_found | Nothing under this ID. |
409 | listing_incomplete, listing_reserved, listing_closed, listing_blocked, automation_disabled, 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. |
422 | The idempotency key was already used with a different request body. | |
429 | rate_limited | Rate limit exceeded. |
500 | internal_error | Server error. |
Weiter lesen
REST-API: Anmeldung mit einem API-Key
Jeder Aufruf von /v1 trägt einen API-Key als Bearer-Token. Wo du ihn bekommst, welche Scopes er trägt und was nicht geht.
REST-API: Fehler als Problem Details
Jeder Fehler von /v1 ist ein Problem nach RFC 9457 mit echtem HTTP-Status, einem Code zum Verzweigen und einer Request-Id für den Support.