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 /melists them asorg.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
400with an issue oncontact.emailthat 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
Newest first, cursor paginated. Use updatedSince to verify what Shace holds without re-pushing.
query Parameters
cursornextCursor from the previous page.
limitPage size, 1 to 200.
statusOnly listings in this status.
updatedSince^(?:(?:\d\d[2468][04…ISO 8601 instant. Only listings whose returned updatedAt is after it, compared at millisecond precision.
List all listings › Responses
OK
The page, newest first.
Pass as ?cursor= to fetch the next page; null on the last page.
Retrieve a listing
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.
path Parameters
idListing id, or ext:<your reference>.
Retrieve a listing › Responses
OK
id^([0-9a-fA-F]{8}-[0-… · requiredShace id.
Your reference, or null when none was sent.
statuspublished (live) or unpublished (not live). publishBlockers says what keeps a listing from going live.
publishBlockersEmpty when the listing can go live; otherwise what is missing: images, price, noticePeriod.
The address, as stored.
Geocoded point for the address, WGS84.
Your reference for the building or property the unit belongs to, or null when none was sent.
typeoffice for a whole office, coworking for desks or rooms in a shared workspace, part_of_office for part of a larger office.
localeLocale the description and amenities were submitted in.
Free text about the premises, in locale.
Floor area in square metres.
Number of workplaces.
Furnished or not.
Base rent, as sent.
priceBasisWhether price.amount is for the whole space or per person. Per-person pricing is only allowed for coworking and part_of_office.
Notice period in months, month-priced listings only.
Binding period in months, or null for no minimum.
amenitiesAmenities as stored in the listing's locale, in display order.
imagesPublic image URLs in display order.
Public floor plan URL, or null.
Opening hours per weekday for coworking listings, or null.
The contact from your last push, with missing parts as null. Null only for a listing that has not been pushed with a contact.
Your metadata as sent, or {} when none. Omitted on update keeps it; null or {} clears it. Sending a map replaces the whole map.
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.
createdViaWhether the listing was created in the app, API, or by an admin.
Last time a PUT through this API wrote content fields.
createdAt^(?:(?:\d\d[2468][04… · requiredISO 8601 UTC.
updatedAt^(?:(?:\d\d[2468][04… · requiredLatest 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
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, blockersimages - 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
path Parameters
idYour external reference for the listing, URL-encoded. Send it directly, without adding ext:.
Create or update a listing › Request Body
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.
typeShace 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.
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.
localeLanguage of description and amenities. Shown as sent, not translated.
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.
priceBasistotal 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.
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.
amenitiesAmenities 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.
imagesImage 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.
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.
statuspublished (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.
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.
assignedToDeprecated. Same as contact: { email }; send one or the other, not both.
Create or update a listing › Responses
OK
id^([0-9a-fA-F]{8}-[0-… · requiredShace id.
Your reference, or null when none was sent.
statuspublished (live) or unpublished (not live). publishBlockers says what keeps a listing from going live.
publishBlockersEmpty when the listing can go live; otherwise what is missing: images, price, noticePeriod.
The address, as stored.
Geocoded point for the address, WGS84.
Your reference for the building or property the unit belongs to, or null when none was sent.
typeoffice for a whole office, coworking for desks or rooms in a shared workspace, part_of_office for part of a larger office.
localeLocale the description and amenities were submitted in.
Free text about the premises, in locale.
Floor area in square metres.
Number of workplaces.
Furnished or not.
Base rent, as sent.
priceBasisWhether price.amount is for the whole space or per person. Per-person pricing is only allowed for coworking and part_of_office.
Notice period in months, month-priced listings only.
Binding period in months, or null for no minimum.
amenitiesAmenities as stored in the listing's locale, in display order.
imagesPublic image URLs in display order.
Public floor plan URL, or null.
Opening hours per weekday for coworking listings, or null.
The contact from your last push, with missing parts as null. Null only for a listing that has not been pushed with a contact.
Your metadata as sent, or {} when none. Omitted on update keeps it; null or {} clears it. Sending a map replaces the whole map.
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.
createdViaWhether the listing was created in the app, API, or by an admin.
Last time a PUT through this API wrote content fields.
createdAt^(?:(?:\d\d[2468][04… · requiredISO 8601 UTC.
updatedAt^(?:(?:\d\d[2468][04… · requiredLatest change to the listing: your pushes, edits in Shace, and Shace's re-indexing shortly after a content change. ISO 8601 UTC, millisecond precision.
outcomeWhat the request did. unchanged means the body matched what Shace already holds.
Unpublish a listing
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".
path Parameters
idListing id, or ext:<your reference>.
Unpublish a listing › Responses
OK
id^([0-9a-fA-F]{8}-[0-… · requiredShace id.
Your reference, or null when none was sent.
statuspublished (live) or unpublished (not live). publishBlockers says what keeps a listing from going live.
publishBlockersEmpty when the listing can go live; otherwise what is missing: images, price, noticePeriod.
The address, as stored.
Geocoded point for the address, WGS84.
Your reference for the building or property the unit belongs to, or null when none was sent.
typeoffice for a whole office, coworking for desks or rooms in a shared workspace, part_of_office for part of a larger office.
localeLocale the description and amenities were submitted in.
Free text about the premises, in locale.
Floor area in square metres.
Number of workplaces.
Furnished or not.
Base rent, as sent.
priceBasisWhether price.amount is for the whole space or per person. Per-person pricing is only allowed for coworking and part_of_office.
Notice period in months, month-priced listings only.
Binding period in months, or null for no minimum.
amenitiesAmenities as stored in the listing's locale, in display order.
imagesPublic image URLs in display order.
Public floor plan URL, or null.
Opening hours per weekday for coworking listings, or null.
The contact from your last push, with missing parts as null. Null only for a listing that has not been pushed with a contact.
Your metadata as sent, or {} when none. Omitted on update keeps it; null or {} clears it. Sending a map replaces the whole map.
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.
createdViaWhether the listing was created in the app, API, or by an admin.
Last time a PUT through this API wrote content fields.
createdAt^(?:(?:\d\d[2468][04… · requiredISO 8601 UTC.
updatedAt^(?:(?:\d\d[2468][04… · requiredLatest change to the listing: your pushes, edits in Shace, and Shace's re-indexing shortly after a content change. ISO 8601 UTC, millisecond precision.
outcomeWhat the request did. unchanged means the body matched what Shace already holds.