Shace Partner API
Publish your vacant premises to Shace from your own property system, and receive the leads they bring in.
There are two setups, agreed with Shace. Listings sync: you push your listings and your team answers leads in Shace. Full integration: listings sync, plus leads in your own system through webhooks and the Deals endpoints. GET /me shows which one your organization has.
Listings. Push each unit by your own reference with PUT /listings/{id} whenever it is saved on your side, and take it off the market with POST /listings/{id}/unpublish. The same reference updates instead of duplicating, an unchanged push is a no-op, and listings you do not push are never touched. Anywhere a listing's Shace id is accepted, ext:<your reference> works too.
Leads. With full integration, set up with Shace, you receive deal.created when a tenant is interested in one of your listings. Answer with POST /deals/{id}/accept or /decline, or by mail to the deal's replyAddress.
Basics. Authenticate every request with Authorization: Bearer shace_sk_…, an organization-scoped key your developers create under Developer > API keys in the Shace dashboard. Every error has the shape { code, status, message, data? }, with validation issues under data.issues.
The guides walk through both flows: Quickstart, Publishing from your system and Receiving leads.
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.
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.images.
Your own URLs. If your system already serves the photos, send those URLs directly on the listing. Shace downloads each image once, converts it to webp, resizes it to at most 2048 px, gives it a blur placeholder and hosts the copy itself; the listing never links to your server. The URL is remembered per organization, so pushing the same URL again is a no-op with no download, and a photo shared by several units (a building exterior) is fetched once. To replace a photo, send a new URL: Shace does not re-check a URL it has already fetched. URLs must be https on the default port, on a public hostname, without credentials and at most 2048 bytes; each file at most 15 MB in JPEG, PNG, WebP or HEIC, judged by its content (HEIC at most 50 megapixels). Shace follows up to 3 redirects and gives each image 20 seconds in all (looking up the host, redirects and download). A push gets 75 seconds for its image URLs, including time spent waiting behind other pushes; images not fetched by then fail as unavailable. Anything else, including a file that is not an image, a GIF or SVG, or a host name that does not resolve, is a 400 with the failing index under issues. A host that does not answer, times out, rate-limits or answers a server error is a 503 IMAGE_HOST_UNAVAILABLE, also with the failing index, and safe to retry: images that did get through are kept, so the retry only fetches the rest. A push with both kinds of failure is a 400 listing every failing index, since retrying it cannot succeed until the body is fixed. The same URL may not appear twice in images. A listing that mixes the two kinds of URL is fine.
Uploads. For photos that live behind a login, or in a system with no public URLs, send the files to POST /uploads/images and reference the returned URLs. Store them next to the unit in your system; later pushes send the same URLs and the listing comes back unchanged. Upload again only when a photo actually changed. Shace checks that each upload URL points into your organization's folder but does not fetch it, so a URL for an upload that no longer exists is accepted and shows as a broken image.
Deletion. An upload or a fetched copy that a push stops using is kept for about 15 minutes, then deleted once no listing in your organization references it. Within those minutes it can be sent again, on the same listing or another one, so a photo or floor plan that moves between units (unit A drops it and unit B gains it) survives if both pushes land within the window. After that, an upload URL shows as a broken image and one of your own URLs is fetched again. Dropping one of your URLs and adding it back within the window reuses the old copy, so to replace a photo, give it a new URL.
Order matters. images is the display order in Shace and the first image is the cover. Reordering the array counts as a change and re-indexes the listing.
Floor plans are optional, uploaded through POST /uploads/floor-plan and do not count towards the three-image minimum. Blur placeholders from the upload response are optional to pass along on the listing; leave them out if your system has nowhere to keep them. They are only read for upload URLs: images fetched from your URLs get theirs generated, and a blurPlaceholders entry for one of your own URLs is ignored.403. GET /me shows which you have under org.integration.
A deal is a tenant's interest in one of your listings. It reaches you as a deal.created webhook with status pending, and waits for your answer until expiresAt (14 days). Answer it with POST /deals/{id}/accept or POST /deals/{id}/decline, or in Shace.
Contact. The tenant's company name and organization number are shared; their name, email and phone are not. A company still under registration in Sweden has no number yet: tenant.underRegistration is true and tenant.description holds what the tenant wrote about their business instead. replyAddress is the tenant's address for the deal: store it as the lead's email in your CRM, and your CRM can track the whole conversation on the lead.
Answering by mail. Your staff can reply to the tenant straight from Outlook. Mail to replyAddress becomes a chat message from the sender, and the first mail to a pending deal accepts it. The tenant's messages come back from the same address, threaded, to whoever last wrote (at first, the listing's contact). Mail is accepted from your members and from anyone on your organization's email domains, and it must pass DMARC; colleagues without a Shace account get one silently. Automated mail (out-of-office replies, newsletters, noreply and CRM send-outs) is ignored, so point your CRM's own automations elsewhere. Quoted history, signatures and images pasted into the mail are left out, and the text is cut at 5,000 characters. Attached files come along, up to 10 per mail and 25 MB each, as PNG, JPEG, WebP, GIF, PDF, Word, Excel, text or CSV; other files are dropped and the message still goes through. A mail that cannot be delivered (the deal is closed, the tenant has not finished signing up, the sender's domain is not yours) gets a short explanation back.
Who answers. Accepting posts your message to the tenant from the member named in from (by default whoever the lead is routed to, usually the listing's contact, else the owner), and makes them responsible for the deal. Declining never shows your reason to the tenant.
Statuses. pending, then accepted, declined, expired (nobody answered in time) or lost (the tenant withdrew, or Shace closed it). A tenant who withdrew can come back, which makes the deal pending again and sends deal.reopened (or deal.created if no earlier event about the deal reached you). declined, expired and lost only end a pending lead: an accepted deal stays accepted, and a tenant who cancels after that is announced in the deal's mail thread, not by an event.webhooks.api-sandbox.shace.se and not in production, where they answer 404. Like the Deals endpoints they need full integration and answer 403 with listings sync. They play the tenant's side of a lead, one call per step, so you can watch every deal event reach your receiver and build against it without a real tenant.
Start with POST /sandbox/deals on one of your published listings: a test tenant shows interest and deal.created fires. Then answer it the way you will in production (POST /deals/{id}/accept or /decline, or by mail) and drive the rest from here: the tenant writes, books a viewing, signs, withdraws and comes back, or the lead expires. Each call returns the deal as it is afterwards, and the events arrive at your endpoints as they would in production.
The steps only act on test deals made here, and the test tenant is the same for every organization in the sandbox.Authorization: Bearer shace_sk_…. A key is shace_sk_ followed by 48 hex characters, and it has full inventory access for its organization and nothing else. There are no scopes yet; if a narrower key is ever needed, say so.
Getting a key. Your organization's developers create keys under Developer > API keys in the Shace dashboard (Shace support makes someone a developer). A key is shown once, so store the plaintext in your secret manager right away. Shace keeps only a hash and can never show a key again; if one is lost, create a new one and revoke the old one. Keys issued for a pilot may carry an expiry: GET /me shows expiresAt, or null for none.
Rotation. Several keys can be live at once, so rotation is: create a new key, switch your job over, revoke the old one. A revoked or expired key answers 401 from the next request.
Server to server only. Keyed routes send CORS headers to this docs site alone, for the Test Request button; every other origin gets none, so a key cannot be used from your own browser pages even by accident. Call the API from your backend or a scheduled job.
Environments. Build and test against the sandbox, api-sandbox.shace.se: the same code as production, with its own organization, keys and data. Going live means switching the host to api.shace.se and the key to a production one; webhook endpoints are registered per environment, each with its own signing secret. Sandbox keys only work on the sandbox and production keys only on production. The docs list both servers, sandbox first; the Test Request button and the code snippets use the one picked in the reference.New lead
Lead is back
Lead accepted
Lead declined
Lead expired
Lead lost
Viewing times offered
Viewing booked
Booked viewing cancelled
Contract signed
Tenant wrote
Your side wrote
Listing went live or came off the market
Test