Publishing from your system
An integration is two calls, each made when something happens in your property system:
- A unit is saved with "publish to Shace" switched on:
PUT /listings/{your reference}with the whole unit. - A unit comes off the market (the switch goes off, or the unit is let):
POST /listings/ext:{your reference}/unpublish.
There is no diffing on your side and no export job. Both calls are idempotent, so a system without save hooks can instead run them on a schedule over its flagged units. An unpublish for a reference Shace never received answers 404; treat it as done. This page covers the rules the two calls rely on.
Your organization can make 600 requests a minute, and 60 of them to the upload endpoints (counted per request, not per file). The limits are shared by all of the organization's keys, so a second key does not add capacity. One image upload and two floor-plan uploads may run at a time; another one sent while they run answers 429 too. A request over that answers 429 with Retry-After in seconds, so a scheduled run over a large inventory should pace itself or wait that long and retry. GET /me reports the limits.
References and ids
Every listing has two identifiers:
idis Shace's UUID, generated by Shace and present in every response.externalRefis your id for the same unit: the unit id in your property system, a spreadsheet row key, whatever you already have. It is how you push the listing.
Wherever the API takes a listing's Shace id, ext: followed by your reference works too: GET /listings/ext:unit-4711 and GET /listings/5c1c8f0e-... return the same listing. Your system never has to store Shace ids.
PUT is the exception. Its path is always your reference, sent as is: PUT /listings/unit-4711, without ext:.
- References are unique per organization, case sensitive, and 1 to 128 characters; surrounding whitespace is trimmed, and they must not start with
ext:(in any case). Control and format characters, such as a line break or a zero-width space, and the Unicode line and paragraph separators (U+2028, U+2029) are refused. URL-encode references in paths:unit 12/Abecomes/listings/unit%2012%2FA. A control character or line separator in a URL may be refused by the hosting edge before it reaches Shace, with an answer that is not JSON. - References are compared after Unicode NFC normalization, so
Ötyped as one character or asOplus a combining diaeresis is the same reference. The same goes forbuildingRef. - Pick one reference per unit, even if your system holds several ids for it.
- Shace never generates a reference. Listings created through the API always have one; listings made in the Shace app have none.
What a push does
It replaces the whole unit
Send every field on every push. An optional field you leave out is cleared, so a push without description removes the stored description. The exceptions: metadata is kept when left out, so is priceBasis (see below), and so are the blur placeholders of images you send again.
There is no merge with anything edited in Shace: the listing becomes exactly what you sent. See Your system owns the listing.
Total or per-person price
Set the top-level priceBasis to "total" for the whole space or "per_person" for each desk or seat. Per-person pricing is allowed for coworking and part_of_office. For example, "priceBasis": "per_person" with "price": { "amount": 3500, "currency": "sek", "period": "month" } means 3,500 SEK per person per month. Listing responses include priceBasis.
Omitting priceBasis on create defaults to "total". Omitting it on update preserves the current basis, except that changing type to "office" resets the basis to "total". Explicitly sending "priceBasis": "per_person" with "type": "office" returns 400 BAD_REQUEST.
An unchanged push does nothing
Shace compares the push with what it holds, field by field. If nothing differs, outcome is unchanged, updatedAt does not move and nothing is written. Pushing on every save, or your whole inventory every night, creates no churn.
Some details of the comparison:
- Values that normalize to the same thing count as unchanged: a differently cased contact email,
metadatakeys in another order, or adescriptionwith surrounding whitespace. blurPlaceholdersare compared too. A push whose placeholders differ counts as a change, so send the same ones every time, or none. They are only read for URLs fromPOST /uploads/images: images fetched from your own URLs get theirs generated, and an entry keyed by one of your own URLs is ignored.- Images are compared by URL, not by the file behind it. Reordering
imagescounts as a change, because the first image is the cover.
When something did change, outcome is updated. Changes to description, locale, type, amenities, images or floorPlanUrl also re-index the listing for matching. Everything else is simply stored.
Field formats
typeisoffice,coworkingorpart_of_office: Shace lists offices only. Retail, warehouse and industrial premises have no type on Shace; leave them out of the sync.price.amountandareaM2take at most two decimals. More is a400, so what Shace stores is exactly what you sent and the next identical push staysunchanged.descriptionis stored trimmed, and an empty string is stored asnull.openHoursneeds all seven days,mondaytosunday, and no other keys. Each day is{ open, close }withcloseafteropen,{ open, close, allDay: true }for around the clock, ornullfor closed.amenitiesare free text in the listing'slocale, shown as written, for example["WiFi", "Takterrass", "Laddstolpar i garaget"]. Up to 30, each up to 40 characters. Shace trims whitespace and drops duplicates, keeping the first spelling and your order.
Addresses and buildings
Every listing carries its own address. Shace geocodes an address the first time your organization sends it and reuses the result after that, so sending the same address on every unit in a building costs nothing extra. A changed address is geocoded again and the listing moves with it. An address that cannot be geocoded is a 400.
Address fields are trimmed and runs of whitespace are collapsed to one space; countryCode is stored uppercased. Case is kept as you send it: a correction that only changes case, sveavägen 44 to Sveavägen 44, is stored and counts as updated, but is not geocoded again. postalCode is compared as sent, so 111 34 and 11134 are two different addresses: send it the same way every time.
If your system models properties and units separately, send your property reference as buildingRef on each unit. Shace stores it and returns it on every read, so you can group responses the way your system does. Shace does not group on it: to Shace, units belong together when their addresses match, and Sveavägen 44 and Sveavägen 44A are two different addresses.
Going live
A listing is either published (live and visible to Shace's matchmaking) or unpublished (not live). Every push publishes the listing unless the body holds it back or it has publish blockers.
Publish blockers
These are the rules the Shace app enforces too:
| Blocker | Rule |
|---|---|
images | At least three images. |
price | A price above zero. Shace has no "price on request". |
noticePeriod | A notice period when price.period is month. |
A blocker is never an error. The push succeeds, the listing is stored as unpublished, and publishBlockers lists what is missing:
Code
Your save hook can push whatever the unit holds and show the blockers next to the publish switch in your own UI. Once a later push resolves them, the listing goes live.
Errors (400) are reserved for bodies that are invalid as sent: a field that fails validation, an address that cannot be geocoded or is outside Sweden, the same URL twice in images, a blurPlaceholders key that is not in images, or noticePeriod or minimumDuration on a listing priced per day (they only apply to monthly prices).
Holding a listing back
Send status: "unpublished" to store a listing without publishing it, for example a unit that is on hold in your system. This works on the first push too, so the listing is never live, not even for a moment. The default is published.
Shace stores one status, not the reason behind it. A listing that has publish blockers is already unpublished, so holding it back answers outcome: "unchanged", and so does releasing it while the blockers remain. The first push that neither holds it back nor has blockers publishes it.
Taking a unit off the market
POST /listings/ext:unit-4711/unpublish takes the listing off Shace's matchmaking. Its content and reference are kept and nothing is deleted. The response is the listing with status: "unpublished", and outcome is unchanged if it was already off the market.
The next push of the same reference puts the listing back on the market, as long as it has no blockers and the body does not say status: "unpublished". That also applies when someone unpublished it in Shace: your push decides.
There is no delete: unpublishing is how a unit leaves Shace, whether it was let, sold or removed from your system. If a unit's reference changes on your side, unpublish the old reference and push the new one. To Shace they are two listings, and the old one stays live until you unpublish it.
Pushes never touch listings you did not push
The API only acts on what it receives. A push only changes the listing with that reference, and there is no full-sync mode that removes units missing from a push, so a bug on your side that skips units can never wipe your inventory. Taking a unit off the market is always the explicit unpublish call, which works on any published listing in your organization by its Shace id, including ones made in the Shace app (drafts that were never published are not part of the API).
Images
Shace recognizes a photo by its URL. Each new URL is downloaded during the push, which takes a little longer the first time a photo is sent and is a plain comparison after that. To replace a photo, send it under a new URL. Shace keeps its copy of a downloaded image for as long as one of your listings uses it, and for about 15 minutes after the last push that sent its URL; only after that is it deleted, and the URL is fetched again the next time you send it. So a changed file behind the same URL is not fetched again, not even if you drop the URL and add it back straight away. Give it a new URL, for example with a version query parameter such as ?v=2.
This breaks down if your system hands out image links that change on every export, such as links with a time-limited token from Azure Blob Storage or SharePoint. Every push then looks like a new set of photos, so each one is downloaded again and the listing is re-indexed. Upload those photos once with POST /uploads/images instead, store the returned URLs next to the photos in your system, and send those from then on.
If an image host does not answer, the push fails with 503 IMAGE_HOST_UNAVAILABLE naming the image's index, and the listing is not saved; retry it with a short backoff. Images that did get through are not downloaded again. A URL whose host name does not resolve, or a file that is not JPEG, PNG, WebP or HEIC (a GIF or SVG, say), is a 400 instead: fix the URL rather than retrying. A push with both kinds of failure is a 400 too, listing every failing index. Uploads in the reference has the size, format and URL rules.
Who is responsible for the unit
Every push names the person responsible for the unit as contact, plus any ids your system uses for them as metadata:
Code
contact is required unless you send the older assignedTo instead (below), so a unit without a responsible person fails in your sync log instead of quietly landing with someone else.
Someone who is already a member of your organization is always assigned directly. Anyone else must have an email on one of your organization's email domains: verified by one of your developers with a DNS TXT record under Developer > Email domains in the Shace dashboard, or set up by Shace. GET /me lists them as org.emailDomains. The match is exact: landlord.se does not cover team.landlord.se. What happens next depends on which integration your organization has (org.integration in GET /me).
Listings sync: your team handles leads, chat and contracts in the Shace app.
- The contact gets an invite to your organization and the push succeeds.
- The listing stays unassigned until they accept, then it is theirs. A lead that arrives before then goes to your organization's owners, naming who it is waiting for.
- While you keep pushing, an unanswered invite is re-sent at most once a day, for three weeks. A declined invite is not re-sent. After three weeks the re-sends stop; once the last invite expires, a week later, the listing stays unassigned, and leads keep going to your owners, until someone re-sends the invite from the Shace app.
Full integration: Shace sends you leads as webhooks (see Receiving leads).
- The contact gets a Shace account without a password, is assigned right away, and receives nothing. Their name follows what you push until they sign in themselves.
- An email that already has a Shace account outside your organization, or an unexpired pending invite or a declined invite to it, fails the push.
- The contact's account is created before the listing is written. If the push then fails for another reason, the listing is not saved but the account stays, and the next push reuses it.
A contact Shace cannot assign fails the push with 400 and an issue on contact.email that says why. The listing is not saved: fix the contact in your system, or add and verify the domain under Developer > Email domains, and push again.
The response's assignedTo is the email of the Shace user the listing is assigned to, or null while an invited contact has not joined.
metadata is yours: up to 50 keys of 1 to 40 characters, each with a string value up to 500 characters. A bad entry is a 400 with an issue on ["metadata", "<key>"]. Shace never reads it. It is returned on every read and sent with every lead, so you can route a lead to the right person in your system. A map you send replaces the stored one as a whole; send null or {} to clear it.
assignedTo in the request body is an older shorthand for contact: { email } and still works. Send one or the other, not both.
Your system owns the listing
A listing with a reference belongs to your system. Shace does not let anyone edit its content in the app: your push is the only source, and every push overwrites every content field.
Two things are handled on push:
- Availability blocks added in the Shace app are kept, because they are not content.
- The assignment is reset to
contacton every push.
Listings already in Shace. A push cannot take over a listing made in the Shace app: pushing a new reference always creates a new listing. To move a unit to your system, unpublish the app listing (in Shace, or through the API by its id) and push the unit from your system. Contact Shace if that does not work for you.
Staying in step
GET /listings?updatedSince=2026-09-01T00:00:00Z returns the listings that changed on Shace's side since a given time, cursor paginated, so you can check what Shace holds without pushing. updatedSince is exclusive and compared to the millisecond: a listing whose updatedAt equals it is left out. Pages are ordered by creation, newest first, not by updatedAt, so follow nextCursor to the end before you move your checkpoint. updatedAt moves on any change, including your own pushes and Shace's re-indexing shortly after one, so expect to see listings you just pushed.
To hear about status changes as they happen, including a listing someone unpublished in Shace, add a webhook endpoint: it receives listing.status_changed.