Free setup on annual plans

Sign up today!
Book a Demo

Place descriptions

Home

> API Reference >

Endpoints >

Place descriptions

API Reference: Place descriptions endpoints

The Place descriptions APIs manage structured condition-report files: reports, rooms, room photos, transcript-to-HTML transformation, DOCX export and tokenized photo delivery.

Current endpoints

Reports

Use this group for place-description workflows that collect room transcripts and photos, transform room notes into clean HTML, and export a complete DOCX report. Protected AnswerPal API endpoints use JWT Bearer authentication with the TicketAccess policy and require the SchedulesOfCondition subscription feature. Tokenized photo downloads are the public exception.

  • GET /api/PlaceDescriptionReports – Bearer JWT (TicketAccess)
    List reports for the current customer. Supports pagination through pageNumber and pageSize, optional sorting through sortBy/sortOrder, and search across address, case number and client names.
  • POST /api/PlaceDescriptionReports – Bearer JWT (TicketAccess)
    Create a report for the current customer and representative. Document and topic references must belong to the current customer.
  • GET /api/PlaceDescriptionReports/{id} – Bearer JWT (TicketAccess)
    Return one report with its rooms ordered by sortOrder and room ID.
  • PUT /api/PlaceDescriptionReports/{id} – Bearer JWT (TicketAccess)
    Update report metadata, document references, transform topic and hero photo token.
  • DELETE /api/PlaceDescriptionReports/{id} – Bearer JWT (TicketAccess)
    Delete a report owned by the current customer. Returns 204 No Content when deleted.
  • GET /api/PlaceDescriptionReports/{id}/export/docx – Bearer JWT (TicketAccess)
    Generate a DOCX file from the report template. Query options control photo placement and whether photos are included.

Report examples

List reports

GET /api/PlaceDescriptionReports?pageNumber=1&pageSize=10&search=Brussels
Authorization: Bearer {token}

200 OK
{
  "items": [
    {
      "placeDescriptionReportID": 123,
      "caseNumber": "PD-2026-001",
      "clientNames": "Example client",
      "address": "Example street 1",
      "dateCreatedUtc": "2026-06-05T09:30:00Z"
    }
  ],
  "totalCount": 1,
  "totalPages": 1
}

Create report

POST /api/PlaceDescriptionReports
Authorization: Bearer {token}
Content-Type: application/json

{
  "clientNames": "Example client",
  "caseNumber": "PD-2026-001",
  "description": "Move-in condition report",
  "landlords": "Example landlord",
  "tenants": "Example tenant",
  "address": "Example street 1",
  "reportDate": "2026-06-05",
  "lexiconDocumentID": 45,
  "instructionsDocumentID": 46,
  "transformTopicID": 12
}

Report fields

Report create/update body

  • clientNames
    Optional client names, max 512 characters. Included in search.
  • caseNumber
    Optional case or file number, max 255 characters. Used as the DOCX filename when present.
  • description
    Optional free-text report description. Also fills DOCX template placeholders.
  • landlords, tenants
    Optional party names, each max 512 characters.
  • address
    Optional address, max 512 characters. Included in search and DOCX placeholders.
  • reportDate
    Optional date used in report metadata and DOCX output.
  • lexiconDocumentID, instructionsDocumentID
    Optional document IDs. Both must belong to the current customer. The lexicon document can be used by transformation; instructions are stored on the report.
  • transformTopicID
    Optional topic ID for transcript transformation. If omitted, the service tries the customer topic named Place description Room.
  • heroPhotoAccessToken
    Optional string token pointing to the photo used as the report hero image in DOCX export.

Report read/detail response

  • placeDescriptionReportID, customerID
    Report identity and owner.
  • createdByCustomerRepID, customerRepID
    Representative identity recorded on create.
  • dateCreatedUtc, dateUpdatedUtc
    Audit timestamps.
  • rooms
    Only on detail responses. Contains room DTOs ordered by sortOrder and room ID.

DOCX export query

  • photoPlacement
    Optional. Accepted values include perRoom, per-room, atEnd and at-end. Default is perRoom.
  • includePhotos
    Optional boolean. Default is true.
  • excludeHeroPhoto
    Optional boolean. Default is true so the hero photo is not duplicated in the room photo sections.

DOCX export

GET /api/PlaceDescriptionReports/{id}/export/docx returns application/vnd.openxmlformats-officedocument.wordprocessingml.document. The filename is based on caseNumber when available, otherwise PlaceDescription-{id}.docx.

Access and behavior

Authentication and feature access

  • Protected endpoints
    Reports, rooms and room-photo management use TicketAccess policy and SchedulesOfCondition feature access.
  • Public image delivery
    GET /api/PlaceDescriptionPhotos/{accessToken:guid} is Public. Access is controlled by the GUID token in the URL.

Ownership and validation

  • Customer scoping
    All protected reads and writes are scoped to the customer ID from the authenticated token. Missing or foreign reports, rooms and photos return 404.
  • Report references
    Document IDs and transform topic IDs must belong to the current customer, otherwise the API returns 400.
  • DOCX template
    DOCX export returns 404 for a missing report and 500 if the server-side DOCX template is missing.

AI transformation

  • Prompt sources
    Transformation combines topic prompt documents, the optional lexicon document, room name and transcriptRaw. Topic documents with SpecialTopic = All are excluded.
  • OpenAI requirements
    The customer must have an OpenAI API key and an active Email-compatible model. Photo prompts additionally require image input support.
  • Generated output
    The generated HTML is stored on the room as transcriptHtml and is used by DOCX export when available.
GET /api/PlaceDescriptionReports?pageNumber=1&pageSize=10&search=Brussels
Authorization: Bearer {token}

200 OK
{
  "items": [
    {
      "placeDescriptionReportID": 123,
      "caseNumber": "PD-2026-001",
      "clientNames": "Example client",
      "address": "Example street 1",
      "dateCreatedUtc": "2026-06-05T09:30:00Z"
    }
  ],
  "totalCount": 1,
  "totalPages": 1
}
POST /api/PlaceDescriptionReports
Authorization: Bearer {token}
Content-Type: application/json

{
  "clientNames": "Example client",
  "caseNumber": "PD-2026-001",
  "description": "Move-in condition report",
  "landlords": "Example landlord",
  "tenants": "Example tenant",
  "address": "Example street 1",
  "reportDate": "2026-06-05",
  "lexiconDocumentID": 45,
  "instructionsDocumentID": 46,
  "transformTopicID": 12
}
POST /api/PlaceDescriptionRooms/456/transform
Authorization: Bearer {token}
Content-Type: application/json

{
  "topicId": 12,
  "includePhotosInPrompt": true,
  "overrideModelId": 7,
  "force": true
}
POST /api/PlaceDescriptionRooms/456/photos
Authorization: Bearer {token}
Content-Type: multipart/form-data

files: kitchen-1.jpg
files: kitchen-2.webp
PUT /api/PlaceDescriptionRooms/456/photos/reorder
Authorization: Bearer {token}
Content-Type: application/json

{
  "photoIds": [901, 902, 903]
}

Rooms and transformation

Room endpoints store raw transcript notes, generated HTML and per-report ordering.

  • GET /api/PlaceDescriptionReports/{reportId}/rooms – Bearer JWT (TicketAccess)
    List rooms for a report owned by the current customer. Rooms are ordered by sortOrder, then room ID.
  • POST /api/PlaceDescriptionReports/{reportId}/rooms – Bearer JWT (TicketAccess)
    Create a room under a report. If sortOrder is omitted, the next sort order is assigned.
  • PUT /api/PlaceDescriptionRooms/{roomId} – Bearer JWT (TicketAccess)
    Update room name, ordering and transcript fields.
  • DELETE /api/PlaceDescriptionRooms/{roomId} – Bearer JWT (TicketAccess)
    Delete a room owned by the current customer.
  • POST /api/PlaceDescriptionRooms/{roomId}/transform – Bearer JWT (TicketAccess)
    Transform transcriptRaw and optional room photos into clean semantic HTML using the customer OpenAI configuration, topic documents and report lexicon.

Transform room example

POST /api/PlaceDescriptionRooms/456/transform
Authorization: Bearer {token}
Content-Type: application/json

{
  "topicId": 12,
  "includePhotosInPrompt": true,
  "overrideModelId": 7,
  "force": true
}

Room fields

Room create/update body

  • name
    Optional room name, max 255 characters.
  • sortOrder
    Optional order within the report. Create assigns the next order when omitted.
  • transcriptRaw
    Optional raw transcript or notes. Transformation reads this value.
  • transcriptHtml
    Optional HTML transcript. Transformation overwrites this with generated clean HTML.

Transform request body

  • topicId
    Optional transform topic override. It must belong to the current customer. If omitted, the report topic or default topic is used.
  • includePhotosInPrompt
    When true, room photos are included in the OpenAI prompt. The selected model must support image input.
  • overrideModelId
    Optional active model override. It must be shared or customer-owned and compatible with the Email usage slot.
  • force
    Accepted by the DTO for clients that need an explicit transform flag. The current endpoint transforms when called.

Transform result

  • roomId
    Transformed room ID.
  • transcriptHtml
    Generated HTML output. The service instructs the model to return HTML only. Review markers become highlighted spans.
  • lastTransformedAtUtc
    UTC timestamp written after a successful transformation.
  • modelIdUsed
    Model ID used for the OpenAI Responses call.

Photos

Photo endpoints

  • GET /api/PlaceDescriptionRooms/{roomId}/photos – Bearer JWT (TicketAccess)
    List photos for one room. Response rows include filename, content type, access token, sort order and dimensions.
  • POST /api/PlaceDescriptionRooms/{roomId}/photos – Bearer JWT (TicketAccess)
    Upload one or more room photos as multipart form field files. The API accepts JPEG, PNG and WebP images.
  • PUT /api/PlaceDescriptionRooms/{roomId}/photos/reorder – Bearer JWT (TicketAccess)
    Replace the ordering for all photos in a room with a complete photoIds list.
  • DELETE /api/PlaceDescriptionRoomPhotos/{photoId} – Bearer JWT (TicketAccess)
    Delete one room photo owned by the current customer.
  • GET /api/PlaceDescriptionPhotos/{accessToken:guid} – Public tokenized download
    Download stored image bytes using the photo access token. The response uses the stored content type or application/octet-stream.

Photo fields and upload rules

Photo upload rules

  • files
    Multipart form field containing one or more image files. Empty requests return 400.
  • Content types
    Allowed content types are image/jpeg, image/png and image/webp.
  • Size and dimensions
    Request size limit is 25 MB. Each processed file must be non-empty, at most 5 MB, with long side <= 2048 px and short side <= 768 px.
  • Ordering
    Uploaded photos are appended after the current highest sortOrder.

Photo read response

  • placeDescriptionRoomPhotoID, placeDescriptionRoomID
    Photo and room identity.
  • fileName, contentType
    Stored filename and MIME type.
  • accessToken
    GUID token for /api/PlaceDescriptionPhotos/{accessToken:guid}.
  • sortOrder, widthPx, heightPx
    Display/order metadata extracted from the uploaded image.
  • dateCreatedUtc
    Photo creation timestamp.

Reorder body

  • photoIds
    Required list of photo IDs. It must contain every current photo for the room exactly once; partial or mismatched lists return 400.

Related APIs: Documents manage the lexicon and instructions documents, Topics manage transform prompt documents, and File/Tickets cover the broader support workflow outside place-description reporting.

Only GET /api/PlaceDescriptionPhotos/{accessToken:guid} is anonymous. All report, room, photo-management, transform and export routes require JWT Bearer authentication with TicketAccess.

The endpoint uses topicId from the request when provided, otherwise the report transformTopicID, otherwise the customer topic named Place description Room. The topic must belong to the current customer.

photoPlacement controls whether photos appear per room or at the end. includePhotos defaults to true and excludeHeroPhoto defaults to true.

Table of Contents

AnswerPal: AI-powered customer service solutions to elevate your support and communication effortlessly.

Quick Links

Contact

For all support, sales, and partnership inquiries, email us at info@answerpal.eu

AnswerPal
Bisschoppenhoflaan 380
2100 Antwerp
Belgium

+32.36416685

BE 0862.692.858

Social Icons