# REST API: what leaves the office

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

> Reply to and follow up with people who inquired. When a message goes out at once and when a proposal waits for a yes (202), and how to read the outcome.

Type: Guide
Last updated: 2026-11-16

Some operations reach a person outside the office. Today there are three, two on an inquiry and one on a listing:

| Path                                            | What happens                                                                                                                    |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `POST /v1/inquiries/{id}/messages`              | a reply to the person who inquired                                                                                              |
| `POST /v1/inquiries/{id}/followUps`             | a follow-up; without `text`, with the standard text from Athaus                                                                 |
| `POST /v1/listings/{externalListingId}/publish` | the listing goes online; the answer is `200` with the listing or `202` with a proposal ([Listings](/en/api/v1/inserate#status)) |

An email cannot be taken back. So your key alone does not decide whether it goes out.

## Go out or wait [#go-out-or-wait]

The rule is the same as for the MCP tool `draft_reply`. A message goes out right away only if both hold:

1. The key has the scope `approve`.
2. The office has set this kind of message to "Automatic" in the app under automation.

| Key            | Office    | Answer                            |
| -------------- | --------- | --------------------------------- |
| `approve`      | Automatic | `201`, the message is queued      |
| `approve`      | Ask first | `202`, a proposal waits           |
| only `propose` | any       | `202`, a proposal waits           |
| only `read`    | any       | `403`, `insufficient_permissions` |
| any            | Off       | `409`, `automation_disabled`      |

Even `201` does not mean "delivered". The email sits in the queue; it is delivered once the proposal reads `executed`.

The key also needs the level `write` on `inquiries`.

## Read the level [#read-the-level]

`GET /v1/automations` names the level of the office for every kind of action: `off`, `ask` or `auto`. `GET /v1/automations/reply` returns the level for replies, `follow_up` the one for follow-ups. Read it before sending if you want to know whether a message answers `201` or `202`. You cannot set a level through the API: whoever manages the office does that in the app. A test key sees the levels of its test office. The key needs the level `read` on `inquiries`.

## The Idempotency-Key header is required [#the-idempotency-key-header-is-required]

Without it the API answers `400` with `idempotency_key_missing`, and nothing runs. Send a new UUID per message and reuse it only to retry exactly that request.

A retry gets the same answer with `Idempotent-Replayed: true`, a `202` included, with the same proposal. A second one is never created. The stored answer shows the state of the first call: read today's under `GET /v1/proposals/{id}`. The other rules are under [Writing](/en/api/v1/schreiben#retry-without-writing-twice).

## The 202 and the proposal [#the-202-and-the-proposal]

```bash
curl -X POST https://api.athaus.ai/v1/inquiries/0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17/messages \
  -H "Authorization: Bearer ath_live_..." \
  -H "Idempotency-Key: 6f1d9a4e-2b0c-4d7e-8a35-91c7e2f0b8d3" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello, the apartment is still available. I would be glad to show it to you this week."}'
```

```http
HTTP/1.1 202 Accepted
Location: /v1/proposals/0190f3b8-5a21-7c34-9e10-4d8a6b2c7f15
```

```json
{
  "object": "proposal",
  "id": "0190f3b8-5a21-7c34-9e10-4d8a6b2c7f15",
  "status": "pending",
  "action": "inquiry.reply",
  "target": { "object": "inquiry", "id": "0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17" },
  "text": "Hello, the apartment is still available. I would be glad to show it to you this week.",
  "livemode": true,
  "createdAt": "2026-11-12T09:14:03Z",
  "decidedAt": null,
  "decidedBy": null,
  "executedAt": null
}
```

Nothing has gone out. A person in the office sees the proposal in the app and says yes or no. Through the API only a key with the scope `decide` decides ([Deciding without a person](#decide)).

For `publish`, `action` is `listing.publish` and `target` is the listing (`listingId`); `executedAt` is set once it is online.

The list of `action` values is open: new ones arrive, and that is no break. Treat an unknown value as a proposal that you follow by `status` only.

## States [#states]

`GET /v1/proposals/{id}` returns the proposal, `GET /v1/proposals` the list (cursor as everywhere, filter `status`, sort `createdAt`). A key sees only the proposals it created itself. Someone else's proposal is `404`.

| `status`   | Meaning                                                                                                             |
| ---------- | ------------------------------------------------------------------------------------------------------------------- |
| `pending`  | waits for a yes or no                                                                                               |
| `approved` | yes was said, the email is in the queue, not yet delivered                                                          |
| `executed` | delivered (`executedAt` is set)                                                                                     |
| `failed`   | yes was said, but delivery gave up after all retries                                                                |
| `rejected` | a person said no                                                                                                    |
| `expired`  | lapsed: a newer proposal of the same kind for the same inquiry replaced it, or the office handled the matter itself |

There is no deadline. A proposal waits until someone decides or it lapses. Do not poll every second: a call every few minutes is enough.

`text` is the message as it goes out. If a person changed it before saying yes, the changed text is there.

## What the API rejects [#what-the-api-rejects]

| Status | Code                                                                | Cause                                                                                                                |
| ------ | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `400`  | [`idempotency_key_missing`](/en/api/errors#idempotency_key_missing) | the header is missing                                                                                                |
| `400`  | [`invalid_body`](/en/api/errors#invalid_body)                       | an unknown field, an empty text, or the text states something that is not on the listing (`errors[].name` is `text`) |
| `404`  | [`not_found`](/en/api/errors#not_found)                             | no such inquiry in this office                                                                                       |
| `409`  | [`address_missing`](/en/api/errors#address_missing)                 | the person has no way to be reached through Athaus: no account and no email address                                  |
| `409`  | [`automation_disabled`](/en/api/errors#automation_disabled)         | the office has switched this kind of message off; nothing is prepared                                                |

The text is checked against the facts on the listing before anything is created. A key is not a source of facts: what is not on the listing, the API does not put into an email. Declining, cancelling or moving viewings, and deleting a listing that has viewings, do not exist at `/v1` yet.

## Deciding without a person [#decide]

By default a person says yes. The office can give a key the right to do it itself: the scope `decide`. Then `POST /v1/proposals/{id}/approve` approves the proposal and `POST /v1/proposals/{id}/reject` rejects it, with nobody reading the message first.

**The risk is the office's.** Mails to customers and inquirers go out without a person having seen them, and an email cannot be taken back. Give `decide` only to a key whose texts you trust.

How it works:

* `decide` needs `approve` and write access to `inquiries`. Only the management of the office switches it on, when the key is created, in the app under Settings, API keys, with a confirmation. No existing key has it, not even one with `approve`. `GET /v1/me` lists it under `key.scopes`.
* Without `decide` the call answers `403` [`insufficient_permissions`](/en/api/errors#insufficient_permissions).
* A key decides only the proposals it created itself, and only replies and follow-ups to an inquiry. Anything else is `403` [`forbidden`](/en/api/errors#forbidden) or, for a foreign proposal, `404`.
* The call runs the same code as the yes in the app: the same checks, the same expiry, the same `409` [`proposal_already_decided`](/en/api/errors#proposal_already_decided) for a decided or lapsed proposal, the same effects. With an `Idempotency-Key` a retry is safe; without one the second decision is a `409`.
* The history, the proposal (`decidedBy`) and, where the message is written into the thread in the house, the message name the key, with its name and id, not the person who created it. If the mail leaves from a mailbox, the key is on the proposal and in the history, and the thread shows the mailbox's mail.
* At most 30 decisions a minute per key, with a burst of 10 ([Limits](/en/api/v1/limits)). The limits of what a yes triggers stay in force.
* An inquiry from outside with no thread in a mailbox of the office has no way for the mail: `409` [`mailbox_not_connected`](/en/api/errors#mailbox_not_connected), and the proposal stays open. A key has no mailbox of its own to fall back on.
* If the mail leaves from a member's mailbox because the thread of the inquiry lives there, it leaves from that mailbox while the proposal names the key.

## In test mode [#in-test-mode]

With a test key nothing goes out, not even after a yes. You can decide the proposal yourself: `POST /v1/proposals/{id}/approve` or `/reject`, without the scope `decide`. The message then stands in the thread as sent, with a note that it was not delivered ([Test mode](/en/api/v1/testmodus)).

## Limits [#limits]

These operations use the bucket for writing ([Limits](/en/api/v1/limits)). A throttled request never runs.
