# Quickstart

The Partner API lets your property system publish vacant premises to Shace directly. You push buildings and units by your own references whenever they are saved on your side; pushing the same reference again updates instead of duplicating. This page gets one listing live in four steps.

You need an API key from Shace. It looks like `shace_sk_` followed by 48 hex characters and is scoped to your organization. Keep it server side: by design, the API answers browser requests from this docs site only.

All examples use `https://api.shace.se/partner/v1`. Against the preview environment, use its API host instead; the paths are the same.

Every endpoint, with field tables, examples and client snippets in your language, is in the [API reference](/reference). The reference is generated from the running API, so it is always current. Its "Test request" button sends real requests: use a preview key and the preview host there.

## 1. Check the key

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

The response names the organization the key acts for and the rate limit tier. If you get `401`, the key is wrong, revoked or expired.

## 2. Upload three images

Listings need at least three images to go live. Upload them once and keep the returned URLs in your system; later pushes reuse them.

```bash
curl -X POST "https://api.shace.se/partner/v1/uploads/images" \
  -H "Authorization: Bearer $SHACE_API_KEY" \
  -F "files=@unit-4711-1.jpg" \
  -F "files=@unit-4711-2.jpg" \
  -F "files=@unit-4711-3.jpg"
```

The response carries `urls` in upload order. Shace converts the files to webp and resizes them, the same pipeline the app uses.

## 3. Push the listing

One request creates the building and the listing. The path segment is your reference for the unit; `address` reuses your organization's object at that address or creates and geocodes one. Later pushes with the same reference update the listing.

```bash
curl -X PUT "https://api.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" },
    "noticePeriod": 3,
    "images": [
      "https://storage.shace.se/listing-images/<your-org>/a.webp",
      "https://storage.shace.se/listing-images/<your-org>/b.webp",
      "https://storage.shace.se/listing-images/<your-org>/c.webp"
    ]
  }'
```

Read three fields in the response:

- `outcome` is `created`, `updated` or `unchanged`.
- `status` is `published` when the listing went live.
- `publishBlockers` lists what stopped it from going live. Empty here; see [Publishing from your system](/publishing-from-your-system) for what shows up otherwise.

Run the exact same request again and `outcome` is `unchanged`. Nothing was written, nothing was re-translated.

## 4. Read it back

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

Anywhere a Shace id is accepted, `ext:` followed by your reference works too, so your system never has to store our ids.

## From here

- Wire the request in step 3 to the save action in your system for units marked for Shace, and `POST /listings/ext:unit-4711/unpublish` to the action that takes a unit off the market. [Publishing from your system](/publishing-from-your-system) covers the rules that make this safe.
- Push buildings on their own with `PUT /objects/{id}` and point listings at them with `objectRef` when several units share an address.
- Use `GET /listings?updatedSince=` to verify what Shace holds without re-pushing.
- Read the [API reference](/reference) for every field, default and enum. Authentication, uploads and the error codes are documented there too, next to the things they describe.