DigitalGuest API (1.0.0)

Download OpenAPI specification:Download

Introduction

DigitalGuest provides a modern, RESTful API for one-way integration with our guest journey platform. Our open API supports creating and modifying booking objects, using JSON as the data format.

For development you should use the sandbox environment at api-dev.digitalguest.com. If you run into any issues, contact our API support and remember to include the eventId from the error response.

Getting Started

If you haven't received authentication info already, contact us to receive a token and the property IDs, we'll set up the required permissions for your clients.

To register a new booking, send a POST request with the booking information. This should be done before sending any update requests, but it is not a hard requirement. When the guest checks in, or out, send a PUT request with state changed. To cancel the booking, send a DELETE request. Many of the booking and guest fields are optional, but they should be filled out if possible.

Status codes

Standard HTTP status codes along with objects are used to return statuses. Responses may include additional information in the optional data field. All requests may return 400, 401, 403, or 500, so they're excluded from the examples for brevity.

Code Message
200 Success.
201 Resource created.
400 Bad request, likely due to missing or invalid input.
401 Missing or invalid authentication.
403 Forbidden.
404 The requested resource doesn't exist.
500 Internal server error. Contact us if the issue persists.

Authentication

Bearer

Authentication is done with JSON Web Tokens, unique for each provider. Contact us to receive a token. Authorization is handled on a per-property basis, contact us if you don't have permission to your client's property.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Bookings

Get booking

Authorizations:
path Parameters
propertyId
required
string non-empty
Example: TheHendrixHotel

Property ID.

bookingId
required
string non-empty
Example: 8324792

Unique ID used to reference bookings.

Responses

Response samples

Content type
application/json
Example
{
  • "type": "accommodation",
  • "state": "expected",
  • "arrival": "2020-12-13T14:00:00.000Z",
  • "departure": "2020-12-21T11:00:00.000Z",
  • "guest": {
    },
  • "unit": {
    },
  • "rateCode": "BAR2"
}

Create booking

Authorizations:
path Parameters
propertyId
required
string non-empty
Example: TheHendrixHotel

Property ID.

bookingId
required
string non-empty
Example: 8324792

Unique ID used to reference bookings.

Request Body schema: application/json
type
required
string
state
required
string
Enum: "expected" "arrived" "departed"

Booking state.

arrival
string <date-time>

Arrival date.

departure
string <date-time>

Departure date.

required
object (Guest)

Contact person for the booking.

email or phone must be present for the guest to receive messages, ideally both.

object
rateCode
string

Code identifying the booking's rate plan.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "accommodation",
  • "state": "expected",
  • "arrival": "2020-12-13T14:00:00.000Z",
  • "departure": "2020-12-21T11:00:00.000Z",
  • "guest": {
    },
  • "unit": {
    },
  • "rateCode": "BAR2"
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "message": "Booking updated.",
  • "eventId": "3d4570c3",
  • "data": {
    }
}

Update booking

This endpoint is used to update existing bookings. If the booking doesn't exist, it will be implicitly created, but this should be done with a POST request if possible.

This endpoint is primarily for changing the booking state. When the guest checks in, state must be changed to arrived, and likewise departed when the guest checks out. Updating the booking is also supported, such as the room number, contact info, and arrival/departure date. The entire booking object gets replaced, so you must include every field that was in the original booking, excluding any fields that should be removed.

If a message needs to be re-sent with different contact info, after state has already been updated (e.g. if the email contained a typo but the guest already checked in), the booking must be recreated by cancelling it first.

Authorizations:
path Parameters
propertyId
required
string non-empty
Example: TheHendrixHotel

Property ID.

bookingId
required
string non-empty
Example: 8324792

Unique ID used to reference bookings.

Request Body schema: application/json
type
required
string
state
required
string
Enum: "expected" "arrived" "departed"

Booking state.

arrival
string <date-time>

Arrival date.

departure
string <date-time>

Departure date.

required
object (Guest)

Contact person for the booking.

email or phone must be present for the guest to receive messages, ideally both.

object
rateCode
string

Code identifying the booking's rate plan.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "accommodation",
  • "state": "expected",
  • "arrival": "2020-12-13T14:00:00.000Z",
  • "departure": "2020-12-21T11:00:00.000Z",
  • "guest": {
    },
  • "unit": {
    },
  • "rateCode": "BAR2"
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "message": "Booking updated.",
  • "eventId": "3d4570c3",
  • "data": {
    }
}