> ## 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. # Adaugă un contact > Un contact adăugat de mână, ca butonul „Adaugă” din cererile tale de pe portal, cu aceleași reguli pentru nume, telefon și email. Contul cheii devine responsabil. Titularul firmei, un administrator sau un manager îl adaugă în cererile firmei, iar `board` cu valoarea `personal` îl lasă în cererile proprii; pentru oricine altcineva, contactul rămâne în cererile proprii. Fără `status`, contactul pornește din etapa `new`. Cere drepturile `leads:read` și `leads:write`. Cu `Idempotency-Key`, o cerere repetată în 10 minute întoarce contactul adăugat prima dată (200), cu același `meta.possible_duplicate`, și nu mai adaugă altul. ## OpenAPI ````yaml ro/openapi.json POST /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: post: tags: - Cererile clienților summary: Adaugă un contact description: >- Un contact adăugat de mână, ca butonul „Adaugă” din cererile tale de pe portal, cu aceleași reguli pentru nume, telefon și email. Contul cheii devine responsabil. Titularul firmei, un administrator sau un manager îl adaugă în cererile firmei, iar `board` cu valoarea `personal` îl lasă în cererile proprii; pentru oricine altcineva, contactul rămâne în cererile proprii. Fără `status`, contactul pornește din etapa `new`. Cere drepturile `leads:read` și `leads:write`. Cu `Idempotency-Key`, o cerere repetată în 10 minute întoarce contactul adăugat prima dată (200), cu același `meta.possible_duplicate`, și nu mai adaugă altul. operationId: v1.leads.store parameters: - name: Idempotency-Key in: header required: false schema: type: string description: >- O valoare unică pentru această creare (de exemplu un UUID). O cerere repetată cu aceeași valoare, în 10 minute, întoarce ce a creat prima, fără să creeze altceva: anunțul la `POST /listings`, contactul la `POST /leads`, mesajul la `POST /leads/{lead}/messages`. La anunțuri și la mesaje contează primele 64 de caractere. - 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. requestBody: required: true content: application/json: schema: type: object properties: name: type: string maxLength: 60 description: Numele. phone: type: - string - 'null' maxLength: 40 description: Telefonul. email: type: - string - 'null' format: email maxLength: 120 description: Emailul clientului, dacă îl ai. source: anyOf: - $ref: '#/components/schemas/LeadSource' - type: 'null' description: >- Cum a ajuns cererea: `message`, `phone` (cerere de apel), `viewing_request`, `referral` sau `other`. Fără el, sursa rămâne necompletată, ca în portal. status: anyOf: - $ref: '#/components/schemas/LeadStatus' - type: 'null' description: Starea. note: type: - string - 'null' maxLength: 500 description: Nota. price: type: - integer - 'null' minimum: 0 maximum: 100000000 description: Prețul. board: type: - string - 'null' enum: - firm - personal - null description: >- Unde ajunge contactul: `firm` (cererile firmei, doar pentru titular, administratori și manageri) sau `personal` (cererile tale). Fără el, contactul ajunge în cererile firmei pentru cine le conduce și în cererile proprii pentru ceilalți. required: - name responses: '200': content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/LeadApiResource' description: Rezultatul cererii. meta: type: object properties: possible_duplicate: anyOf: - type: 'null' - type: object properties: id: type: integer description: Id-ul contactului care pare să fie același om. matched_on: type: string description: 'Ce s-a potrivit: `phone`, `name` sau amândouă.' required: - id - matched_on - type: object properties: id: type: integer description: Id-ul contactului care pare să fie același om. matched_on: type: array items: {} description: 'Ce s-a potrivit: `phone`, `name` sau amândouă.' required: - id - matched_on description: >- Contactul pe care îl găsește verificarea din `POST /leads/duplicate-check`: același telefon sau exact același nume, în aceleași cereri. Contactul nou s-a adăugat oricum. `null` dacă nu există unul. required: - possible_duplicate description: >- Date despre răspuns, în afara rezultatului, de exemplu paginarea unei liste. required: - data - meta description: >- Contactul fusese adăugat deja cu același `Idempotency-Key`. Răspunsul îl conține. '201': content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/LeadApiResource' description: Rezultatul cererii. meta: type: object properties: possible_duplicate: anyOf: - type: 'null' - type: object properties: id: type: integer description: Id-ul contactului care pare să fie același om. matched_on: type: string description: 'Ce s-a potrivit: `phone`, `name` sau amândouă.' required: - id - matched_on - type: object properties: id: type: integer description: Id-ul contactului care pare să fie același om. matched_on: type: array items: {} description: 'Ce s-a potrivit: `phone`, `name` sau amândouă.' required: - id - matched_on description: >- Contactul pe care îl găsește verificarea din `POST /leads/duplicate-check`: același telefon sau exact același nume, în aceleași cereri. Contactul nou s-a adăugat oricum. `null` dacă nu există unul. required: - possible_duplicate description: >- Date despre răspuns, în afara rezultatului, de exemplu paginarea unei liste. required: - data - meta description: >- Contactul a fost adăugat. Răspunsul conține cererea, cu `id`-ul ei, iar `meta.possible_duplicate` contactul care pare să fie același om, dacă există. '400': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: Corpul cererii nu e JSON valid (`malformed_json`). '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 drepturile cerute (`missing_ability`) sau ai cerut cererile firmei fără să le conduci (`forbidden`). '409': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: >- O cerere cu același `Idempotency-Key` e încă în lucru (`idempotency_key_in_use`). Reîncearcă peste câteva secunde. '413': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: Corpul cererii depășește 1 MB (`payload_too_large`). '415': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: >- Corpul cererii nu e declarat ca JSON (`unsupported_media_type`). Trimite-l cu `Content-Type: application/json`. '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`. '503': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: >- Housera a oprit temporar scrierile prin API (`api_writes_paused`). Reîncearcă după numărul de secunde din `Retry-After`. components: schemas: LeadSource: type: string enum: - phone - message - viewing_request - referral - other title: LeadSource LeadStatus: type: string enum: - new - contacted - viewing - offer - closed title: LeadStatus 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.