# REST API: projects

Adresse: https://docs.athaus.ai/en/api/v1/projekte

> Read and write new-build projects in the shape of OpenImmo 2.0. Two ids, the right `projects`, receipts, and the members that are ours.

Type: Reference
Last updated: 2026-11-17

A project at `/v1/projects` is a new-build project of the office: an address, a name, a stage of building and the figures of its units. It has the shape of the project in [OpenImmo 2.0](https://www.openimmo.de). The names, the nesting and the allowed values are the standard's. The units of a project are listings; this page describes the project itself.

| Operation                                           | What it does                                                     |
| --------------------------------------------------- | ---------------------------------------------------------------- |
| `GET /v1/projects`                                  | the external ids of the projects, newest first, in pages         |
| `GET /v1/projects/{externalProjectId}`              | one project, with an `ETag`                                      |
| `POST /v1/projects`                                 | creates a project                                                |
| `PUT /v1/projects/{externalProjectId}`              | updates it; with `createIfMissing=true` it creates an unknown id |
| `DELETE /v1/projects/{externalProjectId}`           | removes a project that has no units                              |
| `POST /v1/projects/{externalProjectId}/units`       | creates up to 500 units                                          |
| `POST /v1/projects/{externalProjectId}/assign`      | makes existing listings units                                    |
| `POST /v1/projects/{externalProjectId}/unassign`    | releases units from the project                                  |
| `POST /v1/listings/{externalListingId}/unit-status` | sets the status of a unit                                        |

## Two ids [#two-ids]

| Id                  | Whose | Where                                                                           |
| ------------------- | ----- | ------------------------------------------------------------------------------- |
| `externalProjectId` | yours | in the path of every call, as `metadata.source.offererMarketingKey` in the body |
| `projectId`         | ours  | in responses and events; it always works in the path                            |

A reference follows the rule of a listing's: 1 to 128 letters, digits, dots, underscores or hyphens. It is unique among the projects of the office (`reference_already_exists`). A project without a reference has its own `projectId` as external id.

## The right `projects` [#right]

`projects` is a resource of its own among the key rights, and a key has it only when it asks for it: it is `none` until chosen when the key is created in the app. A key made before that has none. Reading needs `read`, writing needs `write`; without it every operation answers `403` with `insufficient_permissions`. A test key works in the test office like a live key in a real one: it changes only invented data.

## Write like a listing [#writing]

| What                  | Same as listings                                                                     |
| --------------------- | ------------------------------------------------------------------------------------ |
| `Idempotency-Key`     | a repeat with the same key and body answers the same receipt and creates one project |
| `ETag` and `If-Match` | `GET` carries the tag; `PUT` with a stale tag answers `412`                          |
| Paging                | `limit`, `nextPageToken`, `updatedSince`, newest first                               |
| Errors                | problem details with `code` and `errors[].name` naming the member                    |
| Answer of a write     | `202` with a receipt: `requestId`, `projectId`, `externalProjectId`, `warnings`      |
| `PUT`                 | merges: a member the body does not name stays; `createIfMissing=true` creates        |

## What is stored [#members]

The members of a project stand once on the [listing members page](/en/api/v1/referenz#projects). How they map to the project in the app:

* `data.texts.headline` is the name of the project and is required when it is created. `description`, `area` and `features` are its description, location text and equipment text.
* `data.location` is the address, read and written like the location of a listing. The country is always Germany.
* `data.distributionType` is `BUY` or `RENT`. `BUY_RENT` is refused.
* `data.program.projectStatus` is the stage of building: `CONSTRUCTION_START` is under construction, `PROJECT_ENDED` is finished.
* `data.deliveryDate` is the planned completion, up to 60 characters.
* `data.units` carries figures that Athaus counts from the units: `numberOfUnits`, `priceFrom`, `priceTo`, `livingSpaceFrom`, `livingSpaceTo`, `soldOutPercentage`. Only the buyer provision is written: `provisionType`, `provisionPercent` and `provisionIsVatIncluded`.
* `data.estateType` is always `NEW_BUILD_PROJECT`; `NEW_HOME_PROJECT` is accepted and stored as a new-build project.

A member the standard has and Athaus does not store (`links`, `contact`, `structure`, `estateSubType`, the figures of `units` above) is accepted and answered with a warning `FIELD_IGNORED`; nothing is dropped quietly.

### Members that are ours [#own]

| Member                   | Where                | Meaning                                                                                                                         |
| ------------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `status`                 | request and response | the name of one of the project states of the office, for example `Vertrieb`; without it a new project starts in the first state |
| `projectId`              | response             | the id Athaus gave the project                                                                                                  |
| `createdAt`, `updatedAt` | response             | when the project was created and last changed                                                                                   |
| `projects`               | in the id list       | a summary of each project: `projectId`, `externalProjectId`, `status`, `updatedAt`                                              |

## Units [#units]

A unit is a listing with a project, not a second resource. It has every operation and member of a [listing](/en/api/v1/inserate), and `projectId` tells which project it belongs to. `projectId` is read-only: it is in the answer of `GET /v1/listings/{externalListingId}`, and a listing without a project has none. `GET /v1/projects/{externalProjectId}` names the units in `assignedListings` (a member of ours, not OpenImmo's). A project holds at most 1000 units, so this list and the project in every event stay bounded: a create or an assign that would pass the cap is `409` `project_unit_limit_exceeded` and changes nothing. The unit number is the listing's `data.location.unit` and is unique in the project, upper and lower case alike. A created unit carries the address line of its project.

### Create units [#create-units]

`POST /v1/projects/{externalProjectId}/units` creates up to 500 units in one call. The call is all or nothing: if even one unit is refused, none is created, and `errors` names every refused unit by its position in the body. The unit takes address, texts, energy data and commission from the project; the listing operations change it afterwards. Creating publishes nothing.

```bash
curl -X POST "https://api.athaus.ai/v1/projects/PRJ-7/units" \
  -H "Authorization: Bearer ath_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "units": [
    { "externalListingId": "PRJ-7-WE-1", "unit": "WE 1", "building": "A", "floor": 1, "rooms": 3, "livingSpace": 78.5, "price": 429000 },
    { "externalListingId": "PRJ-7-WE-2", "unit": "WE 2", "building": "A", "floor": 2, "rooms": 2, "livingSpace": 54, "price": 319000, "status": "option" }
  ]
}'
```

The answer is `202` with a receipt that names the `listings` in the order of the body. These members of a unit are ours, not OpenImmo's:

| Member                                               | Meaning                                                                                     |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `unit`                                               | required, the unit number, up to 40 characters                                              |
| `externalListingId`                                  | your reference of the listing, like `metadata.source.offererMarketingKey`                   |
| `building`, `floor`, `rooms`, `livingSpace`, `price` | building, floor, rooms, living space in m², price in euros (for rent the monthly base rent) |
| `status`                                             | `free` (without it), `option`, `reserved`, `sold` or `rented`                               |

What is refused, and how:

| Case                                                                                                   | Answer                                                                        |
| ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| unit number already in the project                                                                     | `409` `unit_already_exists`, `errors` names `units[n].unit`                   |
| unit number twice in the body                                                                          | `400`, `errors` names the second position                                     |
| reference already carried by a listing                                                                 | `409` `reference_already_exists`, `errors` names `units[n].externalListingId` |
| status does not fit the distribution type (`sold` in a rental project, `rented` in a project for sale) | `409` `unit_status_invalid`                                                   |
| more units than the plan allows listings                                                               | `403` `plan_required`                                                         |
| more than 500 units                                                                                    | `400`                                                                         |
| the project would hold more than 1000 units                                                            | `409` `project_unit_limit_exceeded`                                           |

A repeat with the same `Idempotency-Key` returns the first answer again. The same units with a new key do not create a second set: the call answers `409` (`reference_already_exists` when the units name references, else `unit_already_exists`), and `errors` names the existing units.

### Assign and release [#assign]

`POST /v1/projects/{externalProjectId}/assign` makes existing listings units, up to 500, all or nothing. The body is `{ "externalListingIds": [...] }`. Each listing keeps its data; its `data.location.unit` is the unit number, must be set and must be unique in the project. A listing without a unit number is `400`, a number already taken is `409` `unit_already_exists`, each with `externalListingIds[n]` in `errors`. A unit of another project is refused (`400`): release it there first with `unassign`. A listing whose unit status does not fit the project (a released `sold` unit into a rental project) is `409` `unit_status_invalid`. A listing that is already a unit of this project stays as it is, so a repeat changes nothing. If the project would hold more than 1000 units, it is `409` `project_unit_limit_exceeded`.

`POST /v1/projects/{externalProjectId}/unassign` releases units: they stay as plain listings with all their data and hold the key of their own address. If another listing holds that address, it is `409` `address_already_exists`. The listing keeps its state: a reserved or sold unit stays reserved or closed, a paused one stays paused; `unit.status_updated` is not sent, because the listing is no unit any more. A listing that is not a unit of this project is `400`.

Both answer `202` with a receipt naming the `listings`, and send `project.updated`.

### Status of a unit [#unit-status]

`POST /v1/listings/{externalListingId}/unit-status` sets the status of a unit, as the buttons of the unit list in the app do. The body is `{ "status": "reserved" }`; the answer is `200` with the listing. Every status except `free` takes a running listing off the market (its `status` becomes `paused`); `reserved`, `sold` and `rented` also set the listing's `reserved` or `closed` state. The same status again changes nothing. A listing that is not a unit is `409` `listing_not_unit`; a status that does not fit the project is `409` `unit_status_invalid`. It needs `write` on `listings`.

## Delete [#delete]

`DELETE /v1/projects/{externalProjectId}` removes a project without units and answers `202` with a receipt; `If-Match` applies as on `PUT`. A project with units is `409` `project_not_empty`: release them with `unassign` or delete their listings first. The listings of a project never vanish with it.

## Events [#events]

`project.created` and `project.updated` are [events](/en/api/v1/ereignisse) and [webhooks](/en/api/v1/webhooks#events). `data.object` is the project as `GET` returns it, with `id`, `projectId` and `externalProjectId` at the top. A removed project is `{ object: "project", id, deleted: true }`. A key sees them with `read` on `projects`.

`unit.status_updated` comes when the status of a unit changes. `data.object` is the unit: `{ object: "unit", id, externalListingId, projectId, externalProjectId, unit, status, previousStatus }`, with the `listingId` as `id`. A receiver tells a unit from a plain listing by the kind of event and by `projectId`, which the listing also carries when read; a listing without a project never causes this event.

## Test mode [#test]

The test office holds one invented sample project, `TEST-PROJEKT-1`, with three units (`TEST-PROJEKT-1-WE-1` to `-WE-3`). `POST /v1/test/reset` removes the projects of the test office with their units and sets the sample project back. A test key never publishes: the units run on no portal and on no public new-build page.
