AthausDocs

REST API: projects

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.

Last updated:

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. 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.

OperationWhat it does
GET /v1/projectsthe external ids of the projects, newest first, in pages
GET /v1/projects/{externalProjectId}one project, with an ETag
POST /v1/projectscreates 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}/unitscreates up to 500 units
POST /v1/projects/{externalProjectId}/assignmakes existing listings units
POST /v1/projects/{externalProjectId}/unassignreleases units from the project
POST /v1/listings/{externalListingId}/unit-statussets the status of a unit

Two ids

IdWhoseWhere
externalProjectIdyoursin the path of every call, as metadata.source.offererMarketingKey in the body
projectIdoursin 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.

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

WhatSame as listings
Idempotency-Keya repeat with the same key and body answers the same receipt and creates one project
ETag and If-MatchGET carries the tag; PUT with a stale tag answers 412
Paginglimit, nextPageToken, updatedSince, newest first
Errorsproblem details with code and errors[].name naming the member
Answer of a write202 with a receipt: requestId, projectId, externalProjectId, warnings
PUTmerges: a member the body does not name stays; createIfMissing=true creates

What is stored

The members of a project stand once on the listing members page. 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

MemberWhereMeaning
statusrequest and responsethe name of one of the project states of the office, for example Vertrieb; without it a new project starts in the first state
projectIdresponsethe id Athaus gave the project
createdAt, updatedAtresponsewhen the project was created and last changed
projectsin the id lista summary of each project: projectId, externalProjectId, status, updatedAt

Units

A unit is a listing with a project, not a second resource. It has every operation and member of a listing, 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

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.

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:

MemberMeaning
unitrequired, the unit number, up to 40 characters
externalListingIdyour reference of the listing, like metadata.source.offererMarketingKey
building, floor, rooms, livingSpace, pricebuilding, floor, rooms, living space in m², price in euros (for rent the monthly base rent)
statusfree (without it), option, reserved, sold or rented

What is refused, and how:

CaseAnswer
unit number already in the project409 unit_already_exists, errors names units[n].unit
unit number twice in the body400, errors names the second position
reference already carried by a listing409 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 listings403 plan_required
more than 500 units400
the project would hold more than 1000 units409 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

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

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 /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

project.created and project.updated are events and webhooks. 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

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.

Keep reading

On this page