Migrating from Gen1 (Legacy API)

Introduction

This guide supports you in migrating from the legacy system — commonly referred to as Gen1 — to the modern Gen2 platform.

It’s important to understand that Gen1 and Gen2 refer to two generations of the same platform:

• Gen1 represents the legacy API system.
• Gen2 is the current platform, designed with modern best practices, a new API structure, and robust versioning. This whole Developer Hub is built around Gen2.

Versioning

Within Gen2, API versions such as v1, v2, etc., refer only to versions of the Gen2 API. The Gen1 label is independent and should not be confused with v1 of Gen2.

Shared Dataset

Despite architectural and structural differences, both systems continue to operate on the same underlying dataset. This allows gradual migration and coexistence of both generations during transition phases.

---

Key Differences

---

Architectural Shift: View-Based ➜ Resource-Oriented

Gen1 was based on views and custom data structures. Gen2 introduces a more RESTful, resource-oriented model. This brings consistency and better alignment with industry standards.

Example:

Gen1: GET /object/getAll

Gen2: GET /api/properties (nested entities, that might be included in Gen1's response, need to be fetched individually)

📘

Performance

The Gen2 API and the underlying system is designed for a multiple of (small) request. Therefore, we highly encourage to leverage mechanisms like paralism or concurrent execution of request to really leverage the performance of the new system, when requesting different entities or building complex, nested entities.

Pagination

In Gen1, pagination was inconsistently implemented — many endpoints returned full datasets without any limit or offset. This often forced clients to handle large responses and implement pagination manually, if at all.

In Gen2, pagination is a core part of the API design and consistently applied across all collection endpoints. Every GET /api/<entity>/ and POST /api/<entity>/search endpoint returns results in a paginated format by default. This approach enables better performance, improves scalability, and lays the groundwork for integrated filtering and sorting.

📘 Learn more about Pagination.

Filtering

Gen1 supported filtering inconsistently, typically via individual query parameters on GET endpoints. These typically varied from endpoint to endpoint.

In Gen2, filtering is standardized and powered through dedicated search endpoints. Instead of using GET, you should send a POST request to /api/<entity>/search with a JSON body specifying your filter criteria. This structure allows for flexible, composable queries across many fields.

🔍 For example: use POST /api/properties/search instead of trying to filter with GET /api/properties.

📘 Learn more about Filtering.

Sorting

Sorting in Gen1 was limited or non-existent — often the entire dataset was returned without defined order, and any sorting had to be handled client-side.

In Gen2, all GET /api/<entity>/ endpoints support basic sorting using query parameters. For more complex sorting (e.g., nested fields, multiple keys), the POST /api/<entity>/search endpoints should be used instead, where you can define detailed sort rules in the request body.

📘 Learn more about Sorting.

---

Entity Name Changes

Some entity names and structures have changed to better reflect their role in the domain. The tables below outline common mappings (1:1 mappings and sub-entities are omitted):

⚠️

WIP

This is a work-in-progress. Not all Gen1 entites, endpoints or use cases are covered yet in Gen2.

Authentication, People and Organization

Master Data

Operational Data

Common Misconceptions

Some name changes between Gen1 and Gen2 may be misleading if taken at face value. Here are the most common ones to watch out for:

Property

The meaning of property changed from custom metadata fields in Gen1 (which is now referenced as Attribute) to a building or property in Gen2 (which was formerly referenced as object).

User

users in Gen1 generally meant any individual account holder for a certain company (e.g., tenant, owner, contractor employee, property management employee, etc.).

→ In Gen2, these are now called Accounts in general. A User in Gen2 is more precisely a type of Party (in this party type the following people fit: owners, tenants, residents, etc.). In regard to naming, this is decoupled from Accounts, even though a Party of the type User can have an Accountnevertheless. See here for more.

Tenant

Tenant wasn't an entity in Gen1, but it is a type of flatcompany (UnitContract). See more here about available unit contracts for Users (Gen2 meaning here).

→ In addition to that, in Gen2, Tenant is also the new name for Gen1's projects.

---

Migration Strategy

1. Audit Usage
   Identify all Gen1 entities your system interacts with.
2. Map Entities
   Use the table above to find the equivalent Gen2 entities.
3. Prepare Authentication
   Switch to using Gen2-compliant OAuth2 tokens.
4. Refactor API Calls
   Migrate routes from root-based to /api/ and adjust to new concepts introduces in Gen2 (resource-based, pagination, search endpoints, etc.).
5. Test Side-by-Side
   Because both systems share the dataset, you can validate behaviour in parallel.

---

Still Need Help?

Join the discussion in the Developer Forum or check out individual API references for Gen2 to get full technical details.