Shace
Shace Partner API

Listings

Server

Units for rent, each with its own address. PUT /listings/{id} by your own reference is the call to make whenever a unit is saved in your system; POST /listings/{id}/unpublish takes it off the market. The publishing guide covers the rules behind both.

Contacts. Every push names the person responsible for the unit as contact: { email, firstName?, lastName? }; it is required, so a unit without one fails instead of landing with someone else. Email is trimmed, lowercased and at most 254 characters. Names are trimmed, up to 100 characters; leave them out, or send null or an empty string, when your system has none.

  • A member of your organization is assigned directly.
  • Anyone else needs an email on one of your organization's email domains (exact, case-insensitive match, no subdomains): 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.
  • With listings sync (leads in Shace), they are invited and the listing stays unassigned until they accept; an unanswered invite is re-sent at most once a day, for three weeks.
  • With full integration (leads in your own system), they get a passwordless account, are assigned right away and receive nothing; the names you send update theirs until they sign in. An email with a Shace account outside your organization, or with an unexpired pending or a declined invite to it, is rejected.
  • Anything Shace cannot assign is a 400 with an issue on contact.email that says why, and nothing is stored.

The response's assignedTo is the assigned user's email, or null while an invited contact has not joined. In requests, assignedTo is a deprecated shorthand for contact: { email }; sending both is a 400 with an issue on assignedTo.

Metadata. metadata is for your own ids: a flat map of at most 50 keys (1-40 characters) with string values up to 500 characters. Shace stores it untouched, returns it on reads ({} when none) and sends it with every deal event, so you can route a lead to the right person. Leave it out on an update to keep it; send null or {} to clear it. A map you send replaces the stored one whole.


List all listings

GET
https://api-sandbox.shace.se/partner/v1
/listings
Bearer

Newest first, cursor paginated. Use updatedSince to verify what Shace holds without re-pushing.

List all listings › query Parameters

cursor
​string

nextCursor from the previous page.

limit
​integer · min: 1 · max: 200

Page size, 1 to 200.

Default: 50
status
​string · enum

Only listings in this status.

Enum values:
published
unpublished
updatedSince
​string · date-time · pattern: ^(?:(?:\d\d[2468][04…

ISO 8601 instant. Only listings whose returned updatedAt is after it, compared at millisecond precision.

List all listings › Responses

OK

​object[] · required

The page, newest first.

​required

Pass as ?cursor= to fetch the next page; null on the last page.


Retrieve a listing

GET
https://api-sandbox.shace.se/partner/v1
/listings/{id}
Bearer

id is a Shace UUID or ext:<externalRef>. A UUID that is not one of your listings is looked up as an externalRef, so a system whose references are GUIDs can read back at the URL it pushed to; any other reference needs the ext: prefix.

Retrieve a listing › path Parameters

id
​string · minLength: 1 · required

Listing id, or ext:<your reference>.

Retrieve a listing › Responses

OK

id
​string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-… · required

Shace id.

​required

Your reference, or null when none was sent.

status
​string · enum · required

published (live) or unpublished (not live). publishBlockers says what keeps a listing from going live.

Enum values:
published
unpublished
publishBlockers
​string[] · required

Empty when the listing can go live; otherwise what is missing: images, price, noticePeriod.

Enum values:
images
price
noticePeriod
​object · required

The address, as stored.

​required

Geocoded point for the address, WGS84.

​required

Your reference for the building or property the unit belongs to, or null when none was sent.

type
​string · enum · required

office for a whole office, coworking for desks or rooms in a shared workspace, part_of_office for part of a larger office.

Enum values:
office
coworking
part_of_office
locale
​string · enum · required

Locale the description and amenities were submitted in.

Enum values:
sv
en
​required

Free text about the premises, in locale.

​required

Floor area in square metres.

​required

Number of workplaces.

​required

Furnished or not.

​object · required

Base rent, as sent.

priceBasis
​string · enum · required

Whether price.amount is for the whole space or per person. Per-person pricing is only allowed for coworking and part_of_office.

Enum values:
total
per_person
​required

Notice period in months, month-priced listings only.

​required

Binding period in months, or null for no minimum.

amenities
​string[] · required

Amenities as stored in the listing's locale, in display order.

images
​string[] · required

Public image URLs in display order.

​required

Public floor plan URL, or null.

​required

Opening hours per weekday for coworking listings, or null.

​required

The contact from your last push, with missing parts as null. Null only for a listing that has not been pushed with a contact.

​object · maxProps: 50 · required

Your metadata as sent, or {} when none. Omitted on update keeps it; null or {} clears it. Sending a map replaces the whole map.

​required

Email of the Shace user the listing is assigned to: contact.email, or null while a contact who was invited to your organization has not joined yet.

createdVia
​string · enum · required

Whether the listing was created in the app, API, or by an admin.

Enum values:
app
api
admin
​required

Last time a PUT through this API wrote content fields.

createdAt
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

ISO 8601 UTC.

updatedAt
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

Latest change to the listing: your pushes, edits in Shace, and Shace's re-indexing shortly after a content change. ISO 8601 UTC, millisecond precision.


Create or update a listing

PUT
https://api-sandbox.shace.se/partner/v1
/listings/{id}
Bearer

The call to make whenever a unit is saved in your system. The path is your own reference for the unit: the first push of a reference creates the listing, every later push of the same reference updates it, and an unchanged body is a no-op. The listing carries its own address; a changed address is geocoded again. Publishes on success unless the body says status: "unpublished", which holds the listing back, including on its first push. A listing that is valid but not publishable is stored as unpublished and the response lists the publishBlockers. A reference whose listing was unpublished is republished.

Outcomes

The same request in other situations, as outcome, status and any publishBlockers:

  • First push of a new reference: created, published
  • The same body again: nothing is written, nothing is re-indexed, updatedAt does not move: unchanged, published
  • A field changed, for example the price: updated, published
  • The address changed: geocoded again, the listing moves with it: updated, published
  • Two images instead of three on a listing that was live: stored, taken off the market until a third is pushed: updated, unpublished, blockers images
  • The body says status: "unpublished" for a listing that was live: updated, unpublished
  • The first push of a reference says status: "unpublished": stored, never live: created, unpublished
  • The reference of a listing that was unpublished, pushed again: updated, published

Create or update a listing › path Parameters

id
​string · minLength: 1 · maxLength: 128 · required

Your external reference for the listing, URL-encoded. Send it directly, without adding ext:.

Create or update a listing › Request Body

​object · required

Where the premises are. Text fields are trimmed and runs of whitespace collapsed to one space; case is kept as sent. Geocoded the first time an address is seen for your organization; an address that only changes case or whitespace is stored as sent but not geocoded again.

type
​string · enum · required

Shace lists offices only: office for a whole office, coworking for desks or rooms in a shared workspace, part_of_office for part of a larger office.

Enum values:
office
coworking
part_of_office
​object · required

Base rent. Transparent pricing is part of Shace, so there is no price on request.

​

Your own reference for the building or property the unit belongs to, for systems that model property and unit separately. Optional; stored and read back as sent, and cleared when an update omits it. Shace matches on the address, not on this reference.

locale
​string · enum

Language of description and amenities. Shown as sent, not translated.

Enum values:
sv
en
Default: sv
​

Free text about the premises, in locale. Trimmed; an empty string is stored as null.

​

Floor area in square metres, with at most two decimal places.

​

Number of workplaces.

​

Furnished or not.

priceBasis
​string · enum

total prices the whole space; per_person prices each person and is only allowed for coworking and part_of_office. Omitted on create defaults to total. Omitted on update keeps the current basis, except changing type to office resets it to total.

Enum values:
total
per_person
​

Notice period in months. Required to publish month-priced listings; must be omitted for day pricing.

​

Binding period in months, month-priced listings only. Omit for no minimum.

amenities
​string[] · maxItems: 30

Amenities as free text in the listing's locale, for example "Takterrass" or "Laddstolpar i garaget". Up to 30, 40 characters each, shown as written. Order is display order; reordering counts as a change.

Default: []
images
​string[] · maxItems: 20

Image URLs in display order; the first is the cover. Either https URLs your own system serves on the default port (Shace fetches each once and hosts a copy) or URLs returned by POST /uploads/images for your organization. Photos are recognized by URL, so links that change on every export (a time-limited token) should be uploaded once instead. At least 3 to publish, at most 20, no URL twice. Reordering counts as a change.

Default: []
​object

Blur placeholders keyed by upload URL, as returned by the upload endpoint. Every key must be one of this request's images. Optional. Only read for upload URLs: images fetched from your own URLs get theirs generated, and an entry keyed by one of your own URLs is ignored.

​

URL returned by POST /uploads/floor-plan. Optional; does not count towards the three-image minimum.

​

Opening hours per weekday for coworking listings. All seven days (monday to sunday) are required and no other keys are accepted, on the week or on a day. Each day is { open, close } as HH:MM, { open, close, allDay: true } for around the clock, or null for closed. close must be later than open on the same day: hours past midnight (22:00 to 06:00) are not supported, so use allDay for a day that is open 24 hours.

status
​string · enum

published (default) goes live when there are no publish blockers; unpublished holds the listing back, including on its first push, so it is never live for a moment.

Enum values:
published
unpublished
Default: published
​

Required unless the deprecated assignedTo is sent. The person responsible for the unit; Shace assigns the listing to them. A member of your organization is assigned directly. Anyone else must be on one of your organization's email domains: with listings sync (leads in Shace) they are invited and get the listing when they accept; with full integration (leads in your own system) they get a Shace account without a password. Anything Shace cannot accept is a BAD_REQUEST whose message says why.

​

Your own data, for example the responsible person's id in your system. Shace never reads it and returns it on every read. Up to 50 keys of 1-40 characters, string values up to 500 characters. Omitted on an update, the current map is kept; a sent map replaces it; null or {} clears it.

Create or update a listing › Responses

OK

id
​string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-… · required

Shace id.

​required

Your reference, or null when none was sent.

status
​string · enum · required

published (live) or unpublished (not live). publishBlockers says what keeps a listing from going live.

Enum values:
published
unpublished
publishBlockers
​string[] · required

Empty when the listing can go live; otherwise what is missing: images, price, noticePeriod.

Enum values:
images
price
noticePeriod
​object · required

The address, as stored.

​required

Geocoded point for the address, WGS84.

​required

Your reference for the building or property the unit belongs to, or null when none was sent.

type
​string · enum · required

office for a whole office, coworking for desks or rooms in a shared workspace, part_of_office for part of a larger office.

Enum values:
office
coworking
part_of_office
locale
​string · enum · required

Locale the description and amenities were submitted in.

Enum values:
sv
en
​required

Free text about the premises, in locale.

​required

Floor area in square metres.

​required

Number of workplaces.

​required

Furnished or not.

​object · required

Base rent, as sent.

priceBasis
​string · enum · required

Whether price.amount is for the whole space or per person. Per-person pricing is only allowed for coworking and part_of_office.

Enum values:
total
per_person
​required

Notice period in months, month-priced listings only.

​required

Binding period in months, or null for no minimum.

amenities
​string[] · required

Amenities as stored in the listing's locale, in display order.

images
​string[] · required

Public image URLs in display order.

​required

Public floor plan URL, or null.

​required

Opening hours per weekday for coworking listings, or null.

​required

The contact from your last push, with missing parts as null. Null only for a listing that has not been pushed with a contact.

​object · maxProps: 50 · required

Your metadata as sent, or {} when none. Omitted on update keeps it; null or {} clears it. Sending a map replaces the whole map.

​required

Email of the Shace user the listing is assigned to: contact.email, or null while a contact who was invited to your organization has not joined yet.

createdVia
​string · enum · required

Whether the listing was created in the app, API, or by an admin.

Enum values:
app
api
admin
​required

Last time a PUT through this API wrote content fields.

createdAt
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

ISO 8601 UTC.

updatedAt
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

Latest change to the listing: your pushes, edits in Shace, and Shace's re-indexing shortly after a content change. ISO 8601 UTC, millisecond precision.

outcome
​string · enum · required

What the request did. unchanged means the body matched what Shace already holds.

Enum values:
created
updated
unchanged

Unpublish a listing

POST
https://api-sandbox.shace.se/partner/v1
/listings/{id}/unpublish
Bearer

For the unpublish action in your system. id is a Shace UUID or ext:<externalRef>. The listing is hidden from matchmaking and keeps its content and reference; nothing is deleted, and the next PUT of the same reference puts it back on the market. Idempotent: a listing that is already off the market answers outcome: "unchanged".

Unpublish a listing › path Parameters

id
​string · minLength: 1 · required

Listing id, or ext:<your reference>.

Unpublish a listing › Responses

OK

id
​string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-… · required

Shace id.

​required

Your reference, or null when none was sent.

status
​string · enum · required

published (live) or unpublished (not live). publishBlockers says what keeps a listing from going live.

Enum values:
published
unpublished
publishBlockers
​string[] · required

Empty when the listing can go live; otherwise what is missing: images, price, noticePeriod.

Enum values:
images
price
noticePeriod
​object · required

The address, as stored.

​required

Geocoded point for the address, WGS84.

​required

Your reference for the building or property the unit belongs to, or null when none was sent.

type
​string · enum · required

office for a whole office, coworking for desks or rooms in a shared workspace, part_of_office for part of a larger office.

Enum values:
office
coworking
part_of_office
locale
​string · enum · required

Locale the description and amenities were submitted in.

Enum values:
sv
en
​required

Free text about the premises, in locale.

​required

Floor area in square metres.

​required

Number of workplaces.

​required

Furnished or not.

​object · required

Base rent, as sent.

priceBasis
​string · enum · required

Whether price.amount is for the whole space or per person. Per-person pricing is only allowed for coworking and part_of_office.

Enum values:
total
per_person
​required

Notice period in months, month-priced listings only.

​required

Binding period in months, or null for no minimum.

amenities
​string[] · required

Amenities as stored in the listing's locale, in display order.

images
​string[] · required

Public image URLs in display order.

​required

Public floor plan URL, or null.

​required

Opening hours per weekday for coworking listings, or null.

​required

The contact from your last push, with missing parts as null. Null only for a listing that has not been pushed with a contact.

​object · maxProps: 50 · required

Your metadata as sent, or {} when none. Omitted on update keeps it; null or {} clears it. Sending a map replaces the whole map.

​required

Email of the Shace user the listing is assigned to: contact.email, or null while a contact who was invited to your organization has not joined yet.

createdVia
​string · enum · required

Whether the listing was created in the app, API, or by an admin.

Enum values:
app
api
admin
​required

Last time a PUT through this API wrote content fields.

createdAt
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

ISO 8601 UTC.

updatedAt
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

Latest change to the listing: your pushes, edits in Shace, and Shace's re-indexing shortly after a content change. ISO 8601 UTC, millisecond precision.

outcome
​string · enum · required

What the request did. unchanged means the body matched what Shace already holds.

Enum values:
created
updated
unchanged