---
title: "Leads & Inquiries"
url: "https://real-estate-agency.apim.eu/apis/leads/versions/d1fa19e4-3a7d-4b6b-aac0-9ec016571b4b"
---

# Leads & Inquiries

OpenAPI specification document.

```json
{"openapi":"3.0.3","info":{"title":"Leads & Inquiries","version":"1.0.0","description":"Accepts inquiries about properties, maintains search profiles and matches\nthe two automatically. Each inquiry gets a traceable score, so that\nlimited viewing-appointment slots go to the right leads.\n\nLead data is personal. Every record therefore carries a `retention_until`;\nonce it passes, the record is anonymized overnight. A deletion request is\ncarried out immediately via `POST /leads/{id}/deletion`.\n","contact":{"name":"API Support - Real Estate Agency","email":"api-support@realestateagency.example"}},"servers":[{"url":"https://api.realestateagency.example/v1","description":"Production"},{"url":"https://sandbox.api.realestateagency.example/v1","description":"Sandbox"}],"tags":[{"name":"Leads"},{"name":"Inquiries"},{"name":"Matching"}],"security":[{"apiKey":[]}],"paths":{"/leads":{"get":{"tags":["Leads"],"summary":"List leads","operationId":"listLeads","parameters":[{"name":"search_profile_active","in":"query","schema":{"type":"boolean"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Results list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"page":{"$ref":"#/components/schemas/Page"}}}}}},"401":{"$ref":"#/components/responses/NotAuthenticated"}}},"post":{"tags":["Leads"],"summary":"Create a lead","operationId":"createLead","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadInput"},"example":{"first_name":"Anna","last_name":"Bergmann","email":"a.bergmann@example.org","phone":"+1 217 555 0142","consent":{"purpose":"property_referral","granted_at":"2026-08-18T10:22:00Z"},"search_profile":{"type":["apartment"],"locations":["Springfield"],"rooms_min":3,"purchase_price_max_eur":700000}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lead"}}}},"400":{"$ref":"#/components/responses/ValidationError"}}}},"/leads/{leadId}":{"parameters":[{"name":"leadId","in":"path","required":true,"schema":{"type":"string","example":"lead_71ab"}}],"get":{"tags":["Leads"],"summary":"Retrieve a lead","operationId":"getLead","responses":{"200":{"description":"Lead","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lead"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/leads/{leadId}/deletion":{"parameters":[{"name":"leadId","in":"path","required":true,"schema":{"type":"string","example":"lead_71ab"}}],"post":{"tags":["Leads"],"summary":"Request deletion","description":"Carries out a data subject's rights request immediately. Personal\nfields are permanently removed; activity that must be retained for\ntax purposes remains pseudonymized.\n","operationId":"requestLeadDeletion","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","enum":["data_subject_request","retention_expired","duplicate"]},"source":{"type":"string","example":"email dated 2026-08-18"}}}}}},"responses":{"202":{"description":"Deletion initiated","content":{"application/json":{"schema":{"type":"object","properties":{"lead_id":{"type":"string"},"anonymized_at":{"type":"string","format":"date-time"}}}}}}}}},"/inquiries":{"get":{"tags":["Inquiries"],"summary":"List inquiries","operationId":"listInquiries","parameters":[{"name":"property_id","in":"query","schema":{"type":"string","example":"prop_8f2c1a"}},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/InquiryStatus"}}],"responses":{"200":{"description":"Results list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Inquiry"}},"page":{"$ref":"#/components/schemas/Page"}}}}}}}},"post":{"tags":["Inquiries"],"summary":"Record an inquiry","description":"Typically called from the contact form on the agency's own website.","operationId":"createInquiry","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["property_id","lead_id"],"properties":{"property_id":{"type":"string","example":"prop_8f2c1a"},"lead_id":{"type":"string","example":"lead_71ab"},"message":{"type":"string","maxLength":2000},"channel":{"type":"string","enum":["website","portal","phone","trade_fair"]}}}}}},"responses":{"201":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Inquiry"}}}}}}},"/inquiries/{inquiryId}/score":{"parameters":[{"name":"inquiryId","in":"path","required":true,"schema":{"type":"string","example":"inq_5c02"}}],"get":{"tags":["Matching"],"summary":"Retrieve an inquiry's score","description":"Shows how well the search profile and the property match - with the\nindividual criteria, so the rating stays traceable.\n","operationId":"getInquiryScore","responses":{"200":{"description":"Score","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Score"},"example":{"inquiry_id":"inq_5c02","points":82,"rating":"high","criteria":[{"criterion":"purchase_price","met":true,"weight":30},{"criterion":"room_count","met":true,"weight":25},{"criterion":"location","met":true,"weight":20},{"criterion":"financing_proof","met":false,"weight":25}]}}}}}}},"/matching/properties/{propertyId}":{"parameters":[{"name":"propertyId","in":"path","required":true,"schema":{"type":"string","example":"prop_8f2c1a"}}],"get":{"tags":["Matching"],"summary":"Matching leads for a property","description":"Returns leads with a matching search profile, sorted descending by score.","operationId":"matchLeadsForProperty","parameters":[{"name":"min_points","in":"query","schema":{"type":"integer","minimum":0,"maximum":100,"default":60}}],"responses":{"200":{"description":"Results","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Score"}}}}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"apikey","description":"Every call carries an API key in the `apikey` header. You generate the\nkey in the Real Estate portal under \"My Apps\"; it's shown exactly once.\n\nEach key has the scopes it's allowed to use attached to it. If one is\nmissing, the API responds with `403` and `code: \"scope_missing\"`; the\nmissing scope is in `details[].field`.\n"}},"responses":{"NotAuthenticated":{"description":"Key is missing, revoked or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"The request doesn't match the schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Rate limit reached","headers":{"Retry-After":{"schema":{"type":"integer","example":12}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Page":{"type":"object","description":"Cursor-based pagination.","properties":{"count":{"type":"integer","example":25},"total":{"type":"integer","example":138},"next_cursor":{"type":"string","nullable":true,"example":"eyJzIjoyNX0"}}},"ErrorDetail":{"type":"object","properties":{"field":{"type":"string","example":"consent.purpose"},"reason":{"type":"string","example":"missing"}}},"Error":{"type":"object","description":"Uniform error format across all Real Estate Agency APIs.","required":["code","message"],"properties":{"code":{"type":"string","example":"validation_failed"},"message":{"type":"string","example":"Consent is required to create a lead."},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"InquiryStatus":{"type":"string","enum":["new","scored","invited","declined","closed"],"example":"scored"},"Consent":{"type":"object","description":"Record of consent under applicable data protection law.","required":["purpose","granted_at"],"properties":{"purpose":{"type":"string","enum":["property_referral","newsletter"]},"granted_at":{"type":"string","format":"date-time","example":"2026-08-18T10:22:00Z"},"revoked_at":{"type":"string","format":"date-time","nullable":true,"example":null}}},"SearchProfile":{"type":"object","properties":{"type":{"type":"array","items":{"type":"string","enum":["apartment","house","land","commercial"]}},"locations":{"type":"array","items":{"type":"string","example":"Springfield"}},"rooms_min":{"type":"number","format":"float","example":3},"living_area_min_sqm":{"type":"number","format":"float","example":75},"purchase_price_max_eur":{"type":"integer","example":700000},"cold_rent_max_eur":{"type":"integer","example":1600},"financing_proof":{"type":"boolean","example":false}}},"LeadInput":{"type":"object","required":["last_name","email","consent"],"properties":{"first_name":{"type":"string","example":"Anna"},"last_name":{"type":"string","example":"Bergmann"},"email":{"type":"string","format":"email","example":"a.bergmann@example.org"},"phone":{"type":"string","example":"+1 217 555 0142"},"consent":{"$ref":"#/components/schemas/Consent"},"search_profile":{"$ref":"#/components/schemas/SearchProfile"}}},"Lead":{"allOf":[{"$ref":"#/components/schemas/LeadInput"},{"type":"object","properties":{"id":{"type":"string","example":"lead_71ab"},"retention_until":{"type":"string","format":"date","description":"Automatically set deletion deadline. Anonymized after it passes.","example":"2027-02-18"},"created_at":{"type":"string","format":"date-time","example":"2026-08-18T10:22:04Z"}}}]},"Inquiry":{"type":"object","properties":{"id":{"type":"string","example":"inq_5c02"},"property_id":{"type":"string","example":"prop_8f2c1a"},"lead_id":{"type":"string","example":"lead_71ab"},"status":{"$ref":"#/components/schemas/InquiryStatus"},"channel":{"type":"string","example":"website"},"message":{"type":"string","example":"Hello, is the apartment still available? We would like to view it."},"received_at":{"type":"string","format":"date-time","example":"2026-08-19T17:05:31Z"}}},"Criterion":{"type":"object","properties":{"criterion":{"type":"string","example":"purchase_price"},"met":{"type":"boolean","example":true},"weight":{"type":"integer","example":30}}},"Score":{"type":"object","properties":{"inquiry_id":{"type":"string","example":"inq_5c02"},"lead_id":{"type":"string","example":"lead_71ab"},"points":{"type":"integer","minimum":0,"maximum":100,"example":82},"rating":{"type":"string","enum":["low","medium","high"]},"criteria":{"type":"array","items":{"$ref":"#/components/schemas/Criterion"}}}}}}}
```