Shace
Shace Partner API

Deals

Server

Full integration only. These endpoints are for organizations that get their leads as webhooks, set up with Shace. With listings sync, your team answers leads in Shace and every call here answers 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.


Retrieve a deal

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

The deal as it is now. Events can arrive out of order or late; when in doubt, read the current state here. listing.metadata is the listing's current metadata, while an event carries it as it was when the event was created.

Retrieve a deal › path Parameters

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

Shace id of the deal, from the event.

Retrieve a deal › Responses

OK

A tenant's interest in one of your listings.
id
​string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-… · required

Shace id of the deal.

status
​string · enum · required

pending: waiting for your answer. accepted: you took the tenant on and the conversation is open. declined: you said no. expired: nobody answered in time. lost: the tenant withdrew or Shace closed it.

Enum values:
pending
accepted
declined
expired
lost
createdAt
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

When the tenant showed interest.

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

When the deal entered its current status. Events that do not change the status (a viewing, a message) keep it. Neither this nor an event's createdAt guarantees the order events arrive in; when order matters, read the deal.

​required

When a pending deal expires unanswered; null in every other status. Expiry runs nightly, so the deal can still be answered until that run; deal.expired follows it.

​required

The deal's number at your organization, counting from 1000. Fixed for the deal's life.

​required

How people refer to the deal, like VAS-1042: your organization's prefix and the deal's number. Show it to your staff; key your records on id.

replyAddress
​string · email · pattern: ^(?!\.)(?!.*\.\.)([A… · required

The tenant's contact address for this deal. Store it as the lead's email: the tenant's messages arrive from it, and mail your staff send to it reaches the tenant's chat. The first mail to a pending deal accepts it.

url
​string · uri · required

The deal in Shace, for people with an account. Its form follows the status: /dashboard/deals?peek=<reference> (the lead) while pending, /chats/<id> (the conversation) once accepted, /dashboard/deals after that. Take it as a link; do not parse it.

​required

The listing the tenant is interested in; null when the match was not on one of your listings.

​object · required

Who the tenant is. Personal contact details are never shared; use replyAddress.

​object · required

What the tenant asked for. The listed codes are the current ones; treat an unknown value as free text.


Accept a deal

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

Takes the tenant on. message opens the conversation and is shown to the tenant as written by from, who also becomes responsible for the deal. Only a pending deal can be accepted. Answers 409 when the deal is no longer pending, the tenant has not finished signing up yet (try again later), the listing is unpublished (push it again first) or no longer yours, or nobody can answer for your organization (the member the lead is routed to has left and there is no owner; send from). A retry after a timeout can get 409 not_pending because the first attempt went through: after any 409, GET /deals/{id} to see where the deal stands.

Accept a deal › path Parameters

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

Shace id of the deal, from the event.

Accept a deal › Request Body

message
​string · minLength: 1 · maxLength: 5000 · required

The first message to the tenant, in plain text.

from
​string · email · pattern: ^(?!\.)(?!.*\.\.)([A…

Email of the member the message is from, for example a listing contact. Defaults to the member the lead is routed to (usually the listing's contact), or the owner.

Accept a deal › Responses

OK

A tenant's interest in one of your listings.
id
​string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-… · required

Shace id of the deal.

status
​string · enum · required

pending: waiting for your answer. accepted: you took the tenant on and the conversation is open. declined: you said no. expired: nobody answered in time. lost: the tenant withdrew or Shace closed it.

Enum values:
pending
accepted
declined
expired
lost
createdAt
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

When the tenant showed interest.

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

When the deal entered its current status. Events that do not change the status (a viewing, a message) keep it. Neither this nor an event's createdAt guarantees the order events arrive in; when order matters, read the deal.

​required

When a pending deal expires unanswered; null in every other status. Expiry runs nightly, so the deal can still be answered until that run; deal.expired follows it.

​required

The deal's number at your organization, counting from 1000. Fixed for the deal's life.

​required

How people refer to the deal, like VAS-1042: your organization's prefix and the deal's number. Show it to your staff; key your records on id.

replyAddress
​string · email · pattern: ^(?!\.)(?!.*\.\.)([A… · required

The tenant's contact address for this deal. Store it as the lead's email: the tenant's messages arrive from it, and mail your staff send to it reaches the tenant's chat. The first mail to a pending deal accepts it.

url
​string · uri · required

The deal in Shace, for people with an account. Its form follows the status: /dashboard/deals?peek=<reference> (the lead) while pending, /chats/<id> (the conversation) once accepted, /dashboard/deals after that. Take it as a link; do not parse it.

​required

The listing the tenant is interested in; null when the match was not on one of your listings.

​object · required

Who the tenant is. Personal contact details are never shared; use replyAddress.

​object · required

What the tenant asked for. The listed codes are the current ones; treat an unknown value as free text.


Decline a deal

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

Says no to the tenant. Only a pending deal can be declined; the tenant is not told the reason. Unlike accepting, declining also works when the listing has been unpublished since the lead arrived. After a 409 (for example a retry whose first attempt went through), GET /deals/{id} to see where the deal stands.

Decline a deal › path Parameters

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

Shace id of the deal, from the event.

Decline a deal › Request Body optional

reason
​string · maxLength: 500

Why, for Shace. Never shown to the tenant.

Decline a deal › Responses

OK

A tenant's interest in one of your listings.
id
​string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-… · required

Shace id of the deal.

status
​string · enum · required

pending: waiting for your answer. accepted: you took the tenant on and the conversation is open. declined: you said no. expired: nobody answered in time. lost: the tenant withdrew or Shace closed it.

Enum values:
pending
accepted
declined
expired
lost
createdAt
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

When the tenant showed interest.

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

When the deal entered its current status. Events that do not change the status (a viewing, a message) keep it. Neither this nor an event's createdAt guarantees the order events arrive in; when order matters, read the deal.

​required

When a pending deal expires unanswered; null in every other status. Expiry runs nightly, so the deal can still be answered until that run; deal.expired follows it.

​required

The deal's number at your organization, counting from 1000. Fixed for the deal's life.

​required

How people refer to the deal, like VAS-1042: your organization's prefix and the deal's number. Show it to your staff; key your records on id.

replyAddress
​string · email · pattern: ^(?!\.)(?!.*\.\.)([A… · required

The tenant's contact address for this deal. Store it as the lead's email: the tenant's messages arrive from it, and mail your staff send to it reaches the tenant's chat. The first mail to a pending deal accepts it.

url
​string · uri · required

The deal in Shace, for people with an account. Its form follows the status: /dashboard/deals?peek=<reference> (the lead) while pending, /chats/<id> (the conversation) once accepted, /dashboard/deals after that. Take it as a link; do not parse it.

​required

The listing the tenant is interested in; null when the match was not on one of your listings.

​object · required

Who the tenant is. Personal contact details are never shared; use replyAddress.

​object · required

What the tenant asked for. The listed codes are the current ones; treat an unknown value as free text.