Good To Book
API docs by Redocly

Guest Check API (1.8.0)

Download OpenAPI specification:

Support: api-support@goodtobook.com URL: https://goodtobook.com/contact

Introduction

This document describes how to create and retrieve Good To Book guest incident reports through API calls.

The API is accessed over HTTP and is RESTful. It has predictable resource URLs and it returns HTTP response codes to indicate errors. It accepts and returns JSON in the HTTP body.

Getting started

The API is intended for use by property management software providers that are integrating Good To Book guest incident reports into their booking system. To get started, you must register your application by contacting api-support@goodtobook.com.

Once registered, you'll be provided with a client ID and secret, allowing you to generate credentials on behalf of Good To Book customers by making requests to the OAuth server.

Authentication

The API uses OAuth2 flows to authenticate requests from your application using temporary credentials.

OAuth

To access the API an access token must be retrieved from the OAuth server using one of two OAuth2 flows. The flow you use will be determined by the agreement made with Good To Book when you register your application.

  • The Authorization Code flow prompts a Good To Book customer connect their account by logging in with their user name and password, after which an access token can be retrieved to authenticate API requests on their behalf.
  • The Client Credentials flow authenticates the integrating application directly. When this flow is used, each user must be registered with the API as an external account before accessing other endpoints.

The access token must be provided in the head of every request made to the API. When the access token expires, a new one must be requested to continue using the API.

Headers should be provided in the following format:

Header name Format Flows
Authorization Bearer <token> All flows
Account-ID <id>:<external-id> Client Credentials only

The table below lists scopes available to authenticated users of the API. When requesing access tokens, the application must specify which scopes it will be using when accessing the API.

Security Scheme Type: OAuth2
Flow type: authorizationCode
Authorization URL: /v1/oauth/authorize
Token URL: /v1/oauth/token
Scopes:
  • incident:read -

    View incident reports

  • incident:write -

    Create incident reports

  • notification:subscribe -

    Manage notification subscriptions

  • notification:consume -

    View notifications

Flow type: clientCredentials
Token URL: /v1/oauth/token
Scopes:
  • incident:read -

    View incident reports

  • incident:write -

    Create incident reports

  • account:read -

    View external user accounts

  • account:write -

    Create external user accounts

If an API client attepts to use a scope that is not compatible with its security scheme, or one that has not been granted, requests made to endpoints requiring the scope will return a 403 Forbidden error response.

Concepts

Formats

Timestamps

Times and dates are formatted according to ISO 8601.

When submitting timestamp properties to the API, you must indicate the timezone that the timestamp relates to. The timezone should be specified by appending a timezone designator to the timestamp. This can be one of:

  • The timezone offset, eg +10:00 for Australia/Brisbane
  • Z for UTC

Timestamps returned by the API are always in UTC.

Country codes

Country names are formatted as two-character codes according to ISO 3166-1 alpha-2. For example AU for Australia or NZ for New Zealand.

Filter queries

Some endpoints allow you to refine the response data by providing filter expressions as query parameters.

A filter consists of a field name supplied as a query parameter key, and a filter expression with an operator and values as the parameter value. Filterable fields are listed in the query parameters for each endpoint, along with the supported operators for each field.

Operator Expression syntax Behaviour
Equal eq:<value> Exact match
Like like:<value> Partial string match
Range range:<min>,<max> Match between two values

When multiple filters are specified in a single request, they will be combined with a logical AND operation.

Pagination

API endpoints that return many resources may be paginated to restrict the size of the response. The API uses cursor pagination, which means that each result page provides a key to use to get the next page.

There is no way to jump to a specific page without first fetching every previous page. Currently there is no way to navigate to a previous page.

Paginated endpoints will return a next property in the response body. This is the cursor for the next page of resources. If the cursor is not null, there are more pages that can be fetched. To get the next page, make the same request again, including the cursor as the value for the next query parameter.

By default, paginated responses will include a maximum of 20 resources. You can set a different page size in the limit query parameter.

The maximum page size may change at any time, and setting an arbitrarily large limit will not guarantee that you'll recieve all resources in a single page.

Errors

Every response from the API uses the same basic shape. The HTTP response code provides the most basic information on the outcome of the request. The response body contains the properties status and message, which provide more specific details in computer- and human-readable formats respectively.

An error is indicated by a HTTP response status of 400 or above. The response body will contain an error property, which may provide more details on what went wrong.

Each type of error has a unique status value. Often this will correspond to the message of a standard HTTP response code, however some errors send a more specific status:

Status Reason
subscription_required The account doesn't have an active Good To Book subscription
incomplete_account The account is missing required properties, such as business name and address

Guest types

When submitting an incident report to the API you must provide details of the people who were involved. You can choose to include details people staying or travelling with together, even if they weren't directly involved in any offences. This can help other users of the API with identifying rogue guests in the future.

Person type Description
offender A person directly involved in causing an offence during the incident
associate A person travelling or staying with others involved in the incident

A person that is marked as offender will be identified as a rogue guest to users of the API, who will likely be advised against accepting future bookings from that person. When submitting incident reports, users of the API should ensure the data they provide is accurate.

OAuth

The following endpoints must be implemented in any application before users will be able to access resources provided by the API.

The Authorizaton Code flow involves a two-step process, where a user is first authorised, creating a temporary auth code, then the code is then exchanged for an access token that can be used to make requests to the API. The access token is short-lived and it must be refreshed when it expires.

Alternatively, if using the Client Credentials flow, an access token may be retrieved directly without first authorising a specific user.

For more details on the flows see Authentication.

Authorise a user

This endpoint allows a user to authorise your application to get API credentials on their behalf. The user must be directed to the endpoint URL in a browser, where they'll be prompted to log into their Good to Book account. Once logged in, they'll be redirected to your application's registered redirect URL.

The auth code will be provided in the code query parameter of the redirect request's URL. This code should be used to request an acess token using the OAuth auth code grant. If provided in the authorize request, the redirect will also include a state query parameter, which should be compared with the original value to prevent request forgery.

query Parameters
client_id
required
string

Your application's client ID

response_type
required
string
Value: "code"
scope
required
string <scope>
Example: scope=incident:read incident:write

A space-delimited list of scopes that the application is requesting access to. See Authentication for available scopes

Although this property is not strictly required by the server, the default scope returned when it is omitted cannot be used to access any API resources

state
string

A client-generated CSRF token for identifying and validating the response. This value will be passed back with the auth code (see redirect response below)

Responses

Get an access token

This endpoint allows your application to fetch temporary credentials in the form of an access token using different OAuth2 grant types. The way the grant is described and OAuth client ID and secret (credentials) are passed depends on the grant type:

Grant type Body type Credentials
Authorization Code application/json Body
Refresh Token application/json Body
Client Credentials application/x-www-form-urlencoded Header

Refer to request samples for the format of each grant type's body data.

This endpoint requires that you send your application's client secret, which should never be revealed publicly. If you need to do authentication with the API from public frontend code (including native mobile apps) you should use the OAuth2 PKCE flow instead.

header Parameters
Authorization
string
Example: Basic dFNHb1BsZj1BqWWRQc...FNjN3h3WDk1VUNOCg==

Provide client credentials as base64-encoded <client-id>:<client-secret> basic auth string

Request Body schema:
required
grant_type
required
string
Enum: "authorization_code" "refresh_token"

The grant type being used

code
string

The code returned from the authorize endpoint. Required for the "authorization_code" grant type

refresh_token
string

The refresh token from the expiring auth token. Required for the "refresh_token" grant type

client_id
required
string

Your application's client ID

client_secret
required
string

Your application's client secret. Keep this safe

Responses

Request samples

Content type
Example
{
  • "grant_type": "authorization_code",
  • "code": "r0tp5Kfz2M3tHUcvyszShXHGuYyC34izJQBUBV3c",
  • "client_id": "tSGoPlf1Fs6JIhUAwYO45KTk9vxmPSAGD5WEemWv",
  • "client_secret": "C6O5EIQzvf8djefeVsmb3NsPjYdPpSc7xwX95UCN"
}

Response samples

Content type
application/json
{
  • "access_token": "TNaqe9fl4bWsUtQ6kn4YGl6NQHSZ6fZ3HE6fpj3B",
  • "expires_in": 3600,
  • "token_type": "Bearer",
  • "scope": "incident:read incident:write",
  • "refresh_token": "g91NOvJ7gwTHS0v9pd3YvJ9rJTv8aazKhAHD4ce5"
}

External user accounts

These endpoints are provided for applications that are using the OAuth2 Client Credentials flow to authenticate their own users with the API directly. They allow the registration of external users in the API to provide core functionality like incident reports and Guest Check.

Web push notification subscriptions are not available to external user accounts. Email incident alerts for external accounts are provisioned by the notification service directly from user account data.

For applications using the Authorization Code flow, these endpoints do not need to be implemented.

Create an account

Register an external user account with the API.

Authorizations:
OAuth
Request Body schema: application/json
external_id
required
string

The ID of the account in the integrating platform

name
required
string

The name of the account user

email
required
string <email>

The email address of the account user. A welcome email will be sent to this email address when the account is created

required
object

Details of the location associated with the account. This location will be used when submitting incident reports

Responses

Request samples

Content type
application/json
{
  • "external_id": "string",
  • "name": "string",
  • "email": "user@example.com",
  • "location": {
    }
}

Response samples

Content type
application/json
{
  • "status": "created",
  • "message": "string",
  • "data": {
    }
}

Get an account

Get an external user account by its account ID.

Authorizations:
OAuth
path Parameters
account_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": "found",
  • "message": "string",
  • "data": {
    }
}

Update an account

Update an external user account by its account ID.

Authorizations:
OAuth
path Parameters
account_id
required
string <uuid>
Request Body schema: application/json
external_id
required
string

The ID of the account in the integrating platform

name
required
string

The name of the account user

email
required
string <email>

The email address of the account user. A welcome email will be sent to this email address when the account is created

required
object

Details of the location associated with the account. This location will be used when submitting incident reports

Responses

Request samples

Content type
application/json
{
  • "external_id": "string",
  • "name": "string",
  • "email": "user@example.com",
  • "location": {
    }
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "message": "string",
  • "data": {
    }
}

Incident reports

Incident reports are the main resource type provided by the API. Creating an incident report will flag the offenders listed in the report as rogue guests. Guest Check allows Good To Book customers to look up a guest's details to see any matching incident reports, so they can make an informed decision about accepting a guest's booking.

Once created, incident reports are read-only and are visible to Good To Book customers for up to five years. In some cases they may be visible to law enforcement agencies. For more details, see the Good To Book terms of use.

Create an incident report

Enter guest details into the Good To Book incident database.

Although most fields are optional, integrators should provide the ability to complete every field when submitting an incident report, and encourage end users to provide as much detail as possible.

Authorizations:
OAuth
Request Body schema: application/json
required
datetime
required
string <date-time>

The date and time the incident took place

description
string

A description of the incident

This field is for Good To Book's records only. It will not be visible in API response data

object

Details of the visit during which the incident occurred. This object is optional.

required
Array of objects non-empty unique

A list of people related to the incident. At least one person must be provided. This is a required field.

Array of objects unique

A list of vehicles related to the incident. This field is optional.

offences
Array of strings unique
Items Enum: "illicit_substance" "theft" "threatening_behaviour" "violence" "excessive_mess" "outstanding_fees" "police_callout" "police_incident_filed" "malicious_chargeback" "credit_card_fraud" "fraud" "agreed_rules_broken" "wilful_damage"

A list of offences committed by the offenders. This field is optional.

Responses

Request samples

Content type
application/json
{
  • "datetime": "2019-08-24T14:15:22Z",
  • "description": "The room was left dirty and damaged",
  • "visit": {
    },
  • "people": [
    ],
  • "vehicles": [
    ],
  • "offences": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "created",
  • "message": "string",
  • "data": {
    }
}

List incident reports Deprecated

v1.6.0: This endpoint is now deprecated. Use Guest Check instead.

Get a paginated list of all incident reports, or a subset that match some filter criteria.

Authorizations:
OAuth
query Parameters
limit
integer

The maximum number of items to get

next
string

The key for the page of items to get. Provided in the next property of the previous page's response

datetime
string <filter>

An expression to filter the results by incident time
Supported operators: "range"

offender
string <filter>

An expression to filter the results by offender
Supported operators: "like"

Responses

Response samples

Content type
application/json
{
  • "status": "found_some",
  • "message": "string",
  • "data": [
    ],
  • "next": "string"
}

Get an incident report

Get a single incident report by its report ID.

Authorizations:
OAuth
path Parameters
incident_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "message": "found",
  • "data": {
    }
}

Guest Check

Good To Book's Guest Check allows guest data to be queried against the incident reports database, providing details on previous offences if rogue guest matches are found.

Each matched incident report returned by Guest Check includes a match strength indicator. This is a number between 0 and 100 which represents how well the incident report matches the data provided in the request. This may be presented as a percentage, but it is not a statistical probability or confidence interval. Incident reports in Guest Check results are ordered by decreasing match strength, and those with match strength less than 50 will not be included.

Search for incidents

Look up known rogue guests in the Good To Book incident database. This endpoint accepts queries in the form of a single string value, making it suitable for input from human users.

Authorizations:
OAuth
query Parameters
query
required
string

The values to search for in the incident database

Responses

Response samples

Content type
application/json
{
  • "status": "found_some",
  • "message": "found_some",
  • "data": [
    ],
  • "matches": [
    ]
}

Query guest details

Compare the details of guests on a new booking with known rogue guests in the Good To Book incident database. This endpoint expects query data in a structured form that is suited to automated machine-to-machine querying.

Authorizations:
OAuth
Request Body schema: application/json
required
Array of objects non-empty unique

A list of people on the booking

Array of objects unique

A list of vehicles related to the booking

Responses

Request samples

Content type
application/json
{
  • "people": [
    ],
  • "vehicles": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "found_some",
  • "message": "found_some",
  • "data": [
    ],
  • "matches": [
    ]
}

Notification subscriptions

Notification subscriptions control how a user receives push notification messages about events that happen in the API. The user subscribes by registering a device or web browser to receive one or more notification types.

Notification type Trigger
nearby_incident_alerts When a new incident report is created in the user's area of interest. By default, this is the area covered by their account address postcode.

Each notification type can be enabled or disabled individually. All notification types for an individual subscription can also be disabled globally.

Subscribe to notifications

Create a new notification subscription for the authenticated account.

Authorizations:
OAuth
Request Body schema: application/json
required
platform
required
string
Value: "web"

The platform type for this subscription

endpoint
required
string <uri>

The push notification endpoint URL

required
object
required
object

Notification preferences for this subscription. Defines which types of notifications the user wants to receive.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "status": "created",
  • "message": "string",
  • "data": {
    }
}

List subscriptions

Retrieve all notification subscriptions for the authenticated account.

Authorizations:
OAuth

Responses

Response samples

Content type
application/json
{
  • "status": "found_some",
  • "message": "string",
  • "data": [
    ]
}

Update subscription preferences

Update notification preferences for a subscription of the authenticated account.

Authorizations:
OAuth
path Parameters
subscription_id
required
string <uuid>

The ID of the subscription to update

Request Body schema: application/json
required
active
boolean

Activate or deactivate this subscription.

object

Notification preferences to update. Only properties explicitly provided in the request will be updated.

Responses

Request samples

Content type
application/json
{
  • "active": true,
  • "preferences": {
    }
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "message": "updated",
  • "data": {
    }
}

Unsubscribe from notifications

Delete a notification subscription from the authenticated account.

Authorizations:
OAuth
path Parameters
subscription_id
required
string <uuid>

The ID of the subscription to delete

Responses

Response samples

Content type
application/json
{
  • "status": "not_found",
  • "message": "The requested resource could not be found",
  • "error": [
    ]
}

Get VAPID public key

Retrieve the VAPID public key required for push notification subscriptions.

Authentication is not required for this endpoint.

Responses

Response samples

Content type
application/json
{
  • "status": "found",
  • "message": "string",
  • "data": {
    }
}

Notification messages

Notification messages contain details of events that happen in the API, and are delivered via a notification subscription. A user can read their notification history, and mark notifications as read.

List notifications

Retrieve all notifications for the authenticated account (historical, missed, dismissed).

Authorizations:
OAuth
query Parameters
limit
integer

The maximum number of items to get

next
string

The key for the page of items to get. Provided in the next property of the previous page's response

status
string
Example: status=in:sent,delivered,failed

An expression to filter notifications by status.
Supported operators: "eq", "in"

type
string
Example: type=eq:nearby_incident_alerts

An expression to filter notifications by type.
Supported operators: "eq", "in"

Responses

Response samples

Content type
application/json
{
  • "status": "found_some",
  • "message": "string",
  • "data": [
    ],
  • "next": "string"
}

Get a notification

Retrieve a specific notification by its ID for the authenticated account.

Authorizations:
OAuth
path Parameters
notification_id
required
string <uuid>

The ID of the notification to retrieve

Responses

Response samples

Content type
application/json
{
  • "status": "found",
  • "message": "string",
  • "data": {
    }
}

Update a notification status

Update the status of a notification to mark as read or dismissed.

Authorizations:
OAuth
path Parameters
notification_id
required
string <uuid>

The ID of the notification to update

Request Body schema: application/json
required
status
required
string
Enum: "read" "unread"

Update the status of the notification

Responses

Request samples

Content type
application/json
{
  • "status": "read"
}

Response samples

Content type
application/json
{
  • "status": "updated",
  • "message": "string",
  • "data": {
    }
}

Changelog

v1.8.0

1 June 2026

  • Added email notification type for use with external user accounts.

v1.7.4

24 May 2026

  • Fixed notification timestamps being returned as empty objects instead of date strings.

v1.7.3

14 April 2026

  • Fixed handling of formatted phone numbers passed to v1/guest-check/search endpoint.

v1.7.2

6 April 2026

  • Added details of JSON validation errors to API docs.

v1.7.1

31 March 2026

  • Fixed a server error when fetching user notifications.

v1.7.0

09 March 2026

  • Added two new location types for nearby incident report notifications:
    • radius: Notifications delivered when an incident is reported within a radius around a place or coordinates.
    • all: Notifications delivered when an incident is reported regardless of location.
  • Improved error messages for pattern-based JSON validators.
  • Updated the registration_number schema to allow only letters and numbers (no spaces).
  • Added a model field, for specifying the make and model of a vehicle.

v1.6.2

6 February 2026

Made several improvements to field matching logic on /v1/guest-check endpoints:

  • Fixed symbols being treated as whole words.
  • Fixed incorrect match score when multiple fields contain the same value.
  • Improved format compatibility when matching on phone_number field.

v1.6.1

28 January 2026

  • Fixed the schema for the notification-subscription endpoint, which was preventing multiple location-based preferences being set simultaneously (e.g. postcode and radius).

v1.6.0

17 December 2025

New notification system

Two new groups of endpoints /v1/notification and /v1/notification/subscription provide capabilities for viewing/querying and managing notifications, respectively. Users can enable individual notification categories to receive push notification in their web browser:

  • nearby_incident_alerts: Notifications delivered when an incident is reported near the user's location. Users can select the desired alert location by postcode or radius around a place or coordinates.

Incident report listing removed

The ability to list incident reports via GET /v1/incident has been removed and the GET method for this path has been deprecated. Requests made to this endpoint will return no results, as if non-matching filters were specified. If the previously deprecataed offender parameter is passed in the URL query string, results will be returned as if the /v1/guest-check/search endpoint was used instead.

Other changes

  • Users can now provide an email address for each reported person when submitting an incident report. These email addresses will be used for matching incident reports via the Guest Check endpoints.

v1.5.1

9 October 2025

  • Fixed a bug where multiple weakly matched people on the same incident report would result in the match strength being inflated in guest-check endpoint results.

v1.5.0

25 September 2025

Improved Guest Check match accuracy

Guest Check results now include a match_strength property to indicate how well each result matches the request query. The more unique matching properties found on an incident report, the higher the match strength, up to a maximum of 100. Incident reports in Guest Check results are ordered by decreasing match strength, and those with match strength less than 50 will not be included.

Other changes

  • Fixed issues with request validation on guest-check/query endpoint.
  • Fixed error parsing invalid date formats.
  • Fixed error when no Content-Type header is set.

v1.4.6

30 July 2025

  • Fixed false matches in Guest Check endpoint queries by ignoring empty string values.

v1.4.5

12 May 2025

  • Fixed account status not updating immediately after subscription activation.

v1.4.4

13 January 2025

  • Fixed some accounts not being recognised as having valid Good To Book subscriptions.

v1.4.3

11 December 2024

  • Fixed HTTP status code for inactive user accounts
  • Fixed alias names not being matched in guest-check endpoints
  • Fixed people with multiple names not being matched in guest-check endpoints

v1.4.2

26 November 2024

  • Fixed incorrect incident endpoint JSON validation logic

v1.4.1

27 September 2024

  • Bug fixes

v1.4.0

28 May 2024

  • Added new incident offence option for reporting malicious chargebacks

v1.3.0

20 May 2024

New Guest Check search endpoints

Dedicated endpoints /v1/guest-check/search and /v1/guest-check/query for guest screening provide improved accuracy by matching potential rogue guests on multiple incident fields, with results sorted automatically.

Other changes

  • Deprecated the offender query parameter on the incident listing endpoint
  • Fixed incorrect response status when unsupported media type is sent
  • Fixed missing unprocessable entity error response data
  • Other minor fixes for 4xx error responses

v1.2.2

16 November 2023

  • Performance improvements
  • Minor bug fixes

v1.2.1

20 September 2023

  • Increased maximum allowed size of request body JSON data

v1.2.0

25 May 2023

  • Added support for cross-origin requests

v1.1.2

24 April 2023

  • Fixed error when creating an external account

v1.1.1

22 February 2023

  • Improved offender name matching on incident reports

v1.1.0

22 September 2022

  • Added 410 response for expired incident reports

v1.0.0

27 July 2022

The first public release of the Guest Check API. No changes since v0.3.3