Create the units of a project
Request, parameters, response and errors of POST /v1/projects/{externalProjectId}/units.
Last updated:
Creates up to 500 units in one call, each a listing of the project: it takes the address, texts, energy data and commission from the project, and the listing operations change it afterwards. The call is all or nothing: if any item is refused, nothing is created and errors names every refused item by its position (units[3].unit). A unit number already in the project, upper and lower case alike, is 409 unit_already_exists; a number twice in the call is 400; a reference another listing carries is 409 reference_already_exists; a status that does not fit the project is 409 unit_status_invalid. A repeat of the same body with a new Idempotency-Key creates nothing and answers 409 (reference_already_exists when the units name references, else unit_already_exists), and errors names the units that exist; a repeat with the same key answers the first answer again. A project holds at most 1000 units: a call that would pass that is 409 project_unit_limit_exceeded and changes nothing. The units count against the plan's listings (403 plan_required). Creating does not publish. Needs write access to projects.
Requires the scope propose and at least the level write on projects.
Request
POST https://api.athaus.ai/v1/projects/{externalProjectId}/unitsParameters
Path
| Name | Type | Required | Description |
|---|---|---|---|
externalProjectId | string | yes | Your reference of the project: the value of metadata.source.offererMarketingKey. A project without one has its own projectId here, and the projectId always works in the path. 1 to 128 letters, digits, dots, underscores or hyphens, not starting or ending with a dot. |
Header
| Name | Type | Required | Description |
|---|---|---|---|
Athaus-Version | string | no | Optional and carries nothing a client needs: the version is the path. Accepted when it says v1 or 1. Any other value is a 400 api_version_unsupported. |
Idempotency-Key | string | no | Makes a retry safe: the same key with the same body returns the first answer and writes nothing twice. A random value of at least 128 bits, for example a UUID, 1 to 255 characters. The key is kept for 24 hours and scoped to the API key and this operation. The same key with a different body is a 422; while the first request still runs it is a 409. Only successful answers are kept: after an error the key is free again. |
Request body
JSON with Content-Type: application/json. A field the API does not know is a 400, and errors[].name names the field. The body is required.
| Field | Type | Description |
|---|---|---|
units | object[] | |
units[].externalListingId | string | Your reference of the listing the unit becomes (its metadata.source.offererMarketingKey). Without it the listing has only its own listingId. |
units[].unit | string | The unit number, the listing's data.location.unit. Unique in the project, upper and lower case alike. |
units[].building | string | The house or building within the project. |
units[].floor | integer | -5 to 200. |
units[].rooms | number | to 50. |
units[].livingSpace | number | Square metres. |
units[].price | number | Euros; for a rental project the monthly base rent. |
units[].status | string | Ours, not OpenImmo. A rental project knows free, option, reserved and rented; a project for sale knows free, option, reserved and sold. One of free, option, reserved, sold, rented. |
Example
curl -X POST "https://api.athaus.ai/v1/projects/PRJ-1-ext/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"}]}'Response
On success the status is 202 with ProjectUnitsReceipt.
ProjectUnitsReceipt
| Field | Type | Description |
|---|---|---|
requestId | string | |
projectId | string | |
externalProjectId | string | |
listings | object[] | The listings the call created or moved, in the order of the request. |
listings[].listingId | string | |
listings[].externalListingId | string | |
listings[].unit | string | |
warnings | object[] | |
warnings[].type | string | |
warnings[].message | string |
Response headers
| Header | Description |
|---|---|
Request-Id | Identifies this request. Quote it in a support request. |
Athaus-Version | The API version of this response: v1. |
Athaus-Release | The release of v1 that answered, for example 1.0. A label for support and changelogs; no request can select it. |
RateLimit-Policy | The quota policy of the bucket that applies. |
RateLimit | Remaining quota and seconds until the bucket is full again. |
Idempotent-Replayed | true when this is the stored answer to an earlier request with the same Idempotency-Key. |
Errors
Every error arrives as problem details. Branch on code, not on title or detail.
| Status | Codes | Meaning |
|---|---|---|
400 | api_version_unsupported, invalid_body | Invalid request. |
401 | unauthorized | Missing or invalid API key. |
403 | insufficient_permissions, plan_required | The key lacks a right, or the plan does not include API access. |
404 | not_found | Nothing under this ID. |
409 | unit_already_exists, reference_already_exists, unit_status_invalid, project_unit_limit_exceeded, idempotency_key_in_use, idempotency_outcome_unknown | The request conflicts with the state of the resource (for example a duplicate), or with an idempotency key. |
413 | payload_too_large | The request body is larger than 512 KB. |
415 | invalid_input | The request body is not JSON. Send Content-Type: application/json. |
422 | idempotency_key_reused | The idempotency key was already used with a different request body. |
429 | rate_limited | Rate limit exceeded. |
500 | internal_error | Server error. |
Keep reading
REST API: authentication with an API key
Every call to /v1 carries an API key as a bearer token. Where to get one, which scopes it carries and what does not work.
REST API: errors as problem details
Every error from /v1 is an RFC 9457 problem with a real HTTP status, a code to branch on and a request id for support.