GUguesty
Owner Statements (only available for accounting add-on users)

List owner statements

Changed on

Returns owner statement metadata with table-parity fields (listings, business models, status, sharing channels, generation date, minimum account balance) and presigned PDF download URLs (valid for 1 hour).

get/owner-statement-api/owner-statements

Request

  • Base URL
    https://open-api.guesty.com/v1
  • URL
    https://open-api.guesty.com/v1/owner-statement-api/owner-statements
  • Auth
    API key in header authorization

Query parameters

skipinteger

Offset: number of matching statements to skip before returning results. Echoed in the response skip field. Defaults to 0.

limitinteger

Requested page size (1–100). Values above the max are clamped. Echoed as the effective page size in the response limit field. Defaults to 25.

ownerIdstring

Filter results to a specific owner by their ID

periodMode'month' | 'year' | 'monthRange' | 'yearRange' | 'fiscalYear' | 'fiscalYearRange'
Example:month

How to interpret period filter fields.

  • When omitted and no period fields are sent: no period filter is applied; statements are returned across all periods (subject to other filters and pagination).
  • When omitted but any period field is sent (e.g. year=2025 without periodMode): the request is rejected with 400 Bad Request (periodMode is required when period fields are provided). There is no implicit mode and period fields are not ignored in that case.
  • When set: only the fields required by that mode are used; other period fields are ignored. Modes:
  • month — requires year + month (e.g. January 2025)
  • year — requires year (full calendar year)
  • monthRange — requires fromYear, fromMonth, toYear, toMonth (start ≤ end)
  • yearRange — requires fromYear + toYear (full years inclusive, fromYear ≤ toYear)
  • fiscalYear — requires fiscalYear (uses account fiscal start month)
  • fiscalYearRange — requires fromFiscalYear + toFiscalYear (fromFiscalYear ≤ toFiscalYear)
yearinteger
Example:2025

Calendar year. Required for periodMode=month and periodMode=year.

monthinteger
Example:1

Calendar month 1–12. Required for periodMode=month.

fromYearinteger
Example:2025

Range start year. Required for periodMode=monthRange and periodMode=yearRange.

fromMonthinteger
Example:1

Range start month 1–12. Required for periodMode=monthRange.

toYearinteger
Example:2025

Range end year. Required for periodMode=monthRange and periodMode=yearRange.

toMonthinteger
Example:3

Range end month 1–12. Required for periodMode=monthRange.

fiscalYearinteger
Example:2025

Fiscal year. Required for periodMode=fiscalYear.

fromFiscalYearinteger
Example:2025

Fiscal range start. Required for periodMode=fiscalYearRange.

toFiscalYearinteger
Example:2026

Fiscal range end. Required for periodMode=fiscalYearRange.

updatedSincestring date-time

Return statements created or updated after this ISO-8601 timestamp. Highly recommended for incremental sync.

statementType'MONTHLY' | 'ANNUAL' | 'ANNUAL_SUMMARY' | 'ANNUAL_SUMMARY_BY_MONTH'

Filter by statement type

statusstring[]

Filter by lifecycle status. Repeat the query param to match any of the given values (e.g. status=APPROVED&status=PENDING).

sharedViastring[]

Filter by sharing channel. Repeat the query param to match statements shared via any given channel (e.g. sharedVia=EMAIL&sharedVia=OWNERS_PORTAL).

listingIdstring[]

Filter to statements covering the given listing ID(s). Repeat the query param for multiple listings.

businessModelIdstring[]

Filter to statements under the given business model ID(s). Repeat the query param for multiple business models.

generatedAtFromstring date-time

Return statements with generatedAt on or after this ISO-8601 timestamp.

generatedAtTostring date-time

Return statements with generatedAt on or before this ISO-8601 timestamp.

Response

Owner statements list

countinteger required

Number of statements in this page (results.length).

limitinteger required

Effective page size applied to this request (requested limit after clamping to the allowed range).

skipinteger required

Offset applied to this request (same value as the skip query parameter).

totalinteger required

Total number of statements matching all applied filters (before pagination). Not limited to the current page.

Example response

{
  "results": [
    {
      "id": "65d76274721ff5dd3055632f",
      "ownerName": "John Doe",
      "ownerId": "5acb0b89a89953001f6c73db",
      "listings": [
        {
          "id": "60b1a2c3d4e5f6789012345",
          "name": "Seaside Villa 3BR"
        }
      ],
      "businessModels": [
        {
          "id": "60b1a2c3d4e5f6789012345",
          "name": "Seaside Villa 3BR"
        }
      ],
      "periodStartDate": "2025-01-01T00:00:00.000Z",
      "periodEndDate": "2025-01-31T00:00:00.000Z",
      "minimumAccountBalance": 500,
      "endingBalance": 5000,
      "dueToOwner": 3000,
      "currency": "USD",
      "sharedVia": [
        "EMAIL",
        "OWNERS_PORTAL"
      ],
      "generatedAt": "2025-02-01T08:14:33.000Z",
      "status": "APPROVED",
      "statementType": "MONTHLY",
      "pdfDownloadUrl": "https://signed.example/statement.pdf"
    }
  ],
  "count": 25,
  "limit": 25,
  "total": 100
}

Changes

  • 3122b8618183Revision changes
    • info

      added the new optional query request parameter businessModelId

    • info

      added the new optional query request parameter generatedAtFrom

    • info

      added the new optional query request parameter generatedAtTo

    • info

      added the new optional query request parameter listingId

    • info

      added the new optional query request parameter sharedVia

    • info

      added the new optional query request parameter status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status