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

1. You add your endpoint and check it with a test event (step 1 below).
2. Shace switches your organization to full integration.
3. New leads arrive as `deal.created` from 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`:

```bash
curl -X POST "https://api-sandbox.shace.se/partner/v1/webhooks/$ENDPOINT_ID/test" \
  -H "Authorization: Bearer $SHACE_API_KEY"
```

## 2. Receive events

Each event is a JSON `POST` with the body `{ id, type, createdAt, data }`. Your receiver should:

1. **Verify the signature.** Signatures follow [Standard Webhooks](https://www.standardwebhooks.com), which has libraries for most languages, .NET included.
2. **Answer with any `2xx` within 10 seconds.** If processing takes longer, store the event, answer, and process it afterwards: a `2xx` is final.
3. **Drop repeats by `id`.** An event can arrive more than once.
4. **Keep the newest state.** Events can arrive out of order, after a retry or when two happen close together. `createdAt` does not guarantee order either, so treat an event as a signal that the deal changed. When order matters, read the current deal with `GET /deals/{id}`.
5. **Ignore event types you do not know.** Shace adds new ones without notice; answer them with a `2xx` like any other.

A failed delivery is retried for about 28 hours. The [webhooks overview](/webhooks) has the signature steps and the retry schedule.

## 3. Create the lead

`deal.created` carries the deal:

```json
{
  "id": "9a7c5e3b-1f2d-4b6a-8c0e-2d4f6a8b0c1e",
  "type": "deal.created",
  "createdAt": "2026-09-24T09:12:40.130Z",
  "data": {
    "deal": {
      "id": "3f6b1d2e-8c47-4a0e-9f5d-7b2c1e4a9d30",
      "status": "pending",
      "expiresAt": "2026-10-08T09:12:40.118Z",
      "reference": "VAS-1042",
      "replyAddress": "vas-1042@chat.shace.se",
      "listing": {
        "id": "5c1c8f0e-6a3b-4a4c-9a3e-2b7f0d9a1e11",
        "externalRef": "unit-4711",
        "metadata": { "responsibleId": "E-4411" }
      },
      "tenant": {
        "companyName": "Lumen Design AB",
        "orgNumber": "5591234567",
        "country": "SE",
        "underRegistration": false,
        "description": null
      },
      "request": { "city": "stockholm", "teamSize": "8", "moveIn": "1-3m" }
    }
  }
}
```

The example is shortened; [The deal](/webhooks/events#the-deal) has every field. What to do with the important ones:

- **`deal.id`**: key your records on it. The outer `id` is 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.externalRef` and `listing.metadata`**: your reference for the unit and the `metadata` you 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. `listing` is `null` for the rare lead that is not on one of your listings, and `externalRef` is `null` on 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 no `orgNumber` yet; `underRegistration` is `true` and `description` is 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 sends `deal.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.

```bash
curl -X POST "https://api-sandbox.shace.se/partner/v1/deals/3f6b1d2e-8c47-4a0e-9f5d-7b2c1e4a9d30/accept" \
  -H "Authorization: Bearer $SHACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hej! Kul att ni är intresserade av lokalen på Sveavägen 44. När passar det att komma på visning?",
    "from": "anna@landlord.se"
  }'
```

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_sent` with 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 sends `deal.viewing_proposed` and no `deal.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_proposed` comes with it (in no set order with `deal.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](/webhooks/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](/reference/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.

```bash
curl -X POST "https://api-sandbox.shace.se/partner/v1/sandbox/deals" \
  -H "Authorization: Bearer $SHACE_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "listingId": "ext:unit-4711" }'
```

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.
