Update a listing
Request, parameters, response and errors of PATCH /v1/listings/{externalListingId}.
Last updated:
A JSON Merge Patch (RFC 7396) of the OpenImmo 2.0 listing: a member that is missing stays, null clears it. media: [] or null removes the files that came through the API, contact: null removes the contact person. Cannot be cleared: data.distributionType, data.estateType. A running listing blocks changing the address parts or the distribution type (409 listing_active). Needs write access to listings.
Requires the scope propose.
Request
PATCH https://api.athaus.ai/v1/listings/{externalListingId}Parameters
Path
| Name | Type | Required | Description |
|---|---|---|---|
externalListingId | string | yes | 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. |
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. |
If-Match | string | no | Only if the current ETag of the resource is listed (or *: only if the resource exists). Otherwise 412 and nothing is written. |
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 | any | |
metadata | object | any | |
userDefined | object[] | any | |
media | object[] | any | |
contact | object | any |
Example
curl -X PATCH "https://api.athaus.ai/v1/listings/WE-12" \
-H "Authorization: Bearer ath_live_..." \
-H "Content-Type: application/json" \
-d '{"data":{"prices":{"buy":{"price":{"amount":340000}}}}}'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. |
Errors
Every error arrives as problem details. Branch on code, not on title or detail.
| Status | Codes | Meaning |
|---|---|---|
400 | api_version_unsupported, invalid_input, 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 | The request conflicts with the state of the resource (for example a duplicate), or with an idempotency key. |
412 | precondition_failed | The condition of If-Match (or If-None-Match) does not hold for the current state of the resource. Nothing was written. |
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. |
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.