---
title: "Listing Creation"
url: "https://real-estate-agency.apim.eu/apis/listing-creation/versions/ccce93aa-5880-49f4-849d-af24517f6c76"
---

# Listing Creation

OpenAPI specification document.

```json
{"openapi":"3.0.3","info":{"title":"Listing Creation","version":"1.0.0","description":"Turns structured property data into a finished listing - as a PDF and as a\nweb view - and publishes it to the channels you choose.\n\nA listing always references exactly one property from **Property\nManagement**. Standalone listings without a property are intentionally\nnot supported, so mandatory disclosures and history stay maintained in a\nsingle place.\n\n## Workflow\n\n1. `POST /listings` starts the generation. The response carries `status: \"in_progress\"`.\n2. Once the document is ready, the status changes to `completed`. We recommend\n   subscribing to the `listing.completed` event instead of polling.\n3. `GET /listings/{listingId}/pdf` returns the document.\n4. `POST /listings/{listingId}/publish` puts it live on the chosen channels.\n\n## Mandatory disclosures\n\nBefore publication the API checks the disclosures required by law - most\nimportantly the energy-certificate figures and the commission statement.\nIf something is missing, the API responds with `422` and\n`code: \"mandatory_disclosure_missing\"`.\n","contact":{"name":"API Support - Real Estate Agency","email":"api-support@realestateagency.example"},"license":{"name":"For demonstration purposes only"}},"servers":[{"url":"https://api.realestateagency.example/v1","description":"Production"},{"url":"https://sandbox.api.realestateagency.example/v1","description":"Sandbox - data is reset nightly"}],"tags":[{"name":"Listings","description":"Generate, retrieve and publish"},{"name":"Templates","description":"The agency's design templates"}],"security":[{"apiKey":[]}],"paths":{"/listings":{"get":{"tags":["Listings"],"summary":"List listings","description":"Returns the agency's listings, optionally filtered by property and status.","operationId":"listListings","parameters":[{"name":"property_id","in":"query","description":"Only listings for this property.","schema":{"type":"string","example":"prop_8f2c1a"}},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/ListingStatus"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","description":"Cursor from `page.next_cursor` of the previous response.","schema":{"type":"string"}}],"responses":{"200":{"description":"Results list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}},"page":{"$ref":"#/components/schemas/Page"}}}}}},"401":{"$ref":"#/components/responses/NotAuthenticated"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"tags":["Listings"],"summary":"Create a listing","description":"Starts the generation of a listing from a property and a template.\nProcessing runs asynchronously; the response initially carries\n`status: \"in_progress\"`.\n","operationId":"createListing","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateListingRequest"},"examples":{"standard":{"summary":"Apartment with the standard sections","value":{"property_id":"prop_8f2c1a","template_id":"tpl_classic","language":"en","sections":["location","features","energy","floor_plan","commission"]}},"multilingual":{"summary":"Spanish version for international prospects","value":{"property_id":"prop_8f2c1a","template_id":"tpl_modern","language":"es","sections":["location","features","energy"]}}}}}},"responses":{"202":{"description":"Generation accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Listing"},"example":{"id":"lst_4d9b2e","property_id":"prop_8f2c1a","template_id":"tpl_classic","language":"en","status":"in_progress","created_at":"2026-08-20T09:41:12Z"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/NotAuthenticated"},"403":{"$ref":"#/components/responses/ScopeMissing"},"404":{"description":"Property or template not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/listings/{listingId}":{"parameters":[{"$ref":"#/components/parameters/ListingId"}],"get":{"tags":["Listings"],"summary":"Retrieve a listing","description":"Returns status, metadata and the mandatory-disclosure report.","operationId":"getListing","responses":{"200":{"description":"Listing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Listing"}}}},"401":{"$ref":"#/components/responses/NotAuthenticated"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["Listings"],"summary":"Withdraw a listing","description":"Takes a listing off every channel and marks it `withdrawn`.\nThe document remains available for record-keeping purposes.\n","operationId":"withdrawListing","responses":{"204":{"description":"Withdrawn"},"401":{"$ref":"#/components/responses/NotAuthenticated"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/listings/{listingId}/pdf":{"parameters":[{"$ref":"#/components/parameters/ListingId"}],"get":{"tags":["Listings"],"summary":"Download listing as PDF","description":"Returns the generated document. Only available once `status` is\n`completed` - before that the API responds with `409`.\n","operationId":"getListingPdf","responses":{"200":{"description":"PDF document","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/NotAuthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Generation not finished yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"conflict","message":"The listing is still being generated.","details":[{"field":"status","reason":"in_progress"}]}}}}}}},"/listings/{listingId}/publish":{"parameters":[{"$ref":"#/components/parameters/ListingId"}],"post":{"tags":["Listings"],"summary":"Publish a listing","description":"Puts the listing live on the chosen channels. Mandatory disclosures\nare checked first.\n","operationId":"publishListing","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["channels"],"properties":{"channels":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Channel"}},"scheduled_for":{"type":"string","format":"date-time","description":"Optional time for a later, scheduled publication."}}},"example":{"channels":["portal","website","newsletter"]}}}},"responses":{"200":{"description":"Published, or scheduled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Publication"}}}},"401":{"$ref":"#/components/responses/NotAuthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Mandatory disclosures are missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"energy_certificate":{"summary":"Energy-certificate figures are missing","value":{"code":"mandatory_disclosure_missing","message":"Mandatory disclosures from the energy certificate are missing for publication.","details":[{"field":"energy_certificate.final_energy_demand_kwh","reason":"missing"},{"field":"energy_certificate.valid_until","reason":"expired"}]}},"commission":{"summary":"Buyer share exceeds seller share","value":{"code":"commission_invalid","message":"The buyer's share of the commission may not exceed the seller's share.","details":[{"field":"commission.buyer_percent","reason":"exceeds_seller_share"}]}}}}}}}}},"/templates":{"get":{"tags":["Templates"],"summary":"List templates","description":"The agency's design templates, each with the sections it supports.","operationId":"listTemplates","responses":{"200":{"description":"Templates","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Template"}}}},"example":{"data":[{"id":"tpl_classic","name":"Classic","description":"Understated layout with a large cover photo.","sections":["location","features","energy","floor_plan","commission"]},{"id":"tpl_modern","name":"Modern","description":"Two-column layout with bold typography, for new-build projects.","sections":["location","features","energy"]}]}}}},"401":{"$ref":"#/components/responses/NotAuthenticated"}}}}},"components":{"parameters":{"ListingId":{"name":"listingId","in":"path","required":true,"description":"Identifier of the listing.","schema":{"type":"string","example":"lst_4d9b2e"}}},"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"},"example":{"code":"not_authenticated","message":"The API key is invalid or has been revoked.","details":[]}}}},"ScopeMissing":{"description":"The key is missing a required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"scope_missing","message":"The API key is missing a required scope.","details":[{"field":"listings:write","reason":"not_granted"}]}}}},"NotFound":{"description":"The listing doesn't exist","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":"energy_certificate.final_energy_demand_kwh"},"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":"mandatory_disclosure_missing"},"message":{"type":"string","example":"Mandatory disclosures from the energy certificate are missing for publication."},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"ListingStatus":{"type":"string","description":"Lifecycle of a listing.","enum":["in_progress","completed","published","withdrawn","failed"],"example":"completed"},"Channel":{"type":"string","description":"Publication channel.","enum":["portal","website","newsletter","shop_window"]},"Section":{"type":"string","description":"Content block of the listing.","enum":["location","features","energy","floor_plan","commission","neighborhood","history"]},"CreateListingRequest":{"type":"object","required":["property_id","template_id"],"properties":{"property_id":{"type":"string","description":"Property the listing is generated from.","example":"prop_8f2c1a"},"template_id":{"type":"string","description":"Design template of the agency.","example":"tpl_classic"},"language":{"type":"string","description":"Language of the generated document. Useful when marketing to international buyers.","enum":["en","es","fr","de"],"default":"en"},"sections":{"type":"array","description":"Order and selection of sections. Defaults to the template's sections if omitted.","items":{"$ref":"#/components/schemas/Section"}},"internal_note":{"type":"string","maxLength":500,"description":"Internal remark; does not appear in the document.","example":"Owner prefers viewings starting September 1st."}}},"Listing":{"type":"object","properties":{"id":{"type":"string","example":"lst_4d9b2e"},"property_id":{"type":"string","example":"prop_8f2c1a"},"template_id":{"type":"string","example":"tpl_classic"},"language":{"type":"string","example":"en"},"status":{"$ref":"#/components/schemas/ListingStatus"},"pdf_url":{"type":"string","format":"uri","description":"Only set once `status: completed`. The link is valid for 24 hours.","example":"https://api.realestateagency.example/v1/listings/lst_4d9b2e/pdf"},"pages":{"type":"integer","description":"Page count of the generated document.","example":6},"disclosures":{"$ref":"#/components/schemas/DisclosureReport"},"created_at":{"type":"string","format":"date-time","example":"2026-08-20T09:41:12Z"},"completed_at":{"type":"string","format":"date-time","nullable":true,"example":"2026-08-20T09:41:20Z"}}},"DisclosureReport":{"type":"object","description":"Result of the mandatory-disclosure check.","properties":{"complete":{"type":"boolean","example":false},"missing":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"Publication":{"type":"object","properties":{"listing_id":{"type":"string","example":"lst_4d9b2e"},"status":{"$ref":"#/components/schemas/ListingStatus"},"channels":{"type":"array","items":{"type":"object","properties":{"channel":{"$ref":"#/components/schemas/Channel"},"state":{"type":"string","enum":["live","scheduled","failed"]},"url":{"type":"string","format":"uri"}}}},"published_at":{"type":"string","format":"date-time","example":"2026-08-20T09:44:03Z"}}},"Template":{"type":"object","properties":{"id":{"type":"string","example":"tpl_classic"},"name":{"type":"string","example":"Classic"},"description":{"type":"string","example":"Understated layout with a large cover photo."},"sections":{"type":"array","items":{"$ref":"#/components/schemas/Section"}}}}}}}
```