API docs by Redocly

GuardianCheckin Public API (1.0.0)

Download OpenAPI specification:

The GuardianCheckin Public Developer API. A stable, versioned (/v1/) read surface over your listings and forms, decoupled from GuardianCheckin's internal data shapes (Story 37.4, FR-API-20). Authentication is a bearer API key (Authorization: Bearer gck_live_<prefix>.<secret>) on the api.gcheckin.com host. Every request is scoped to the listings the key's owner owns or writer-manages; out-of-scope or unknown ids return 404 with no existence disclosure. Pagination is keyset/cursor based. nextCursor is an opaque token — treat it as a black box and pass it back verbatim as the cursor query parameter to fetch the next page. A null nextCursor means the last page was reached. Cursors are stable over inserts/deletes: a row added during iteration appears only if it sorts after your current position; already-returned pages never shift.

Listings

Read access to the listings in your API scope.

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

Returns a cursor-paginated page of the listings the authenticated key may read (owner or writer access). Ordered by an immutable (created_at, id) tuple. Pass nextCursor back as cursor to page forward. Page size defaults to 50 and is clamped to [1, 100].

Authorizations:
bearerAuth
query Parameters
limit
integer <int32> [ 1 .. 100 ]
Default: 50

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.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Fetch a single listing by id.

Returns a single in-scope listing. An out-of-scope or non-existent id returns 404 with a single non-disclosing message (an out-of-scope listing is indistinguishable from a missing one).

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The listing id (UUID).

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "publicId": "string",
  • "title": "string",
  • "address": "string",
  • "city": "string",
  • "country": "string",
  • "zipCode": "string",
  • "district": "string",
  • "timezone": "string",
  • "active": true,
  • "maxPeopleInListing": 0,
  • "maxVehicles": 0,
  • "allowPets": true,
  • "createdAt": "2019-08-24T14:15:22Z"
}

Forms

Read access to the guest-registration forms on listings in your API scope.

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

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
query Parameters
limit
integer <int32> [ 1 .. 100 ]
Default: 50

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 <uuid>

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

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Fetch a single form by id.

Returns a single in-scope form. An out-of-scope or non-existent id returns 404 with a single non-disclosing message (an out-of-scope form is indistinguishable from a missing one).

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The form id (UUID).

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "listingId": "8c73d933-f7ed-437e-9da1-caac95adc1ae",
  • "publicId": "string",
  • "status": "SENT",
  • "checkInDate": "2019-08-24T14:15:22Z",
  • "checkOutDate": "2019-08-24T14:15:22Z",
  • "numberOfGuests": 0,
  • "numberOfVehicles": 0,
  • "numberOfPets": 0,
  • "createdAt": "2019-08-24T14:15:22Z"
}

FormWrites

Create and update guest-registration forms on listings in your API scope.

Create a guest-registration form on an in-scope listing.

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:
bearerAuth
header Parameters
Idempotency-Key
string <= 255 characters

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 schema: application/json
required
listingId
required
string <uuid>

The in-scope listing the form is created on.

checkInDate
required
string <date-time>

Check-in instant (ISO-8601). Interpreted in UTC, as the in-app flow does.

checkOutDate
required
string <date-time>

Check-out instant (ISO-8601, UTC). Must be after checkInDate.

numberOfGuests
required
integer <int32>

Number of guests on the form.

contactEmail
string or null <email>

Optional guest contact email. When present, drives the in-app form-created notification. Write-only — never returned in FormV1.

Responses

Request samples

Content type
application/json
{
  • "listingId": "8c73d933-f7ed-437e-9da1-caac95adc1ae",
  • "checkInDate": "2019-08-24T14:15:22Z",
  • "checkOutDate": "2019-08-24T14:15:22Z",
  • "numberOfGuests": 0,
  • "contactEmail": "user@example.com"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "listingId": "8c73d933-f7ed-437e-9da1-caac95adc1ae",
  • "publicId": "string",
  • "status": "SENT",
  • "checkInDate": "2019-08-24T14:15:22Z",
  • "checkOutDate": "2019-08-24T14:15:22Z",
  • "numberOfGuests": 0,
  • "numberOfVehicles": 0,
  • "numberOfPets": 0,
  • "createdAt": "2019-08-24T14:15:22Z"
}

Update a guest-registration form in your API scope.

Updates an existing form, running the same safety pipeline as the in-app flow. Requires a read-write key (a read-only key returns 403). The form and the target listingId (a form may be moved to another in-scope listing) must both be in scope, or the request returns 404 with no existence disclosure. PUT targets a specific form id and is therefore naturally idempotent; it carries no Idempotency-Key.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The form id (UUID).

Request Body schema: application/json
required
listingId
required
string <uuid>

The in-scope listing the form belongs to (a PUT may move the form to another in-scope listing).

checkInDate
required
string <date-time>

Check-in instant (ISO-8601, UTC).

checkOutDate
required
string <date-time>

Check-out instant (ISO-8601, UTC). Must be after checkInDate.

numberOfGuests
required
integer <int32>

Number of guests on the form.

contactEmail
string or null <email>

Optional guest contact email. Write-only — never returned in FormV1.

Responses

Request samples

Content type
application/json
{
  • "listingId": "8c73d933-f7ed-437e-9da1-caac95adc1ae",
  • "checkInDate": "2019-08-24T14:15:22Z",
  • "checkOutDate": "2019-08-24T14:15:22Z",
  • "numberOfGuests": 0,
  • "contactEmail": "user@example.com"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "listingId": "8c73d933-f7ed-437e-9da1-caac95adc1ae",
  • "publicId": "string",
  • "status": "SENT",
  • "checkInDate": "2019-08-24T14:15:22Z",
  • "checkOutDate": "2019-08-24T14:15:22Z",
  • "numberOfGuests": 0,
  • "numberOfVehicles": 0,
  • "numberOfPets": 0,
  • "createdAt": "2019-08-24T14:15:22Z"
}