Listing Description API Reference

Generate AI-powered real estate listing descriptions via our REST API.

Endpoint

POST https://customer-api.listingai.co/v2/create-description

Authentication

Include your API key as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Don't have an API key? Request API access to get started.

Parameters

Send a JSON body with Content-Type: application/json.

Parameter	Type	Required	Description
`address`	String	Yes	Full property address
`transactionType`	String	Yes	`"sale"` or `"rent"`
`propertyType`	String	Yes	See Property Types below
`numberOfBedrooms`	Number	Yes	Number of bedrooms (use 0 if not applicable)
`numberOfBathrooms`	Number	Yes	Number of full bathrooms (use 0 if not applicable). Accepts decimals (e.g. 3.5) — if no `numberOfHalfBathrooms` is provided, a decimal value will be auto-split (3.5 → 3 full + 1 half).
`numberOfHalfBathrooms`	Number	No	Number of half bathrooms. When provided, `numberOfBathrooms` must be a whole number.
`numberOfParkingSpaces`	Number/String	Yes	Number of parking spaces or text description (e.g. "private garage"). Use 0 if not applicable.
`area`	Number	Yes	Interior size of the property
`areaUnit`	String	Yes	Unit of measurement (e.g. `"sqft"`, `"sqm"`)
`additionalDetails`	String	Yes	Additional property details and features to include
`writingStyle`	String	Yes	`"relaxed"`, `"formal"`, `"luxury"`, or `"custom"`
`language`	String	Yes	ISO 639 + ISO 3166-1 code (e.g. `"en-US"`, `"fr-FR"`, `"es-ES"`)
`length`	Number	Yes	Target length (max 2000 for words, 10000 for characters)
`lengthType`	String	Yes	`"words"` or `"characters"`
`tone`	String	Yes	`"casual"`, `"professional"`, or `"creative"`
`complexity`	String	Yes	`"simple"`, `"intermediate"`, or `"advanced"`
`lotSize`	Number	No	Lot size of the property
`lotSizeUnit`	String	No	Unit for lot size (e.g. `"acres"`, `"sqft"`)
`zoning`	String	No	Zoning classification (e.g. `"residential"`)
`areasToFocus`	Array	No	Areas to emphasize (e.g. `["neighborhood", "proximity to parks"]`)
`aboveGroundLevels`	Number	No	Number of above-ground levels/stories. Used for AI context only — not explicitly mentioned in output.
`belowGroundLevels`	Number	No	Number of below-ground levels (e.g. basement). Used for AI context only — not explicitly mentioned in output.
`communityHighlights`	Object	No	Community features in Google Places API format. If not provided, auto-discovered based on `communityHighlightsDiscovery`.
`communityHighlightsDiscovery`	String	No	How to discover nearby amenities: `"point"`, `"disabled"`, `"city"`, or `"property_address"`
`instructions`	Array	No	Array of instruction strings for the AI. See Instructions below.
`dictionaryRules`	Array	No	Word substitution/encouragement rules. See Dictionary Rules below.
`copyWriter`	String	No	AI model instance. See CopyWriter below.

Property Types

Standard values:

house
condo
apartment
townhouse
multi-family
commercial
industrial
farm
vacant (vacant land)
mobile-home
medical-office

You can also provide any custom string up to 30 characters (e.g. "single-family", "duplex", "ranch").

CopyWriter

Choose which AI model generates the description. You can use the model name directly:

Value	Platform	Notes
`claude-opus-4.6`	Anthropic	Most intelligent model. Recommended for best quality.
`claude-sonnet-4.6`	Anthropic	Excellent quality, faster response times.
`gpt-5.4`	OpenAI	Latest OpenAI model with advanced reasoning.
`gpt-5.1`	OpenAI	Fast response times.
`gemini-3.1-pro`	Google	Strong multilingual support.

If no value is provided, defaults to claude-opus-4.6.

Instructions

An array of strings that guide the AI's output. Each instruction is a directive the AI will follow when generating the description.

"instructions": [
  "Always format your output using HTML",
  "Use numerical values for numbers under 10",
  "Do not include copy about the location or community",
  "Incorporate bullet points",
  "Add a title like: New Home for Sale in [city], [state]"
]

Dictionary Rules

An array of rules that control word usage. Two types are supported:

"substitute term" — replaces one term with another
"encourage using the term" — encourages the AI to use a specific term

"dictionaryRules": [
  {
    "type": "substitute term",
    "term": "master bedroom",
    "alternative": "owner's bedroom"
  },
  {
    "type": "encourage using the term",
    "term": "open-concept"
  }
]

Response Format

A successful response returns a JSON object:

{
  "status": "success",
  "response": "Welcome to 123 Main St, a stunning 4-bedroom home..."
}

Error responses return:

{
  "errors": [
    "Address is required",
    "Number of bedrooms is required as an integer value..."
  ]
}

Example Request (curl)

curl -X POST https://customer-api.listingai.co/v2/create-description \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "address": "123 Main St, Austin, TX 78701",
    "transactionType": "sale",
    "propertyType": "house",
    "numberOfBedrooms": 4,
    "numberOfBathrooms": 3,
    "numberOfHalfBathrooms": 1,
    "numberOfParkingSpaces": 2,
    "area": 2500,
    "areaUnit": "sqft",
    "additionalDetails": "Recently renovated, hardwood floors throughout",
    "writingStyle": "relaxed",
    "language": "en-US",
    "length": 250,
    "lengthType": "words",
    "tone": "professional",
    "complexity": "intermediate",
    "communityHighlightsDiscovery": "city",
    "aboveGroundLevels": 2,
    "belowGroundLevels": 1,
    "copyWriter": "claude-opus-4.6"
  }'

Need help integrating? Contact our support team or request API access.