# Descriptions

> Draft a marketing description for a listing from its facts.

Drafts a marketing description for a listing from the facts you send. The text comes back to you; nothing is saved to the listing until you send it with [`PUT /properties/:id`](https://www.fondaro.com/docs/api/properties/crud.md#update-a-listing).

## Draft a description

### `POST /properties/description/generate`

Needs the `properties:write` scope. Every field is optional, but the more facts you send, the more specific the text.

| Field | Type | Notes |
|---|---|---|
| `propertyId` | string | An existing listing. A listing that already has a description is refused |
| `propertyType`, `propertyCategory`, `listingType` | string | Same values as [listing fields](https://www.fondaro.com/docs/api/properties/crud.md#listing-fields) |
| `bedrooms`, `bathrooms` | number | |
| `livingArea`, `plotArea`, `areaUnit` | number, string | |
| `price`, `currency` | number, string | |
| `yearBuilt`, `isNewConstruction` | number, boolean | |
| `city`, `community`, `region`, `provinceState`, `countryCode`, `postalCode` | string | Location wording |
| `addressLine1`, `addressLine2`, `latitude`, `longitude` | string, number | |
| `hasPool`, `hasSeaView`, `hasGarage`, `hasTerrace`, `hasGarden`, `hasAirConditioning`, `hasLift`, `isFurnished` | boolean | Features to mention |
| `energyRatingDetails` | string | |
| `additionalFeatures` | object | Your own key-value facts |
| `imageUrls` | string[] | Tells the writer the listing has photos; the photos themselves are not read |

```bash
curl -X POST https://api.fondaro.com/properties/description/generate \
  -H "Authorization: Bearer fondaro_pk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "propertyType": "house_detached",
    "propertyCategory": "residential",
    "listingType": "sale",
    "bedrooms": 4,
    "bathrooms": 3,
    "city": "Marbella",
    "region": "Costa del Sol",
    "countryCode": "ES",
    "livingArea": 320,
    "plotArea": 800,
    "areaUnit": "sqm",
    "price": 1250000,
    "currency": "EUR",
    "hasPool": true,
    "hasSeaView": true
  }'
```

```json
{
  "description": "A four-bedroom villa in Marbella with sea views and a private pool, set on an 800 sqm plot..."
}
```

Review the draft before you publish it: it is written from your facts and can be wrong where they are incomplete.

## Errors

| Status | When |
|---|---|
| `400` | A field has the wrong type, or `propertyId` names a listing that already has a description |
| `403` | The key lacks `properties:write` (`API_KEY_SCOPE_MISSING`) |
| `500` | The draft could not be written; try again |

Source: https://www.fondaro.com/docs/api/properties/descriptions