# Quickstart

The Partner API lets your property system publish vacant premises to Shace. You push each unit under your own reference whenever it is saved on your side. Pushing the same reference again updates the listing, so nothing is ever duplicated. This page gets one listing live in three requests.

## Two ways to integrate

Shace sets up one of these with your organization:

- **Listings sync.** Your system pushes listings to Shace, and your team answers leads in the Shace app. Everything on this page works with it.
- **Full integration.** Listings sync, plus leads in your own system: Shace sends them to you as webhooks, and you answer them through the Deals endpoints or by mail. See [Receiving leads](/receiving-leads).

`GET /me` shows which one you have.

## Before you start

- **An API key.** Your organization's developers create keys under **Developer > API keys** in the Shace dashboard; Shace support makes someone a developer. A key looks like `shace_sk_` followed by 48 hex characters and acts for your organization only. Call the API from your backend: keys do not work from browser pages.
- **The host.** Build against the sandbox, `https://api-sandbox.shace.se/partner/v1`. It runs the same code as production with its own organization, keys and data, so nothing you push there reaches tenants. It has its own dashboard at `https://sandbox.shace.se`, where you create sandbox keys and endpoints. When you are ready, switch the host to `https://api.shace.se/partner/v1` and the key to a production one. Webhook endpoints are per environment too: add your production endpoint in the production dashboard and give your receiver its signing secret. The examples below use the sandbox host.

The [API reference](/reference) has every endpoint with field tables, examples and client snippets. It is generated from the running API, so it is always current. Its "Test request" button sends real requests to the server picked in the reference. Sandbox is picked by default, so use a sandbox key there. The OpenAPI document behind it is at [`https://docs.shace.se/openapi.json`](https://docs.shace.se/openapi.json), for Postman, code generators or an AI assistant, and [`/llms.txt`](https://docs.shace.se/llms.txt) lists these guides as Markdown.

## 1. Check the key

```bash
curl "https://api-sandbox.shace.se/partner/v1/me" \
  -H "Authorization: Bearer $SHACE_API_KEY"
```

The response names the organization the key acts for, and `org.integration` says whether it has listings sync (`listings`) or full integration (`full`). A `401` means the key is wrong, revoked or expired.

## 2. Push a listing

The last path segment is your reference for the unit. The first push of a reference creates the listing; every later push of it updates the listing. Before you run it, swap in three image URLs your system serves and your own email as `contact`.

```bash
curl -X PUT "https://api-sandbox.shace.se/partner/v1/listings/unit-4711" \
  -H "Authorization: Bearer $SHACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": { "streetAddress": "Sveavägen 44", "postalCode": "111 34", "city": "Stockholm" },
    "type": "office",
    "locale": "sv",
    "description": "Ljust hörnkontor på plan 4 med sex arbetsplatser.",
    "areaM2": 120,
    "capacity": 6,
    "price": { "amount": 38000, "currency": "sek", "period": "month" },
    "priceBasis": "total",
    "noticePeriod": 3,
    "images": [
      "https://media.example.se/units/4711/entrance.jpg",
      "https://media.example.se/units/4711/open-plan.jpg",
      "https://media.example.se/units/4711/meeting-room.jpg"
    ],
    "contact": { "email": "anna@landlord.se", "firstName": "Anna", "lastName": "Berg" }
  }'
```

A few fields need a word:

- **`images`**: a listing needs at least three to go live. Send the public `https` URLs your system already serves. Shace downloads each one once and hosts its own copy. If your photos are behind a login, upload them with `POST /uploads/images` and send the returned URLs instead (see [Uploads](/reference/uploads)).
- **`address`**: Shace geocodes it the first time your organization sends it.
- **`contact`**: the person responsible for the unit, required on every push. Use your own email, or a colleague's on your organization's email domain. See [Who is responsible for the unit](/publishing-from-your-system#who-is-responsible-for-the-unit).

The response is the listing as Shace stores it, with Shace's own URLs in `images`. Three fields tell you what happened:

- `outcome`: `created`, `updated` or `unchanged`.
- `status`: `published` when the listing is live.
- `publishBlockers`: what kept it from going live. Empty here.

Send the exact same request again and `outcome` is `unchanged`: nothing was written.

## 3. Read it back

```bash
curl "https://api-sandbox.shace.se/partner/v1/listings/ext:unit-4711" \
  -H "Authorization: Bearer $SHACE_API_KEY"
```

Wherever the API takes a listing's Shace id, `ext:` followed by your reference works too, so your system never has to store Shace ids.

## Next steps

- **Connect your system.** Call the push from step 2 when a unit marked for Shace is saved, and `POST /listings/ext:unit-4711/unpublish` when it comes off the market. [Publishing from your system](/publishing-from-your-system) covers the rules behind both calls.
- **Receive leads.** With full integration, Shace sends leads to your system as webhooks. See [Receiving leads](/receiving-leads).
- **Look up fields.** The [API reference](/reference) documents every field, default and error.
