> ## Documentation Index > Fetch the complete documentation index at: https://api.housera.ro/llms.txt > Use this file to discover all available pages before exploring further. # Cererile clienților > Mesajele, cererile de apel și cererile de vizionare pe care contul le vede în căsuța din portal, cu datele de contact ale clienților, de la cea mai veche, cu paginare prin cursor. Cere dreptul `leads:read`. Poți filtra după anunț (`listing` sau `external_ref`), după dată (`since`) și cu filtrele din portal: etapa (`status`), canalul (`source`), colegul care are cererea (`agent`), punctul de lucru (`office`) și căutarea (`q`). ## OpenAPI ````yaml ro/openapi.json GET /leads openapi: 3.1.2 info: title: Housera API version: 1.0.0 description: >- Publică și gestionează anunțuri imobiliare pe Housera din CRM-ul sau din aplicația ta, cu aceleași reguli ca formularul din portalul Housera. servers: - url: https://staging.housera.ro/api/v1 description: 'Sandbox (staging): date de test, aceleași reguli ca producția.' - url: https://housera.ro/api/v1 description: 'Producție: anunțurile reale de pe housera.ro.' security: - bearer: [] tags: - name: Anunțurile tale - name: Poze - name: Evenimente - name: Vocabular - name: Conectează cu Housera - name: Cererile clienților - name: Firma și echipa - name: Mandatele de comercializare - name: Vizionări - name: Proiecte - name: Parteneriate - name: Cheia API - name: Statistici paths: /leads: get: tags: - Cererile clienților summary: Cererile clienților description: >- Mesajele, cererile de apel și cererile de vizionare pe care contul le vede în căsuța din portal, cu datele de contact ale clienților, de la cea mai veche, cu paginare prin cursor. Cere dreptul `leads:read`. Poți filtra după anunț (`listing` sau `external_ref`), după dată (`since`) și cu filtrele din portal: etapa (`status`), canalul (`source`), colegul care are cererea (`agent`), punctul de lucru (`office`) și căutarea (`q`). operationId: v1.leads.index parameters: - name: listing in: query schema: type: - string - 'null' maxLength: 20 description: Codul public al anunțului (8 caractere). - name: external_ref in: query schema: type: - string - 'null' maxLength: 100 description: >- Id-ul anunțului în sistemul tău, dacă l-ai creat cu `PUT /listings/ref/{ref}`. Îl vede doar o cheie din spațiul în care a fost pus; pentru celelalte chei e `null`. - name: since in: query schema: type: - string - 'null' format: date-time description: >- Doar cererile primite sau schimbate după acest moment (ISO 8601, cu fus orar). Îl folosești la sincronizarea incrementală. - name: inbox in: query schema: type: - string - 'null' enum: - 'true' - 'false' - '1' - '0' - null description: >- `true` pentru cererile din „De preluat”: cele care nu au încă responsabil și pe care contul le poate prelua cu `POST /leads/{lead}/take`. Fără el primești cererile pe care contul le vede deja în portal. - name: status in: query schema: anyOf: - $ref: '#/components/schemas/LeadStatus' - type: 'null' description: >- Doar cererile din această etapă: `new`, `contacted`, `viewing`, `offer` sau `closed`. - name: source in: query schema: anyOf: - $ref: '#/components/schemas/LeadSource' - type: 'null' description: >- Doar cererile venite pe acest canal: `message`, `phone`, `viewing_request`, `referral` sau `other`. - name: agent in: query schema: type: - string - 'null' format: email maxLength: 254 description: >- Doar cererile pe care le are colegul cu acest email. Pentru un email care nu e al nimănui primești o listă goală. - name: office in: query schema: type: - integer - 'null' minimum: 1 description: >- Doar cererile punctului de lucru cu acest id, cel din `office.id` al cererii. - name: q in: query schema: type: - string - 'null' maxLength: 100 description: >- Caută ca bara de căutare din portal: în nume, în notă, la începutul emailului și în telefon, scris oricum (`0740 111 222` găsește `+40740111222`). Titularul, administratorii și managerii găsesc cererile și după numele colegului care le are. - name: complex in: query schema: type: - string - 'null' maxLength: 20 description: >- Codul ansamblului unui proiect de dezvoltator: doar cererile de pe ansamblu și de pe unitățile lui. Un cod necunoscut întoarce o listă goală. - name: per_page in: query schema: type: - integer - 'null' minimum: 1 maximum: 100 description: Câte rezultate pe pagină (implicit 50, maximum 100). - name: cursor in: query schema: type: - string - 'null' description: >- Cursorul paginii următoare, din `meta.next_cursor`, trimis exact cum l-ai primit. Altă valoare primește 422 (`pagination_cursor`). - name: locale in: query required: false schema: type: string enum: - ro - en default: ro example: ro description: >- Limba răspunsului, `ro` sau `en`. Schimbă mesajele erorilor (`title`, `detail`), etichetele și, când anunțul are o traducere aprobată în limba cerută, titlul și descrierea lui. Codurile sunt aceleași în orice limbă. Are întâietate față de `Accept-Language` și de limba contului. responses: '200': content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/LeadApiResource' description: Rezultatul cererii. links: type: object properties: first: type: - string - 'null' description: Adresa primei pagini. last: type: - string - 'null' description: Adresa ultimei pagini (null la paginarea cu cursor). prev: type: - string - 'null' description: Adresa paginii anterioare, sau null. next: type: - string - 'null' description: >- Pagina următoare: adresa ei, sau cursorul de trimis mai departe. Null când nu mai e nimic. required: - first - last - prev - next description: Legăturile de paginare. meta: type: object properties: path: type: - string - 'null' description: Adresa de bază a listei. per_page: type: integer minimum: 0 description: Numărul de rezultate pe pagină. next_cursor: type: - string - 'null' description: >- Cursorul paginii următoare; null când lista s-a terminat. prev_cursor: type: - string - 'null' description: Cursorul paginii anterioare; null pe prima pagină. required: - path - per_page - next_cursor - prev_cursor description: >- Date despre răspuns, în afara rezultatului, de exemplu paginarea unei liste. required: - data - links - meta description: Cererea a reușit. '401': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: Cheia lipsește, e revocată sau a expirat (`unauthenticated`). '403': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: >- Cheia nu are dreptul cerut (`missing_ability`) sau accesul e refuzat (`forbidden`). '422': content: application/problem+json: schema: $ref: '#/components/schemas/ValidationProblem' description: >- Datele nu trec regulile: câte o intrare pe câmp în `errors[]`, cu un `code` stabil. '429': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: >- Prea multe cereri. Reîncearcă după numărul de secunde din `Retry-After`. components: schemas: LeadStatus: type: string enum: - new - contacted - viewing - offer - closed title: LeadStatus LeadSource: type: string enum: - phone - message - viewing_request - referral - other title: LeadSource LeadApiResource: type: object properties: id: type: integer description: >- Id-ul cererii. E același în evenimentele `lead.created` și `lead.updated`. source: type: - string - 'null' enum: - phone - message - viewing_request - referral - other - null description: >- Cum a ajuns cererea: `message` (mesaj), `phone` (cerere de apel), `viewing_request` (cerere de vizionare), `referral` sau `other` (adăugată de mână în portal). E canalul primei cereri: o cerere nouă a aceluiași client pe același anunț vine ca evenimentul `lead.updated`, cu canalul ei în `source`. status: type: string enum: - new - contacted - viewing - offer - closed description: >- Etapa cererii în portal: `new`, `contacted`, `viewing`, `offer` sau `closed`. listing: type: - object - 'null' properties: code: type: string description: Codul public al anunțului. external_ref: type: - string - 'null' description: >- Id-ul anunțului în sistemul tău, dacă l-ai creat cu `PUT /listings/ref/{ref}`. Îl vede doar o cheie din spațiul în care a fost pus; pentru celelalte chei e `null`. required: - code - external_ref description: >- Anunțul pe care a venit cererea; `null` pentru o cerere trimisă de pe pagina agenției sau adăugată de mână. complex: type: - object - 'null' properties: code: type: string description: Codul public al ansamblului. title: type: - string - 'null' description: Titlul ansamblului. url: type: string description: Adresa ansamblului pe Housera. required: - code - title - url description: >- La un dezvoltator, proiectul cererii: ansamblul pe care a venit sau cel din care face parte unitatea, cu `code`, `title` și `url`. `null` în afara unui proiect. contact: type: object properties: name: type: string description: Numele clientului. phone: type: - string - 'null' description: Telefonul clientului (E.164), dacă îl are. email: type: - string - 'null' description: Emailul clientului, dacă îl are. required: - name - phone - email description: Datele de contact ale clientului. message: type: - string - 'null' description: >- Ce a scris clientul: primul lui mesaj pe anunț sau textul trimis de pe pagina agenției. `null` dacă n-a scris nimic, de exemplu la o cerere de apel. erased: type: boolean description: >- `true` când clientul și-a șters contul: numele e anonimizat, iar telefonul, emailul, mesajul și nota sunt `null`. Ștergi datele clientului și din copia ta. note: type: - string - 'null' description: >- Nota contului despre cerere, ca în portal. La o cerere trimisă de pe pagina agenției, nota pornește cu textul clientului. price: type: - integer - 'null' description: >- Suma oferită de client, în euro întregi, ca în portal; `null` dacă nu e trecută. agent: type: - object - 'null' properties: name: type: string description: >- Numele contului agentului. Portalul arată numele din `display_name`. email: type: - string - 'null' description: >- Emailul agentului; `null` când nu avem o adresă reală a lui, de exemplu la un coleg venit dintr-un CRM, fără email în fișa lui. display_name: type: string description: >- Numele public aprobat al agentului, cel pe care îl arată portalul în dreptul cererii. Diferă de `name` când agentul are aprobat un alt nume public. required: - name - email - display_name description: >- Agentul care are cererea în portal; `null` cât timp așteaptă în căsuța firmei să o preia cineva. requests: type: object properties: callback_at: type: - string - 'null' description: >- Ultima cerere de apel a clientului (ISO 8601); `null` dacă n-a cerut să fie sunat. viewing_at: type: - string - 'null' description: >- Ultima cerere de vizionare a clientului (ISO 8601); `null` dacă n-a cerut o vizionare. required: - callback_at - viewing_at description: >- Când a cerut clientul ultima oară să fie sunat și să vină la vizionare, ca în portal. `source` spune doar canalul primei cereri. office: type: - object - 'null' properties: id: type: integer description: >- Id-ul punctului de lucru. Îl trimiți ca `office` în `GET /leads`. name: type: string description: >- Numele punctului de lucru. Sediul are numele „Sediu”, în limba răspunsului. required: - id - name description: >- Punctul de lucru al cererii; `null` pentru o cerere din afara unei firme. inbox: type: - object - 'null' properties: reason: type: string enum: - no_listing - left - no_agent description: >- De ce așteaptă: `no_listing` (clientul a scris de pe pagina firmei), `left` (agentul care avea cererea sau anunțul a plecat din firmă ori a fost dezactivat) sau `no_agent` (anunțul nu are un agent activ). since: type: - string - 'null' description: Momentul în care a venit cererea (ISO 8601), ca în portal. required: - reason - since description: >- De ce așteaptă cererea în „De preluat” și când a venit; `null` cât timp are un responsabil. created_at: type: - string - 'null' description: Momentul cererii (ISO 8601). updated_at: type: - string - 'null' description: Ultima modificare a cererii în portal (ISO 8601). required: - id - source - status - listing - complex - contact - message - erased - note - price - agent - requests - office - inbox - created_at - updated_at title: LeadApiResource Problem: type: object title: Problem properties: type: type: string format: uri description: Adresa tipului de problemă (RFC 9457). title: type: string description: Rezumatul problemei, în limba cererii. status: type: integer description: Codul HTTP. code: type: string description: >- Codul stabil al refuzului, după care tratezi eroarea (lista e în pagina Erori). detail: type: string description: Explicația, în limba cererii. existing: type: object properties: code: type: string description: Codul public al anunțului existent. external_ref: type: - string - 'null' description: >- Id-ul tău pentru anunțul existent, dacă l-ai pus tu cu `PUT /listings/ref/{ref}`. Altfel `null`. required: - code - external_ref description: >- Doar la `409 duplicate_listing`: anunțul pe care îl ai deja pentru aceeași proprietate. required: - type - title - status - code - detail ValidationProblem: type: object title: ValidationProblem properties: type: type: string format: uri description: Adresa tipului de problemă (RFC 9457). title: type: string description: Rezumatul problemei, în limba cererii. status: type: integer description: 'Codul HTTP: `422`.' errors: type: array items: type: object properties: pointer: type: string description: Câmpul la care se referă, ca JSON Pointer (`/features/2`). code: type: string description: Regula încălcată, ca cod stabil (lista e în pagina Erori). detail: type: string description: >- Explicația, în limba cererii. Textul se poate schimba, așa că tratezi eroarea după `code`. required: - pointer - code - detail description: Câte o intrare pentru fiecare câmp care nu trece regulile. required: - type - title - status - errors securitySchemes: bearer: type: http scheme: bearer description: 'Authorization: Bearer ' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.