logo
Documentation Powered by ReDoc

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 to VAT to tax. For backwards compatibility, the old VAT properties are still available, but are deprecated.
  • Added the new /v1/tax-rates endpoint and deprecated the old /v1/vat-rates endpoint.

Introduction

The Let's Book API uses the REST standard. When an endpoint accepts parameters, the data should be sent as a JSON body or form-encoded. The response will always be returned as JSON. All endpoints start with the base URL: https://api.letsbook.app. The OpenAPI specification is available at https://developers.lets-book.com/api-spec.json.

Note: The API is currently in beta. Please contact us if you run into any issues.

You can be certain all GET requests won't change any data and are therefore idempotent while POST/PUT/DELETE requests are not. We use HTTP status codes to communicate what went wrong whenever possible.

Authentication

To use the API, you'll need an API key which can be obtained from the dashboard. The API key is used as a 'Bearer Authentication' token. Note that the API key is case sensitive. The tooling you're using probably supports Bearer Authentication. If you're using a tool that doesn't, you can construct the Authorization header yourself like this: Authorization: Bearer <API_KEY>.

Example

For example, when your API key is ac11f67b-1dcb-460c-aff3-f1ef35cd3c1c|pMKSUHcHXd7706zhHwBE040alh1BSY9RPsu6ZQ04 you should set 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 supply the X-Tenant-Id header with every request. If no header is specified, we will assume the default tenant.

Example

You can use the /me endpoint to get a list of all tenants you have access to. You can then use the id of the tenant you want to access. Let's say the ID is 9366b305-e315-4abe-ba8a-90e326ad8e81. You can then set the header like this:

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

Me

Echo information about the current user. Mainly used to verify authentication works as expected.

Me

Retrieve user information about the current user.

Responses

Response Schema: application/json
required
object

Information about the authenticated API user

Response samples

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

Docks

A dock is the pickup & return point for a boat. Boats can be moored at docks for a period of time.

List all docks

Returns a list of your docks. The docks are sort 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 is a type of boat. Many boat rental companies have multiple of interchangeable boats. We call that a boat model.

List all boat models

Returns a list of boat models. The boat models are sort 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 a person who rents a boat.

List all customers

Returns a 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

Register a new customer

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 made by customers or staff members. It is basically a reservation for a specific boat model, picked up at a certain time at a specific dock and returned an at a certain time at that same dock.

Bookings can have different statuses.

List all bookings

Returns a 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"

Only show bookings with the supplied status

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

Only show bookings updated after supplied date time in ISO8601 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 confirmed booking.

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 and its financial details 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 (schemas)

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 named percentage used to calculate the tax on add-ons, costs and more.

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 is 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 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": {
      }
    }
}