---
title: "Getting Started"
description: "From access to your first generated listing in ten minutes."
url: "https://real-estate-agency.apim.eu/getting-started"
image: "https://real-estate-agency.apim.eu/_og/d/c_Ocean.takumi,title_Getting+Started,description_From+access+to+your+first+generated+listing+in+ten+minutes.,props_eyJ0aGVtZSI6eyJtb2RlIjoiZGFyayIsImNvbG9ycyI6eyJwcmltYXJ5IjoiI0Q0QTI0QyJ9fX0,p_Ii9nZXR0aW5nLXN0YXJ0ZWQi,s_VXgqvAlY_TmmnNkx.png"
---

## Getting Started

From access, through your first application, to a fully generated listing - this guide walks you through the complete onboarding.

## [1\. Request Access](#_1-request-access)

Register with your business email address. We verify the entry against your real estate license; approval usually happens the next business day.

Until then, the **sandbox** is open to you. It contains a full sample portfolio of twelve properties, thirty leads and a handful of appointments. Sandbox data resets every night.

## [2\. Create an Application](#_2-create-an-application)

Every integration is its own application. Create one under **My Apps** and choose which APIs it's allowed to use.

Use a separate application per environment - that way a single key can be revoked without interrupting production.

## [3\. Generate an API Key](#_3-generate-an-api-key)

For each application you generate an **API key**. It's shown exactly once - after that it can't be read again, only replaced.

```text
re_live_7f3c9a24b1e84d05a6c2f8e1d3b70945
```

Each key has the scopes it's allowed to use attached to it. Grant only what the given process actually needs: an import job doesn't need write access to commissions.

Keep the key in a secret store, not in version control.

## [4\. Your First Call](#_4-your-first-call)

The key goes along with every call in the `apikey` header. The quickest useful call is listing your properties:

```bash
curl "https://api.realestateagency.example/v1/properties?status=active&limit=5" \
  -H "apikey: $REAL_ESTATE_API_KEY"
```

```json
{
  "data": [
    {
      "id": "prop_8f2c1a",
      "type": "apartment",
      "title": "3-Bedroom Period Home near Riverside Park",
      "address": { "street": "148 Elm Street", "postal_code": "10001", "city": "Springfield" },
      "living_area_sqm": 86.5,
      "purchase_price_eur": 645000,
      "status": "active"
    }
  ],
  "page": { "count": 1, "total": 12, "next_cursor": null }
}
```

## [5\. Your First Listing](#_5-your-first-listing)

With a property ID and a template, you generate a listing:

```bash
curl -X POST https://api.realestateagency.example/v1/listings \
  -H "apikey: $REAL_ESTATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "property_id": "prop_8f2c1a",
        "template_id": "tpl_classic",
        "sections": ["location", "features", "energy", "floor_plan"]
      }'
```

Generation runs asynchronously. The response returns status `in_progress`; once it reaches `completed`, `GET /listings/{id}/pdf` returns the finished document. Alternatively, subscribe to the `listing.completed` event via webhook.

Details on templates, sections and mandatory disclosures are in the guide [From Property to Listing](https://real-estate-agency.apim.eu/guides/listing-workflow).

## [Error Format](#error-format)

All APIs respond the same way on error:

```json
{
  "code": "mandatory_disclosure_missing",
  "message": "Mandatory disclosures from the energy certificate are missing for publication.",
  "details": [
    { "field": "energy_certificate.final_energy_demand_kwh", "reason": "missing" },
    { "field": "energy_certificate.valid_until", "reason": "expired" }
  ]
}
```

| HTTP | code                         | Meaning                                         |
| :--- | :--------------------------- | :---------------------------------------------- |
| 400  | validation_failed            | Request doesn't match the schema                |
| 401  | not_authenticated            | Key is missing, revoked or invalid              |
| 403  | scope_missing                | The key lacks the required scope                |
| 404  | not_found                    | Property, listing or appointment doesn't exist  |
| 409  | conflict                     | State doesn't allow it, e.g. publishing a draft |
| 422  | mandatory_disclosure_missing | A required disclosure is missing                |
| 429  | too_many_requests            | Rate limit reached                              |

## [Rate Limits](#rate-limits)

| Environment | Requests per minute | Listing generations per hour |
| :---------- | :------------------ | :--------------------------- |
| Sandbox     | 60                  | 20                           |
| Production  | 600                 | 200                          |

Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`. On `429`, a well-built client waits the number of seconds stated in `Retry-After` instead of retrying immediately.

## Ready for Your First Integration?

Register, create an application, and generate your first listing in under ten minutes.

[Request Access](https://real-estate-agency.apim.eu/getting-started)[View API Catalog](https://real-estate-agency.apim.eu/apis)