Receiving leads
When a tenant is interested in one of your listings, Shace creates a deal and sends it to you as a deal.created webhook. You answer it through the API, by mail or in Shace, and more events follow the deal from there.
This page is for organizations with full integration, which work leads in their own system, a CRM for example. You agree on it with Shace. With listings sync, your team handles leads in the Shace app: deal events are not sent and the Deals endpoints answer 403. GET /me shows which one you have under org.integration.
Getting started goes in this order:
- You add your endpoint and check it with a test event (step 1 below).
- Shace switches your organization to full integration.
- New leads arrive as
deal.createdfrom then on.
If you already push listings on listings sync, contacts with an unexpired pending invite or a declined invite fail the push once full integration is on. Have them accept, or ask Shace support to cancel those invites, before the switch.
1. Set up an endpoint
Add the URL your receiver listens on, for example https://integrations.landlord.se/shace/events, under Developer > Webhooks in the Shace dashboard. It must be https on a public hostname. You then see the endpoint's signing secret, starting with whsec_, only this once, so store it with your receiver right away. Endpoints are per environment: add one in the sandbox dashboard (https://sandbox.shace.se) while you build, and one in production when you go live, each with its own secret.
With full integration the endpoint gets every event. Before that, it gets listing events and test events only. To check your receiver, send a test event from the dashboard, or call POST /webhooks/{id}/test with the endpoint's id from GET /webhooks:
Code
2. Receive events
Each event is a JSON POST with the body { id, type, createdAt, data }. Your receiver should:
- Verify the signature. Signatures follow Standard Webhooks, which has libraries for most languages, .NET included.
- Answer with any
2xxwithin 10 seconds. If processing takes longer, store the event, answer, and process it afterwards: a2xxis final. - Drop repeats by
id. An event can arrive more than once. - Keep the newest state. Events can arrive out of order, after a retry or when two happen close together.
createdAtdoes not guarantee order either, so treat an event as a signal that the deal changed. When order matters, read the current deal withGET /deals/{id}. - Ignore event types you do not know. Shace adds new ones without notice; answer them with a
2xxlike any other.
A failed delivery is retried for about 28 hours. The webhooks overview has the signature steps and the retry schedule.
3. Create the lead
deal.created carries the deal:
Code
The example is shortened; The deal has every field. What to do with the important ones:
deal.id: key your records on it. The outeridis the event's, for dropping repeats.reference: show it to your staff. It is how people refer to the deal.replyAddress: store it as the lead's email. The tenant's personal contact details are never shared; mail to this address reaches them, and their messages come from it.listing.externalRefandlisting.metadata: your reference for the unit and themetadatayou pushed on it, so you can route the lead to the right person. An event carries the metadata as it was when the event was created;GET /deals/{id}returns the listing's current metadata.listingisnullfor the rare lead that is not on one of your listings, andexternalRefisnullon a listing made in the Shace app, so have somewhere for those to land.tenant: the company, never the person. A company still under registration has noorgNumberyet;underRegistrationistrueanddescriptionis what the tenant wrote about their business, so show it to whoever handles the lead.expiresAt: the lead waits 14 days for an answer. After that, Shace's nightly run expires it and sendsdeal.expired; until then it can still be answered.
Create or update your record from any deal event whose deal you have not seen: every event carries the whole deal, and a lead that Shace accepted on your behalf arrives as deal.accepted without a deal.created first.
4. Answer the lead
Any of three ways works. Whichever you use, a deal.accepted or deal.declined event follows, so your system can update the lead from events alone.
Through the API. Accepting sends message to the tenant from the member named in from, who becomes responsible for the deal. from must be a member of your organization, for example someone you pushed as a listing contact; leave it out to send as whoever the lead is routed to, usually the listing's contact.
Code
To say no, POST /deals/{id}/decline with an optional reason. The reason is for Shace and never shown to the tenant. Declining works even if the listing has been unpublished since the lead arrived; accepting then answers 409 with data.reason listing_unpublished until you push the listing again.
After any 409 on accept or decline, GET /deals/{id} to see where the deal stands. A retry after a timeout is the common case: the first attempt went through, so the retry answers 409 with not_pending and the deal is already accepted or declined. Accepting can also answer 409 with no_owner when the member the lead is routed to has left your organization and it has no owner to answer instead; send from to answer as someone else.
By mail. Your staff can reply to replyAddress straight from Outlook or your CRM. The first mail to a pending deal accepts it, and every mail becomes a chat message from its sender. The tenant's replies come back from the same address, threaded, to whoever wrote last.
- Mail is accepted from members of your organization and from anyone on your organization's email domains (added and verified with a DNS TXT record under Developer > Email domains, listed in
GET /me), and must pass DMARC. - Automated mail (out-of-office replies, newsletters, noreply senders, CRM send-outs) is ignored, so point your CRM's automations elsewhere.
- Quoted history, signatures and images pasted into the mail (logos, screenshots) are left out. A text longer than 5,000 characters is cut at the last whole word before that and ends with "…". Attached files come along: up to 10 per mail, 25 MB each, as PNG, JPEG, WebP, GIF, PDF, Word, Excel, text or CSV. Other files are dropped and the message still goes through.
- Every mail that becomes a chat message sends
deal.message_sentwith the text as the tenant sees it, so your system can check what came through. A mail with nothing but viewing times in it (and no files) becomes only the pick-a-time card below, so it sendsdeal.viewing_proposedand nodeal.message_sent. - Viewing times written in a mail, like "torsdag kl 10 eller fredag kl 14", are read and offered to the tenant as a pick-a-time card, the same as times proposed in Shace, and
deal.viewing_proposedcomes with it (in no set order withdeal.message_sent). The sentences that only list the times are left out of the chat message, since the card shows them. New times while the tenant has an upcoming booked viewing replace it: the booked viewing is cancelled (deal.viewing_cancelled) and the tenant picks again. - A mail that cannot be delivered, for example to a closed deal, gets a short explanation back.
In Shace. The deal's url opens it in the Shace app for anyone with an account. Its form follows the status: /dashboard/deals?peek=<reference> while the deal is pending, /chats/<id> (the conversation) once it is accepted, and /dashboard/deals after that. Store it as a link rather than parsing it.
5. Follow the deal
More events follow the deal: deal.viewing_proposed when your side offers viewing times (sent again with the same viewing id when the offered times change, and with no slots when your side withdraws them; the latest one is current), deal.viewing_booked when the tenant books one, deal.viewing_cancelled when new times replace an upcoming booked viewing, deal.message_created when the tenant writes in the chat, deal.message_sent when someone on your side does (in Shace, by mail or with an accept through the API; via says which), and deal.contract_signed once both parties have signed. A pending lead that ends unanswered or withdrawn sends deal.expired or deal.lost, and a tenant who comes back sends deal.reopened (or deal.created, if the lead never reached you before). An accepted deal stays accepted: if the tenant cancels after that, the deal's mail thread tells you, not an event.
When the tenant books a viewing, Shace also mails a calendar invite (a 30-minute event) to your side of the deal: the person who last mailed the reply address, or else the person the deal is routed to (usually the listing's contact). The invite is organized by the deal's reply address, and a cancelled viewing sends a cancellation to the same calendars. It is a convenience for the person's calendar; deal.viewing_booked and deal.viewing_cancelled stay the events to build on.
Events lists every event with its fields and an example.
6. Test in the sandbox
You don't need a real tenant to see these events. On the sandbox (https://api-sandbox.shace.se/partner/v1, with a sandbox key), the Sandbox endpoints play the tenant's side, one call per step. They do not exist in production. Your sandbox organization needs full integration too, like the Deals endpoints; Shace turns it on with the sandbox account.
Code
A test tenant shows interest in the listing, which must be published, and your endpoint gets deal.created. Accept it as in step 4 and drive the conversation with the first three calls below. Withdraw, reopen and expire need a lead you have not answered, so create another test lead for those:
| Call | What happens | Event |
|---|---|---|
POST /sandbox/deals/{id}/message | The tenant writes in the chat | deal.message_created |
POST /sandbox/deals/{id}/viewing | Your side offers a viewing tomorrow at 10:00 Stockholm time and the tenant books it | deal.viewing_proposed, deal.viewing_booked |
POST /sandbox/deals/{id}/contract | Both sides sign a placeholder contract | deal.contract_signed |
POST /sandbox/deals/{id}/withdraw | The tenant withdraws a pending lead | deal.lost |
POST /sandbox/deals/{id}/reopen | The tenant comes back after withdrawing | deal.reopened (deal.created if no earlier event about the deal was sent to your organization) |
POST /sandbox/deals/{id}/expire | The lead runs out unanswered | deal.expired |
A call the deal is not ready for answers 409 with the reason in data.reason, and an id that is not a test deal answers 404. Each call returns the deal as it is afterwards.
The same steps are one click each under Developer > Playground in the sandbox dashboard, for when you would rather watch your receiver than write the calls.