Create a guest-registration form on an in-scope listing.
POST /v1/forms
Creates a form on a listing in your API scope, running the exact same safety pipeline as the in-app flow. Requires a read-write key (a read-only key returns 403). The target listingId must be in scope, or the request returns 404 with no existence disclosure. Creation is idempotent: a retry of the same request — detected by a durable fingerprint of the request body — never creates a duplicate form or re-fires its side effects. Supply an optional Idempotency-Key header to make replays explicit; reusing the same key with a different body returns 422.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Header Parameters
Section titled “Header Parameters ”Optional client-supplied idempotency key. A retry with the same key and the same body replays the original result; the same key with a different body returns 422.
Request Body required
Section titled “Request Body required ”The body for creating a guest-registration form.
object
The in-scope listing the form is created on.
Check-in instant (ISO-8601). Interpreted in UTC, as the in-app flow does.
Check-out instant (ISO-8601, UTC). Must be after checkInDate.
Number of guests on the form.
Optional guest contact email. When present, drives the in-app form-created notification. Write-only — never returned in FormV1.
Responses
Section titled “ Responses ”Idempotent replay — the form created by an earlier identical request.
The public projection of a guest-registration form. A curated, additive-only subset.
object
The form’s unique id.
The id of the listing this form belongs to.
The form’s public slug.
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.
When the form was created (ISO-8601, UTC). The cursor ordering key.
The created form.
The public projection of a guest-registration form. A curated, additive-only subset.
object
The form’s unique id.
The id of the listing this form belongs to.
The form’s public slug.
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.
When the form was created (ISO-8601, UTC). The cursor ordering key.
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
A stable, enumerated error code. Branch on this, never on message.
A human-readable description. May change without a contract break.
A per-response id for support correlation.
Present only for VALIDATION_ERROR — the field-level validation failures.
One field-level validation failure.
object
The rejected field or query parameter name.
What was wrong with it.
The API key is missing, malformed, revoked, or expired (UNAUTHENTICATED).
The single error envelope for every public-surface error response.
object
A stable, enumerated error code. Branch on this, never on message.
A human-readable description. May change without a contract break.
A per-response id for support correlation.
Present only for VALIDATION_ERROR — the field-level validation failures.
One field-level validation failure.
object
The rejected field or query parameter name.
What was wrong with it.
The key is authenticated but not permitted this operation (FORBIDDEN) — e.g. a read-only key on a write.
The single error envelope for every public-surface error response.
object
A stable, enumerated error code. Branch on this, never on message.
A human-readable description. May change without a contract break.
A per-response id for support correlation.
Present only for VALIDATION_ERROR — the field-level validation failures.
One field-level validation failure.
object
The rejected field or query parameter name.
What was wrong with it.
The resource does not exist, or the key has no access to it (RESOURCE_NOT_FOUND). The two cases are indistinguishable — no existence disclosure.
The single error envelope for every public-surface error response.
object
A stable, enumerated error code. Branch on this, never on message.
A human-readable description. May change without a contract break.
A per-response id for support correlation.
Present only for VALIDATION_ERROR — the field-level validation failures.
One field-level validation failure.
object
The rejected field or query parameter name.
What was wrong with it.
The request body exceeded the public-surface size or field-count limit (PAYLOAD_TOO_LARGE).
The single error envelope for every public-surface error response.
object
A stable, enumerated error code. Branch on this, never on message.
A human-readable description. May change without a contract break.
A per-response id for support correlation.
Present only for VALIDATION_ERROR — the field-level validation failures.
One field-level validation failure.
object
The rejected field or query parameter name.
What was wrong with it.
The supplied Idempotency-Key was already used for a request with a different body (IDEMPOTENCY_KEY_REUSED).
The single error envelope for every public-surface error response.
object
A stable, enumerated error code. Branch on this, never on message.
A human-readable description. May change without a contract break.
A per-response id for support correlation.
Present only for VALIDATION_ERROR — the field-level validation failures.
One field-level validation failure.
object
The rejected field or query parameter name.
What was wrong with it.
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
A stable, enumerated error code. Branch on this, never on message.
A human-readable description. May change without a contract break.
A per-response id for support correlation.
Present only for VALIDATION_ERROR — the field-level validation failures.
One field-level validation failure.
object
The rejected field or query parameter name.
What was wrong with it.
Headers
Section titled “Headers ”Integer seconds to wait before retrying (RFC 7231 delta-seconds form, always >= 1).