Client requests

When a client sends a message about a listing, asks to be called, or asks for a viewing, the request lands in the Housera portal inbox. With the leads:read permission, you can read it through the API, with the client’s contact details, and bring it into your CRM.

Who has access

An API key sees the requests the account sees in the portal within the key’s company, plus the account’s requests on listings published outside any company:

the agency owner and administrators see the whole company’s requests;
a branch manager sees their branch’s requests (for a property developer, the requests for its projects);
an agent sees the requests they are handling;
an account without a company sees its own requests.

Requests from another company never appear, even for someone who works in both. While the company is suspended, the key sees only the requests the account is handling, as in the portal. Colleagues’ requests no longer appear, and neither do events about them; they come back after reactivation. When the company closes, the key keeps only the account’s requests from outside the company. For your own key, you tick leads:read yourself in Settings → API. An integrator gets it only if Housera has approved it, and the consent page tells the account that the integrator will receive clients’ contact details. Without this permission, calls to /leads get 403 missing_ability.

List of requests

GET /leads returns requests from oldest to newest, with cursor pagination.

curl "https://housera.ro/api/v1/leads?since=2026-11-01T00:00:00Z&per_page=50" \
  -H "Authorization: Bearer $HOUSERA_KEY" \
  -H "Accept: application/json"

Parameter	What it does
`listing`	Only requests for the listing with this code.
`external_ref`	Only requests for the listing with this ID from your system.
`since`	Only requests received or changed after this point in time (ISO 8601): a new one, one the same client came back to, or one whose status changed in the portal.
`status`	Only requests at this stage: `new`, `contacted`, `viewing`, `offer` or `closed`.
`source`	Only requests that came in on this channel: `message`, `phone`, `viewing_request`, `referral` or `other`.
`agent`	Only the requests held by the colleague with this email. An email that belongs to nobody gets you an empty list.
`office`	Only the requests of the office with this id, the one in the request’s `office.id`.
`complex`	Only the requests of a developer’s project, by the development’s code: those on the development and those on its units.
`q`	Searches like the portal’s search bar: the name, the note, the start of the email and the phone. Write the phone any way you like: `0740 111 222` finds `+40740111222`. The owner, admins and managers also find requests by the name of the colleague who holds them.
`per_page`	How many requests per page, from 1 to 100 (default 50).
`cursor`	The cursor for the next page, taken from `meta.next_cursor` and sent exactly as you received it. Any other value gets `422 pagination_cursor`.

If Housera cannot find the code or ID, you get an empty list. The filters combine with each other and with inbox=true, and a value outside their list (for example status=unassigned) gets 422. since is compared with updated_at, so a request you already imported can show up again. Use its id to tell that you already have it.

One request

GET /leads/{id} returns a single request. For a request the key can’t access, the API returns 404, just as for one that does not exist.

{
  "data": {
    "id": 4182,
    "source": "message",
    "status": "new",
    "listing": { "code": "HEWPUTA8", "external_ref": "CRM-10293" },
    "complex": null,
    "contact": { "name": "Andrei Ionescu", "phone": "+40740123456", "email": "andrei@example.com" },
    "message": "Bună ziua, mai este disponibil apartamentul? Aș putea veni sâmbătă la vizionare.",
    "note": null,
    "price": null,
    "agent": { "name": "Maria Popescu", "email": "maria.popescu@agentia.ro", "display_name": "Maria Popescu" },
    "requests": { "callback_at": null, "viewing_at": "2026-11-02T08:14:03+00:00" },
    "office": { "id": 12, "name": "Tătărași" },
    "inbox": null,
    "created_at": "2026-11-02T08:14:03+00:00",
    "updated_at": "2026-11-02T08:14:03+00:00"
  }
}

Field	What it contains
`source`	How the request came in: `message`, `phone` (call request), `viewing_request`, `referral`, or `other`.
`status`	Where the request stands in the portal: `new`, `contacted`, `viewing`, `offer`, or `closed`.
`listing`	The listing the request is about, with the Housera code and your ID (`external_ref`, `null` if you didn’t set it). `null` for a request not tied to a listing.
`complex`	At a developer, the request’s project, with `code`, `title` and `url`: the development the request came on, or the one the unit is part of. `null` outside a project.
`contact`	The client’s name, phone, and email.
`message`	What the client wrote. `null` if they wrote nothing, for example with a call request.
`note`	The account’s note on the request, as in the portal. For a request sent from the agency’s page, the note starts with the client’s text.
`price`	The amount the client offered, in whole euros. `null` when none is set.
`agent`	Who took the request in the portal: `name` is the account’s name, `email` its email, and `display_name` the approved public name the portal shows next to the request. The two names differ when the colleague has a different public name approved. `email` is `null` when we have no real address for the colleague, for example one who came from a CRM with no email on their team record. `agent` is `null` while the request is waiting in the company’s inbox.
`requests`	When the client last asked to be called (`callback_at`) and to come to a viewing (`viewing_at`), as in the portal. `null` if they never asked. `source` only gives the channel of the first request, so a client who wrote to you and then asked for a call has `source: message` and a `callback_at`.
`office`	The request’s office, with `id` and `name`. The head office is named in the language of the response: “Head office” in English, “Sediu” in Romanian. `null` for a request outside a company.
`inbox`	Only for a request in “To take”: `reason` says why it waits, and `since` when the request came in. `null` while someone holds the request.

The values of inbox.reason are the portal’s:

no_listing: the client wrote from the company’s page, so the request has no listing;
left: the agent who held the request or the listing left the company or was deactivated, and their work went to “To take”;
no_agent: the listing has no active agent.

Working on requests

With the leads:write permission you do through the API what you do with a request in the portal: change its stage, note and amount, delete it, add contacts by hand and take the requests nobody is responsible for yet. The rules are the portal’s, and the change shows up there right away. leads:write works only together with leads:read, because every response carries the client’s contact details. On your own key you tick it in Settings → API. An integrator gets it only if Housera has approved it, and the account accepts it separately on the consent page. A key or connection that only has leads:read can’t write: it gets 403 missing_ability.

Stage, note and contact details

PATCH /leads/{id} changes the fields you send and leaves the others as they are. A field sent as null is cleared, except the name and the stage, which can’t be empty.

curl -X PATCH "https://housera.ro/api/v1/leads/4182" \
  -H "Authorization: Bearer $HOUSERA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "viewing", "note": "Vine sâmbătă la 11.", "price": 91000}'

Field	What it changes
`status`	The stage: `new`, `contacted`, `viewing`, `offer`, or `closed`. Any stage can follow any other.
`note`	The account’s note, up to 500 characters.
`price`	The offered amount, in whole euros.
`name`, `phone`, `email`	The contact details, with the same checks as in the portal. The phone is stored in international format (`+40…`).
`source`	The channel: `message`, `phone`, `viewing_request`, `referral`, or `other`.

The response holds the request with the new values. If another contact of the same client on the same listing already has the phone or email you sent, you get 422 with the lead_duplicate code on /phone. DELETE /leads/{id} deletes the request, as in the portal. The response is 204, and the request disappears from the lists and from GET /leads/{id}. A request the key doesn’t see, a colleague’s or another company’s, gets 404, like one that doesn’t exist.

A contact added by hand

POST /leads adds a contact, like the “Add” button in the portal, with you as the person responsible. Only name is required, and without status the contact starts at the new stage. Send a different Idempotency-Key for each new contact and the same one when you retry a request: within 10 minutes, the same value answers with the contact added the first time, with 200 and the same meta.possible_duplicate, and adds no other. The owner, admins and managers add the contact to the company’s requests. If you want it to stay only in your own requests, send "board": "personal". For an agent, the contact always goes to their own requests, and "board": "firm" gets 403.

Is the contact already there?

Before saving, the portal checks whether you already have the contact: it looks in the same requests (the company’s or yours) for the latest contact with the same phone or exactly the same name. Through the API you run the same check, among the requests the key sees, with POST /leads/duplicate-check, sending name, phone and, optionally, board, as for POST /leads:

curl -X POST "https://housera.ro/api/v1/leads/duplicate-check" \
  -H "Authorization: Bearer $HOUSERA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Andrei Ionescu", "phone": "0740 123 456"}'

If it finds the contact, you get the request in data, as from GET /leads/{id}, and in meta.matched_on what matched: phone, name or both. If not, you get "data": null and an empty meta.matched_on. The check changes nothing and needs the same permissions as adding a contact, leads:read and leads:write. Two people can share a phone, for example an agency’s line, so the check only warns you. You decide whether to add the contact. POST /leads adds it anyway and tells you in meta.possible_duplicate the contact the same check finds, with id and matched_on, or null.

Requests nobody is responsible for

When a company listing has no active agent, or the client writes from the agency’s page, the request goes to “To take” and anyone in the branch can take it. Through the API:

GET /leads?inbox=true returns the requests in “To take” that the account can take. An agent sees only their branch’s, while the owner and admins see all of them. GET /leads/{id} reads them too.
POST /leads/{id}/take gives you the request. If a colleague took it first, you get 409 lead_already_taken. If you already have a contact with the same client, without a listing, the request joins it, as in the portal: the response is your contact, and meta.merged_from is the id of the joined request, which no longer exists.
POST /leads/{id}/assign, with {"agent_email": "colleague@agency.ro"}, hands the request to a colleague on your team. It works for the owner, admins and managers, and the colleague gets the portal’s notification. An email that isn’t a colleague’s on the team gets 422 agent_not_member, and a deactivated colleague 422 agent_deactivated.

Once a request is taken, it shows up in the responsible person’s GET /leads, with agent filled in.

The conversation with the client

When the client writes to you about a listing, the request has a conversation, the same one you see in Messages in the portal. Through the API you read it and reply to the client, as from the portal. Only the account in charge of the listing reads the conversation and replies to the client, as in the portal. An owner or manager who sees an agent’s request gets 403 conversation_not_held on its conversation. A request with no conversation (a call request, a contact added by hand, a message from the agency’s page) returns an empty list.

Messages

GET /leads/{id}/messages returns the messages oldest first, with cursor pagination. With after you get only the messages after one you already have. Reading through the API doesn’t mark messages as read, so it doesn’t hide them from whoever works in the portal.

{
  "data": [
    {
      "id": 90211,
      "direction": "in",
      "author": { "name": "Andrei Ionescu" },
      "body": "Bună ziua, mai este disponibil apartamentul?",
      "kind": null,
      "deleted": false,
      "edited_at": null,
      "read_at": "2026-11-02T08:20:11+00:00",
      "created_at": "2026-11-02T08:14:03+00:00"
    }
  ]
}

Field	What it contains
`direction`	`in` for a message from the client, `out` for one sent from the listing’s side, by you or by a colleague who handled the listing before.
`author`	The author’s name, as the portal’s conversation shows it.
`body`	The text. `null` for a deleted message, which keeps its place in the conversation.
`kind`	`viewing_request` for the message with which the client asked for a viewing, otherwise `null`.
`read_at`	When the other side read the message. `null` until they read it.

Replying

POST /leads/{id}/messages sends a message to the client, as from the portal. The client sees it in the conversation and gets the same notifications as for a message written in the portal.

curl -X POST "https://housera.ro/api/v1/leads/4182/messages" \
  -H "Authorization: Bearer $HOUSERA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2b0e-8a4d-4c3e-9b7a-2d5f1e0c9a11" \
  -d '{"body": "Bună ziua! Da, e disponibil. Vă convine sâmbătă la 11?"}'

The response is 201, with the message. Send a different Idempotency-Key for each new message and the same one when you retry a message: within 10 minutes, a request with the same value returns the message sent the first time, with 200, and sends nothing else. The text has at most 2,000 characters. The reply is refused with 409 when the request has no conversation (no_conversation), when the conversation is read only because the listing or the client’s account was deleted (conversation_closed), and when one side blocked the other (conversation_blocked). Replies through the API and from the portal share the same limit, 20 per minute and 200 per hour per account.

Editing, deleting and reading

PATCH /leads/{id}/messages/{message}, with {"body": "…"}, changes the text of a message you wrote, within the first 15 minutes and while the conversation is open. After 15 minutes you get 409 edit_window_closed. The client sees the message marked as edited.
DELETE /leads/{id}/messages/{message} deletes a message you wrote, at any time. The message stays in the conversation as “Message deleted”, with no text.
A client’s message can’t be edited or deleted: you get 403 message_not_yours.
POST /leads/{id}/messages/read marks the client’s messages as read, as opening the conversation in the portal does. The client isn’t told.

The `lead.message_received` event

When the client writes again in the conversation, the account in charge of the listing gets the lead.message_received event, on its webhook and in GET /events, if it has a key with leads:read. The event has lead_id and message_id, without the message’s text, which you read with GET /leads/{id}/messages?after=…. The client’s first message, the one that opens the conversation, comes as lead.created, or as lead.updated if the client already had a request on the listing, so it doesn’t also produce lead.message_received.

Clients’ messages are personal data, like their contact details. Keep them only as long as you need them to respond to the request.

The `lead.created` event

When a client sends their first request about a listing, you get a lead.created event on your webhook and in GET /events. The event does not include the client’s data. It has lead_id and source, and you read the details with GET /leads/{id}. In GET /events you see it with any key that has leads:read, even without listings:read. Only accounts that see the request in their inbox and have a key with leads:read get the event. From the day we announce to you, a request that lands in “To take” also produces lead.created for whoever may take it, that is, for everyone in the office the portal tells, agents included. A webhook gets it only if it has leads:read behind it. See Webhooks for details.

The `lead.assigned` and `lead.removed` events

From the day we announce to you, you also learn what happens to a request after it arrives. lead.assigned comes when the request has a new holder. by says how: take (someone took it from “To take”), assign (the owner, an admin or a manager gave it to a colleague) or handover (it went to a colleague along with the work of someone who left the company or was deactivated, or with a listing moved to another agent). agent is the new holder and previous_agent the one before, each with name and email; previous_agent is null when the request was waiting in “To take” or when the previous colleague’s account was deleted. Whoever sees the request now gets it. lead.removed comes when the request is no longer yours, with reason:

deleted: the request was deleted, in the portal or through the API;
merged: the request was added to the same client’s request that the colleague who took it already had;
out_of_reach: the request is no longer within your reach, for example a colleague took it from “To take” or you handed it on.

Whoever got the request’s events until then gets it. After lead.removed, GET /leads/{id} answers 404, but the event stays in GET /events. Delete the request from your system, or mark it as out of your reach. Both events have lead_id, like lead.created, and need the leads:read permission. Any webhook that gets lead.created also gets them, without ticking them.

The `lead.updated` event

When the same client comes back to the same listing with a new request, for example asking you to call after they sent a message, the new request is added to the one you already have. No separate request appears, but you get a lead.updated event with the same lead_id. The event’s source is the channel of the new request (phone here), while source in GET /leads/{id} stays the channel of the first one. The event’s created_at is when the new request came in. The request’s updated_at moves to that moment too, so GET /leads?since= returns it again. You also get lead.updated when the client writes again from the company’s page after a colleague took their request, and when a request from “To take” joins, on taking, the contact you already have with the same client. lead.updated goes to the same accounts and webhooks as lead.created and also needs leads:read. On a webhook you set up in Settings → API, you tick it separately.

Clients’ contact details are personal data. Keep them only as long as you need them to respond to the request, and don’t use them for anything else.

Erasing client data

Housera erases a client’s data in two cases, and you must erase it from your system too. When a client deletes their account, their requests stay in the portal without their data: the name is anonymized, and the phone, email, message and note are cleared. The request gets erased: true, and updated_at becomes the time of the deletion, so GET /leads?since= returns it again. You also receive the lead.erased event, with reason: account_deleted, even for a request you already deleted in the portal. A request with no activity for 24 months, or one deleted in the portal more than 30 days ago, is deleted for good. Just before that, you receive lead.erased with reason: retention. After that, GET /leads/{id} returns 404, and the event stays in GET /events for 35 days. lead.erased goes to the same accounts as lead.created and also needs leads:read. Every webhook that receives lead.created receives it too; it does not appear in the webhook’s event list and you do not tick it.

When you receive lead.erased or see a request with erased: true, delete the client’s name, phone, email, message and note for that request from your system. You received the data from Housera, so its erasure on our side applies to you as well (GDPR, Article 17(2) and Article 19).

Get started

Concepts

Guides

Reference

More

Who has access

List of requests

One request

Working on requests

Stage, note and contact details

A contact added by hand

Is the contact already there?

Requests nobody is responsible for

The conversation with the client

Messages

Replying

Editing, deleting and reading

The `lead.message_received` event

The `lead.created` event

The `lead.assigned` and `lead.removed` events

The `lead.updated` event

Erasing client data

Who has access

List of requests

One request

Working on requests

Stage, note and contact details

A contact added by hand

Is the contact already there?

Requests nobody is responsible for

The conversation with the client

Messages

Replying

Editing, deleting and reading

The lead.message_received event

The lead.created event

The lead.assigned and lead.removed events

The lead.updated event

Erasing client data

The `lead.message_received` event

The `lead.created` event

The `lead.assigned` and `lead.removed` events

The `lead.updated` event