# 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:

- `id` is Shace's UUID, generated by Shace and present in every response.
- `externalRef` is 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/A` becomes `/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 as `O` plus a combining diaeresis is the same reference. The same goes for `buildingRef`.
- 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](#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, `metadata` keys in another order, or a `description` with surrounding whitespace.
- `blurPlaceholders` are 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 from `POST /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 `images` counts 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

- `type` is `office`, `coworking` or `part_of_office`: Shace lists offices only. Retail, warehouse and industrial premises have no type on Shace; leave them out of the sync.
- `price.amount` and `areaM2` take at most two decimals. More is a `400`, so what Shace stores is exactly what you sent and the next identical push stays `unchanged`.
- `description` is stored trimmed, and an empty string is stored as `null`.
- `openHours` needs all seven days, `monday` to `sunday`, and no other keys. Each day is `{ open, close }` with `close` after `open`, `{ open, close, allDay: true }` for around the clock, or `null` for closed.
- `amenities` are free text in the listing's `locale`, 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:

```json
{
  "id": "5c1c8f0e-6a3b-4a4c-9a3e-2b7f0d9a1e11",
  "externalRef": "unit-4711",
  "status": "unpublished",
  "publishBlockers": ["images", "noticePeriod"],
  "outcome": "created"
}
```

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](/reference/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`:

```json
{
  "contact": { "email": "anna@landlord.se", "firstName": "Anna", "lastName": "Berg" },
  "metadata": { "responsibleId": "E-4411" }
}
```

`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](/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 `contact` on 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](/webhooks): it receives [`listing.status_changed`](/webhooks/events#listingstatus_changed).
