List the forms on listings in your API scope (cursor-paginated).

GET

/v1/forms

Returns a cursor-paginated page of the forms on listings the authenticated key may read. Ordered by an immutable (created_at, id) tuple. The optional listingId filter narrows the result to a single listing; an out-of-scope or unknown listingId yields an empty 200 page (never a 404, never disclosure). The listingId filter must be repeated on every page.

Authorizations

• bearerAuth

Parameters

Query Parameters

limit

integer format: int32

default: 50 >= 1 <= 100

Page size. Defaults to 50; values are clamped to the range [1, 100].

cursor

string

An opaque pagination token from a prior page’s nextCursor. Treat as a black box.

listingId

string format: uuid

Optional filter — return only forms on this listing. Out-of-scope/unknown ⇒ empty page.

Responses

200

A page of forms.

A cursor-paginated page of forms.

object

items

required

Array<object>

The public projection of a guest-registration form. A curated, additive-only subset.

object

id

required

The form’s unique id.

string format: uuid

listingId

required

The id of the listing this form belongs to.

string format: uuid

publicId

The form’s public slug.

string

nullable

status

required

The public form status. Additive-only — new values may appear over time. Always handle UNKNOWN as a forward-compatible catch-all for any status this API version does not enumerate.

string

Allowed values: SENT COMPLETED ACCEPTED REJECTED VALIDATED INVALIDATED CHECKED_OUT UNKNOWN

checkInDate

string format: date-time

nullable

checkOutDate

string format: date-time

nullable

numberOfGuests

integer format: int32

nullable

numberOfVehicles

integer format: int32

nullable

numberOfPets

integer format: int32

nullable

createdAt

required

When the form was created (ISO-8601, UTC). The cursor ordering key.

string format: date-time

nextCursor

Opaque token for the next page, or null on the last page.

string

nullable

400

The request was malformed — an invalid cursor (INVALID_CURSOR) or a failed parameter validation (VALIDATION_ERROR, with field-level errors[]).

The single error envelope for every public-surface error response.

object

code

required

A stable, enumerated error code. Branch on this, never on message.

string

Allowed values: UNAUTHENTICATED FORBIDDEN RESOURCE_NOT_FOUND INVALID_CURSOR VALIDATION_ERROR PAYLOAD_TOO_LARGE RATE_LIMITED IDEMPOTENCY_KEY_REUSED

message

required

A human-readable description. May change without a contract break.

string

correlationId

required

A per-response id for support correlation.

string format: uuid

errors

Present only for VALIDATION_ERROR — the field-level validation failures.

Array<object>

One field-level validation failure.

object

field

required

The rejected field or query parameter name.

string

issue

required

What was wrong with it.

string

401

The API key is missing, malformed, revoked, or expired (UNAUTHENTICATED).

The single error envelope for every public-surface error response.

object

code

required

A stable, enumerated error code. Branch on this, never on message.

string

Allowed values: UNAUTHENTICATED FORBIDDEN RESOURCE_NOT_FOUND INVALID_CURSOR VALIDATION_ERROR PAYLOAD_TOO_LARGE RATE_LIMITED IDEMPOTENCY_KEY_REUSED

message

required

A human-readable description. May change without a contract break.

string

correlationId

required

A per-response id for support correlation.

string format: uuid

errors

Present only for VALIDATION_ERROR — the field-level validation failures.

Array<object>

One field-level validation failure.

object

field

required

The rejected field or query parameter name.

string

issue

required

What was wrong with it.

string

429

The per-key rate limit was exceeded (RATE_LIMITED). Retry after the interval in Retry-After.

The single error envelope for every public-surface error response.

object

code

required

A stable, enumerated error code. Branch on this, never on message.

string

Allowed values: UNAUTHENTICATED FORBIDDEN RESOURCE_NOT_FOUND INVALID_CURSOR VALIDATION_ERROR PAYLOAD_TOO_LARGE RATE_LIMITED IDEMPOTENCY_KEY_REUSED

message

required

A human-readable description. May change without a contract break.

string

correlationId

required

A per-response id for support correlation.

string format: uuid

errors

Present only for VALIDATION_ERROR — the field-level validation failures.

Array<object>

One field-level validation failure.

object

field

required

The rejected field or query parameter name.

string

issue

required

What was wrong with it.

string

Headers

Retry-After

integer format: int32

Integer seconds to wait before retrying (RFC 7231 delta-seconds form, always >= 1).