logo
API docs by Redocly

Let's Book API (1.0)

Let's Book: tech@lets-book.com URL: https://lets-book.com

Changelog

2024-05-31

  • Renamed all references from VAT to tax. For backward compatibility, the legacy VAT properties remain available but are now deprecated.
  • Introduced the new /v1/tax-rates endpoint and deprecated the legacy /v1/vat-rates endpoint.

Introduction

The Let's Book API adheres to REST standards. When an endpoint accepts parameters, data should be transmitted as either a JSON body or form-encoded data. All responses are returned in JSON format. Every endpoint begins with the base URL: https://api.letsbook.app. The OpenAPI specification is available at https://developers.lets-book.com/api-spec.json.

You can be assured that all GET requests do not modify any data and are therefore idempotent, while POST/PUT/DELETE requests are not. We use HTTP status codes to communicate errors whenever possible.

Authentication

To access the API, you need an API key, which can be obtained from the dashboard. The API key is used as a Bearer Authentication token. Please note that the API key is case- sensitive. Most tooling supports Bearer Authentication natively. If you are using a tool that does not support it, you can construct the Authorization header manually as follows: Authorization: Bearer <API_KEY>.

Example

For instance, when your API key is ac11f67b-1dcb-460c-aff3-f1ef35cd3c1c|pMKSUHcHXd7706zhHwBE040alh1BSY9RPsu6ZQ04, you should configure the header as follows:

Authorization: Bearer ac11f67b-1dcb-460c-aff3-f1ef35cd3c1c|pMKSUHcHXd7706zhHwBE040alh1BSY9RPsu6ZQ04

Multiple Tenants

If your API user has access to multiple tenants, you should include the X-Tenant-Id header with every request. If no header is provided, we will default to your primary tenant.

Example

You can use the /me endpoint to retrieve a list of all tenants to which you have access. You can then use the id of the desired tenant. For example, if the ID is 9366b305-e315-4abe-ba8a-90e326ad8e81, you would configure the header as follows:

X-Tenant-Id: 9366b305-e315-4abe-ba8a-90e326ad8e81

Me

Retrieves information about the current user. Primarily used to verify that authentication is functioning as expected.

Me

Retrieves user information for the currently authenticated user.

Responses

Response Schema: application/json
required
object

Information regarding the authenticated API user

Response samples

Content type
application/json
{
  • "data": {
    • "description": "My app API key",
    • "currentTenant": {
      },
    • "tenants": [
      ]
    }
}

Docks

A dock serves as the pickup and return point for boats. Boats can be moored at docks for specified periods of time.

List all docks

Returns a list of your docks. The docks are sorted by the order as defined in the dashboard. The response is not paginated.

Responses

Response Schema: application/json
required
Array of objects (Dock)

Response samples

Content type
application/json
{}

Retrieve a dock

Retrieve a Dock object by ID.

path Parameters
id
required
string
Example: 8d159bbe-f6bc-4ddd-8c9a-6091d7ebd278

ID of the dock

Responses

Response Schema: application/json
required
object (Dock)

The location from where boats can be picked up

Response samples

Content type
application/json
{}

Boat models

A boat model represents a type of boat. Many boat rental companies maintain multiple interchangeable boats of the same type, which we refer to as a boat model.

List all boat models

Returns a list of boat models. The boat models are sorted by the order as defined in the dashboard. The response is not paginated.

Responses

Response Schema: application/json
required
Array of objects (BoatModel)

Response samples

Content type
application/json
{}

Retrieve a boat model

Retrieve a BoatModel object by ID.

path Parameters
id
required
string
Example: 8d159bbe-f6bc-4ddd-8c9a-6091d7ebd278

ID of the boat model

Responses

Response Schema: application/json
required
object (BoatModel)

A boat model

Response samples

Content type
application/json
{}

Customers

A customer is an individual who rents a boat.

List all customers

Retrieves a comprehensive list of your customers.

query Parameters
page
integer
Default: 1
Example: page=1

The page number to fetch.

Responses

Response Schema: application/json
required
Array of objects (Customer)
required
object (Pagination)

Pagination to iterate large result sets.

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ],
  • "pagination": {}
}

Create a customer

Registers a new customer in the system.

Request Body schema: application/json
customerTypeId
required
string

Customer type ID

givenName
required
string

First name of the customer

familyName
required
string

Last name of the customer

emailAddress
required
string <email>

Email address of the customer

phoneNumber
string

Phone number of the customer in E.164 format

preferredLocale
string

Preferred locale of the customer in language_COUNTRY format.

password
string

Password of the customer. Should be left empty if you don't want to change the password. It will be set to a random password if you don't specify one when creating a new customer.

Note: The password must be at least 8 characters long.

addAliasOnDuplicate
boolean
Default: false

If set to true, the customer will be added as an alias to the existing customer with the same email address. If set to false, an error will be returned if the customer already exists.

notifyCustomer
boolean
Default: false

If set to true, the customer will receive an email containing their login credentials.

Responses

Response Schema: application/json
required
object (Customer)

Data of the customer

Request samples

Content type
application/json
{
  • "customerTypeId": "a6fe15b1-8131-4f48-8082-311e0369f599",
  • "givenName": "John",
  • "familyName": "Doe",
  • "emailAddress": "john.doe@example.com",
  • "phoneNumber": "+49123456789",
  • "preferredLocale": "sv_SE",
  • "password": "correcthorsebatterystaple",
  • "addAliasOnDuplicate": false,
  • "notifyCustomer": true
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": "8d159bbe-f6bc-4ddd-8c9a-6091d7ebd278",
    • "customerTypeId": "a6fe15b1-8131-4f48-8082-311e0369f599",
    • "givenName": "John",
    • "familyName": "Doe",
    • "fullName": "John Doe",
    • "emailAddress": "john.doe@example.com",
    • "phoneNumber": "+49123456789",
    • "preferredLocale": "sv_SE",
    • "registeredAt": "2022-01-01T13:37:00Z"
    }
}

Search customers

Returns a list of all customers matching the query.

query Parameters
emailAddress
string <email>
Example: emailAddress=john.doe@example.com

The email address to search for

page
integer
Default: 1
Example: page=1

The page number to fetch.

Responses

Response Schema: application/json
required
Array of objects (Customer)
required
object (Pagination)

Pagination to iterate large result sets.

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ],
  • "pagination": {}
}

Retrieve a customer

Retrieve a Customer object by ID.

path Parameters
id
required
string
Example: 8d159bbe-f6bc-4ddd-8c9a-6091d7ebd278

ID of the customer

Responses

Response Schema: application/json
required
object (Customer)

Data of the customer

Response samples

Content type
application/json
{
  • "data": {
    • "id": "8d159bbe-f6bc-4ddd-8c9a-6091d7ebd278",
    • "customerTypeId": "a6fe15b1-8131-4f48-8082-311e0369f599",
    • "givenName": "John",
    • "familyName": "Doe",
    • "fullName": "John Doe",
    • "emailAddress": "john.doe@example.com",
    • "phoneNumber": "+49123456789",
    • "preferredLocale": "sv_SE",
    • "registeredAt": "2022-01-01T13:37:00Z"
    }
}

Update a customer

Update an existing customer.

path Parameters
id
required
string
Example: 8d159bbe-f6bc-4ddd-8c9a-6091d7ebd278

ID of the customer

Request Body schema: application/json
customerTypeId
string

Customer type ID

givenName
string

First name of the customer

familyName
string

Last name of the customer

emailAddress
string <email>

Email address of the customer

phoneNumber
string

Phone number of the customer in E.164 format

preferredLocale
string

Preferred locale of the customer in language_COUNTRY format.

password
string

Password of the customer. Should be left empty if you don't want to change the password. It will be set to a random password if you don't specify one when creating a new customer.

Note: The password must be at least 8 characters long.

Responses

Response Schema: application/json
required
object (Customer)

Data of the customer

Request samples

Content type
application/json
{
  • "customerTypeId": "a6fe15b1-8131-4f48-8082-311e0369f599",
  • "givenName": "John",
  • "familyName": "Doe",
  • "emailAddress": "john.doe@example.com",
  • "phoneNumber": "+49123456789",
  • "preferredLocale": "sv_SE",
  • "password": "correcthorsebatterystaple"
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": "8d159bbe-f6bc-4ddd-8c9a-6091d7ebd278",
    • "customerTypeId": "a6fe15b1-8131-4f48-8082-311e0369f599",
    • "givenName": "John",
    • "familyName": "Doe",
    • "fullName": "John Doe",
    • "emailAddress": "john.doe@example.com",
    • "phoneNumber": "+49123456789",
    • "preferredLocale": "sv_SE",
    • "registeredAt": "2022-01-01T13:37:00Z"
    }
}

List all customer types

Returns a list of all customer types. The response is not paginated.

Responses

Response Schema: application/json
required
Array of objects (CustomerType)

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ]
}

Bookings

A booking can be created by customers or staff members. It represents a reservation for a specific boat model, to be picked up at a designated time from a specific dock and returned at a specified time to that same dock.

Bookings can have various statuses.

List all bookings

Retrieves a comprehensive list of all bookings.

query Parameters
page
integer
Default: 1
Example: page=1

The page number to fetch.

status
string
Enum: "draft" "expired" "option" "confirmed" "completed" "canceled" "all"

Display only bookings with the specified status

updatedAfter
string <date-time>
Example: updatedAfter=2022-01-01T00:00:00Z

Display only bookings updated after the specified date and time in ISO 8601 format

Responses

Response Schema: application/json
required
Array of objects (Booking)
required
object (Pagination)

Pagination to iterate large result sets.

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ],
  • "pagination": {}
}

Create a booking

Creates a new booking with confirmed status.

Request Body schema: application/json
customerId
required
string

ID of the customer

dockId
required
string

ID of the dock

boatModelId
required
string

ID of the boat model

pickup
required
string <date-time>

Pickup date and time in ISO 8601 format

return
required
string <date-time>

Return date and time in ISO 8601 format

boats
integer
Default: 1

Number of boats booked

passengers
integer
Default: 1

Number of passengers including the customer who booked the boat

paid
boolean
Default: true

If set to true, the booking will be marked as paid by adding a cash payment equal to the unpaid costs. It will be ignored when the booking is already fully paid.

Note that slot based pricing may fail to calculate the correct amount as the slot is not known when the booking is created using the API.

createdAt
string <date-time>

The time this booking was first created in ISO 8601 format

notifyCustomer
boolean
Default: false

If set to true, the customer will receive a booking confirmation email.

includePaymentLink
boolean
Default: true

Whether or not the booking confirmation email should contain a payment request link. Only applicable if notifyCustomer is true.

Responses

Response Schema: application/json
required
object

Request samples

Content type
application/json
{
  • "customerId": "8d159bbe-f6bc-4ddd-8c9a-6091d7ebd278",
  • "dockId": "3462e0cd-a446-49b7-bf18-b5e1c78098ca",
  • "boatModelId": "3462e0cd-a446-49b7-bf18-b5e1c78098ca",
  • "pickup": "2022-01-01T00:00:00Z",
  • "return": "2022-01-03T00:00:00Z",
  • "boats": 1,
  • "passengers": 1,
  • "paid": true,
  • "createdAt": "2022-01-01T00:00:00Z",
  • "notifyCustomer": false,
  • "includePaymentLink": true
}

Response samples

Content type
application/json
{
  • "data": {
    • "bookingId": "4a974b2a-2d35-4313-a2e9-5aee4e83601f"
    }
}

Retrieve a booking

Retrieve a booking with its financial and customer details.

path Parameters
id
required
string
Example: 8d159bbe-f6bc-4ddd-8c9a-6091d7ebd278

ID of the booking

Responses

Response Schema: application/json
required
object (BookingExtended)

Comprehensive booking details

Response samples

Content type
application/json
{
  • "data": {
    • "id": "551ceb1c-6fbc-479b-819d-734f4044eca2",
    • "reference": "BK8J3L",
    • "status": "confirmed",
    • "customerId": "8d159bbe-f6bc-4ddd-8c9a-6091d7ebd278",
    • "dockId": "3462e0cd-a446-49b7-bf18-b5e1c78098ca",
    • "boatModelId": "3462e0cd-a446-49b7-bf18-b5e1c78098ca",
    • "pickup": "2022-01-01T00:00:00Z",
    • "return": "2022-01-03T00:00:00Z",
    • "boats": 1,
    • "passengers": 1,
    • "createdAt": "2022-01-01T00:00:00Z",
    • "updatedAt": "2022-01-01T00:00:00Z",
    • "url": "https://barrysboats.letsbook.app/bookings/BK8J3L",
    • "customer": {
      },
    • "financialDetails": {
      }
    }
}

Update a booking

Update an existing booking.

path Parameters
id
required
string
Example: 8d159bbe-f6bc-4ddd-8c9a-6091d7ebd278

ID of the booking

Request Body schema: application/json

Update booking parameters. None of the fields are required.

customerId
string

ID of the customer

dockId
string

ID of the dock

boatModelId
string

ID of the boat model

pickup
string <date-time>

Pickup date and time in ISO 8601 format

return
string <date-time>

Return date and time in ISO 8601 format

boats
integer
Default: 1

Number of boats booked

passengers
integer
Default: 1

Number of passengers including the customer who booked the boat

paid
boolean
Default: true

If set to true, the booking will be marked as paid by adding a cash payment equal to the unpaid costs. It will be ignored when the booking is already fully paid.

Note that slot based pricing may fail to calculate the correct amount as the slot is not known when the booking is created using the API.

createdAt
string <date-time>

The time this booking was first created in ISO 8601 format

notifyCustomer
boolean
Default: false

If set to true, the customer will receive a booking updated email.

Responses

Response Schema: application/json
required
object

Request samples

Content type
application/json
{
  • "customerId": "8d159bbe-f6bc-4ddd-8c9a-6091d7ebd278",
  • "dockId": "3462e0cd-a446-49b7-bf18-b5e1c78098ca",
  • "boatModelId": "3462e0cd-a446-49b7-bf18-b5e1c78098ca",
  • "pickup": "2022-01-01T00:00:00Z",
  • "return": "2022-01-03T00:00:00Z",
  • "boats": 1,
  • "passengers": 1,
  • "paid": true,
  • "createdAt": "2022-01-01T00:00:00Z",
  • "notifyCustomer": false
}

Response samples

Content type
application/json
{
  • "data": {
    • "bookingId": "4a974b2a-2d35-4313-a2e9-5aee4e83601f"
    }
}

Tax rates

A tax rate is a named percentage used to calculate taxes on add-ons, costs, and other charges.

List all tax rates

Returns a list of tax rates used in costs, add-ons, etc. The response is not paginated.

Responses

Response Schema: application/json
required
Array of objects (TaxRate)

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ]
}

List all VAT rates Deprecated

Deprecated. Use the GET /v1/tax-rates endpoint instead.

Responses

Response Schema: application/json
required
Array of objects (TaxRate)

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ]
}

Availability

Availability represents the availability of a boat model at a specific dock. Availability is calculated by subtracting the number of bookings for a specific boat model at a specific dock from the total number of boats available at that dock.

Calculate availability

Get availability for a boat model at a dock during a date/time period.

query Parameters
dockId
required
string <uuid>
Example: dockId=878f1403-9677-482d-a09d-392004de8c46

The dock ID

boatModelId
required
string <uuid>
Example: boatModelId=2d2071f6-0a1d-4aca-a49d-4d112b141c44

The boat model ID

period
required
string <date-time-period>
Example: period=2022-01-01T00:00:00Z/2022-01-03T00:00:00Z

The period of time to check availability

Responses

Response Schema: application/json
required
object

The availability result

required
object

The parameters used to calculate availability. Can be used to verify the query parameters were parsed correctly.

Response samples

Content type
application/json
{
  • "data": {
    • "lowestAvailability": 4,
    • "perMoment": [
      ]
    },
  • "parameters": {
    • "dockId": "878f1403-9677-482d-a09d-392004de8c46",
    • "boatModelId": "2d2071f6-0a1d-4aca-a49d-4d112b141c44",
    • "period": {
      }
    }
}