API V2

API V2 lets you, or a third party you invite, access your Beds24 account, properties, bookings and inventory. You authenticate with a token in the request header, and the scopes of the token decide what it can read and change. Try the endpoints in the interactive documentation at beds24.com/api/v2.

Note: API V1 is deprecated and not recommended for new projects. See How to use API.

Contents

Authentication

To use most API endpoints, include a token header in the format token: {token}. There are two kinds of tokens: long life tokens, which have read-only access, and refresh tokens, which generate tokens that can read and make changes.

Credential What it does How long it lasts
Invite code Exchanged for a refresh token and token with GET /authentication/setup Expires after 24 hours
Long life token Authenticates calls, read-only access Lasts forever as long as it's used. Unused long life tokens expire after 90 days.
Refresh token Generates new tokens with GET /authentication/token Lasts forever as long as it's used. Unused refresh tokens expire after 30 days.
Token generated from a refresh token Authenticates calls, read and write access (within its scopes) Expires after 24 hours

Tokens are between 152 and 172 characters long.

Get and use a token

  1. Get an invite code or long life token. Generate them on the Invite Codes page (Settings > Marketplace > API). See Invite codes. This is the only step you must do manually: you can perform and automate all other steps programmatically.
  2. If you use an invite code, get a refresh token. Skip this step if you use a long life token. Use the invite code with GET /authentication/setup. It returns a token and a refresh token.
  3. Use the token to authenticate calls. Include the token (a long life token or a token generated with a refresh token) as a header to authenticate calls to other API endpoints.
  4. Use the refresh token to generate new tokens. Tokens generated from refresh tokens expire after 24 hours, so use the refresh token with GET /authentication/token to get new tokens when old ones expire.

Tip: Try this out in the interactive UI at beds24.com/api/v2.

Get a refresh token

Exchange your invite code with GET /authentication/setup.

Request:

curl -X 'GET' \ 'https://beds24.com/api/v2/authentication/setup' \ -H 'accept: application/json' \ -H 'code: abc123'

Response:

{
  "token": "qEK5L...",
  "expiresIn": 86400,
  "refreshToken": "iexTC..."
}

token is a short-term access token to authenticate other API calls, expiresIn is how many seconds the token lasts, and refreshToken generates more tokens in the future.

Refresh a token

Request:

curl -X 'GET' \
  'https://api.example.com/v2/authentication/token' \
  -H 'accept: application/json' \
  -H 'refreshToken: Ea6DftE50aYYRe/qAd9SkQaSmTF6kaLQxH6gtRxO1h10yVC64d4qIj4BGiQOU+y5'

Response:

{
  "token": "wEoJHQIwRrLwHqTqAsn0/XjzaZkVk4E8sSDwbRN2HKDlulkt6n7aHQCcvdqfX+y5",
  "expiresIn": 3600
}

Invite codes

To grant a third party access to your account, give them an invite code.

If a third party gives you a link, most fields are filled out for you.

  1. Decide if the third party can access your linked properties.
  2. Click Generate invite code.
  3. Give the code to the third party.

Create a code to give to a third party

  1. Select what the third party can access. Click Generate invite code and select the scopes of the invite code. Scopes determine what the third party can access and what they can do with it. See Scopes.
  2. Linked properties. Decide if the third party can access your linked properties, or only the properties in your account.
  3. IP whitelisting. If you add an IP address, only that IP address can access your account with the invite code. Separate multiple IP addresses with commas, for example: 
    192.168.0.1, 127.0.0.1, 2001:0db8:85a3:0000:0000:8a2e:0370:7334
  4. Create the invite code. Click Generate invite code. Copy the code and give it to the third party.

Expected result: The code shows in the table. Invite codes expire after 24 hours, so the third party needs to exchange it for a refresh token before then.

If you are a third party that needs invite codes from users, give users a link that prefills the form with the scopes you need.

  1. Select the scopes you need.
  2. Click the button in the bottom left corner to see your customised link.

Tip: You can prefill a whitelisted IP address in the same way.

Scopes

Scopes limit what your token can do. Each category of API endpoint (except /authentication) needs a corresponding scope. Scopes are set when you create an invite code and can't be changed later: to change them, create a new invite code with the scopes you want and exchange it for a new token.

Scope Access Endpoints
bookings Basic booking information GET /bookings
POST /bookings
bookings-personal Personal information, in addition to the basic information granted by the bookings scope GET /bookings
POST /bookings
GET /bookings/messages
POST /bookings/messages
PATCH /bookings/messages
bookings-financial Financial information, in addition to the basic information granted by the bookings scope GET /bookings
POST /bookings
inventory Inventory GET /inventory/offers
GET /inventory/availability
GET /inventory/calendar
POST /inventory/calendar
properties Properties GET /properties
POST /properties
accounts Accounts GET /accounts
POST /accounts

Subcategory scopes

Some categories have additional scopes that allow access to personal or financial information. For example, the bookings scope grants access to a booking's basic information, such as the check-in and checkout dates. To access personal information, such as the name of a guest, you need the bookings-personal scope. To access the invoice of a booking, you need the bookings-financial scope.

Scope methods

Each scope also needs a method:

  • read:bookings grants read access to bookings, so your token can retrieve bookings via the API.
  • write:bookings is needed to create a new booking or modify bookings.
  • all is a shortcut that grants access to all methods. For example, all:bookings allows reading, updating, creating and deleting bookings.

Linked properties

By default, tokens don't give access to linked properties and their bookings. To access properties that aren't in your account, tick Allow linked properties when you select the scopes for the token.

Note: Properties must be linked in Account Management > Manage Account > Manage Property. Other methods of linking properties aren't supported in API V2.

POST requests

Create or modify multiple items

All POST endpoints accept an array of items (an item may be a booking, message, property and so on), so you can create and modify multiple different items in one request. Every existing "POSTable" item has an id field that uniquely identifies it.

  • To create a new item, don't include an id.
  • To modify an existing item, include its id.

Subitems

Some items can contain subitems. For example, a booking may contain an "invoice item" and an "info item". Subitems generally work in the same way as their parent items. Deleting a subitem needs the WRITE scope method; deleting a subitem's parent item needs the DELETE scope method.

To add a new subitem to an item, include the subitem without an id. Example: add a new info item to a booking:

[
    {
        "id": {bookingId},
        "infoItems": [
            {
                "code": "this will create",
                "text": "a new info item"
            }
        ]
    }
]

To update an existing subitem, include the subitem's id. Example: update a booking's info item:

[
    {
        "id": {bookingId},
        "infoItems": [
            {
                "id": {infoItemId},
                "text": "this info item will have its text changed"
            }
        ]
    }
]

To delete a subitem, include only the subitem's id. Example: delete a booking's info item:

[
    {
        "id": {bookingId},
        "infoItems": [
            {
                "id": {infoItemId},
            }
        ]
    }
]

Responses

All POST requests have a standard response: an array with one response item for each item in the request, in the same order as the items were sent. Each response item contains a success boolean field, which is false if there were any errors in processing the item.

Note: success being false doesn't necessarily mean nothing has changed. For example, if you post a valid booking with an invalid info item, the booking is created but the info item isn't. success is false in this case because there was an error.

A response item may also contain one or more of these fields:

Field Contains
New Information about newly created items and subitems. For example, the id of a newly created booking, or the id of a new info item for an existing booking.
Modified Information about modified items and subitems. For example, if the departure date of a booking is changed, this field has information confirming the change.
Errors Information about fatal issues with an item or subitem in the request. An error means an attempt was made to create or change an item or subitem, but the attempt failed.
Warnings Information about non-fatal issues with an item in the request. A warning means an item or subitem was created or changed, but, for example, a non-required field had invalid data.
Info General information about what has happened to the request.

Example: POST two messages for different bookings:

[
    {
        "bookingId": 1111111,
        "message": "a message"
    },
    {
        "bookingId": 2222222,
        "message": "a different message"
    },
]

Example: response order for the request above:

[
    {
        "success": true,
        "info": [
            {
                "message": "information about the message for booking 1111111"
            }
        ]
    },
    {
        "success": false,
        "errors": [
            {
                "message": "an error about the message for booking 2222222"
            }
        ]
    }
]

Endpoints

For the full schema and examples of each endpoint, see beds24.com/api/v2.

Bookings

Endpoint Description
GET /bookings Get bookings matching specified criteria.
POST /bookings Create or update bookings. See Add or remove bookings from a group booking and Enable Stripe payment actions with stripeToken.
DELETE /bookings Delete bookings by id.
GET /bookings/messages Get messages for a booking.
POST /bookings/messages Send messages or mark them as read. Only works for messages for an OTA booking, not bookings made directly from the booking page.
PATCH /bookings/messages Make changes in all messages in a selection.
GET /bookings/invoices Get invoices for bookings.

Add or remove bookings from a group booking

Add or remove a booking from a group booking with the masterId parameter, without using the action makeGroup.

  • To add a booking to a group booking, set the master id of the group booking in masterId, like this in your request: "masterId": 1234567. This modifies the booking to add it to the group.
  • To remove a booking from a group booking, set masterId to null, like this in your request: "masterId": null.

Enable Stripe payment actions with stripeToken

For direct bookings where payment is processed via Stripe, the stripeToken field must be set. The token is typically generated when card details are collected securely through Stripe, so sensitive information isn't handled or stored by Beds24.

  • If a booking has a stripeToken, a Stripe button shows on the Charges and Payments tab. Click it to view Stripe transactions and all saved cards for the booking.
  • For bookings paid with other methods, the field stays empty unless card details are later collected via Stripe.

Inventory

These endpoints only work if a price is set for the property or room. To set up prices, see How to setup Daily Prices or How to setup Fixed Prices.

Endpoint Description
GET /inventory/rooms/offers Get offers based on specified criteria.
GET /inventory/rooms/availability Get the availability status of dates.
GET /inventory/rooms/calendar Get per-day values from the calendar.
POST /inventory/rooms/calendar Modify per-day calendar values.

Properties

Endpoint Description
GET /properties Get properties matching specified criteria. See Prices.
POST /properties Create or modify properties. See Price rules.
DELETE /properties Delete properties by id.
DELETE /properties/rooms Delete rooms of properties by id.

Note: To update room-level settings with POST /properties, include the property id in your request. If it's missing, the system may return an error or incorrectly report success without applying any changes.

Prices

To get price setup rules, include the includePriceRules parameter in GET /properties, like this:

/api/v2/properties?includePriceRules=true

A room can have up to 16 prices. In the control panel, set them in Prices > Daily Price Rules. In the API, access them through GET and POST /inventory/calendar:

{
  "data": [
    {
      "calendar": [
        {
          "price1": 100,
          "price2": 300,
          "price3": 200,
          ...
        }
      ]
    }
  ]
}

Price rules

You can't create new price rules yet, but you can modify price rules with POST /properties. Example: modify the name of the price rule:

{
  "id": propertyid,
  "roomTypes": [
    {
      "id": roomid,
      "priceRules": [
        {
          "priceruleid": 1,
          "name": "-INSERT NAME HERE-"
        }
      ]
    }
  ]
}

Accounts

Endpoint Description
GET /accounts Get accounts and sub-accounts.
POST /accounts Create or modify accounts.

Webhooks

Endpoint Description
POST Webhooks - bookings The webhook payload sent to your URL from the booking webhook in Settings > Properties > Access > Booking Webhook.

Channels

Endpoint Description
GET /channels/settings Get channel-specific settings.
POST /channels/settings Modify channel settings.
GET /channels/airbnb/users Get all Airbnb user ids connected to an account.
GET /channels/airbnb/listings Get all Airbnb listings for a specified Airbnb user id.
POST /channels/airbnb Perform actions at Airbnb.
POST /channels/booking Perform actions at Booking.com.
GET /channels/booking/reviews Get reviews from Booking.com.
POST /channels/stripe Perform actions at Stripe. See Collect card payments with Stripe.
GET /channels/stripe/paymentMethods Get payment methods for a booking from Stripe.
GET /channels/stripe/charges Get charges for a booking from Stripe.

Collect card payments with Stripe

You can collect the card directly with Stripe, so you don't have any PCI DSS obligations. The process is basically the same as creating a normal Stripe Checkout session, except that creating it through the Beds24 API connects the payment to the booking. The Stripe checkout session creates a Stripe checkout page that receives payments into the property's Stripe account.

  1. Make the booking via API and get the new booking ID.
  2. Call API V2 POST /channels/stripe with the booking ID and any charges you want to collect. Pass the line_items, success_url and cancel_url in the format the Stripe API needs to create a checkout session. The line_items format is defined in the Stripe documentation: Stripe Checkout.
    • If the booking already exists, pass its booking ID as bookId. Any payments to this checkout session are added to the booking's invoice.
    • Setting "capture":false authorises the amount but doesn't collect the funds.
  3. POST /channels/stripe returns the session data you need to instantly create a Stripe payment checkout. Use the session id to create the Stripe checkout in your app, following Stripe's instructions and the Stripe API or widgets: Stripe Checkout Sessions API.
  4. When you initialise Stripe in your app, use this pk_live key and the stripe_account value (acct_) from the session response: 
    var stripe = Stripe('pk_live_zWSW2ykzZoq4mYcKg9c8jmHS', {
stripeAccount: 'acct_stripe_acccont-value-from-response'
});

Expected result: The booker securely enters their card while on your site. The card is automatically connected to the booking ID and can be charged by API or manually from the control panel.

For more information, see Stripe's checkout documentation.

Webhooks

Enable booking webhooks for API V2 in Settings > Properties > Access > Booking webhooks. For other webhooks, including non-API V2 webhooks, see Webhooks.

Credit limits and payload size

The API credit limit restricts how much you can use the API in a 5-minute window. By default it's 100 credits per 5 minutes.

  • Each API request has a cost, calculated dynamically depending on how complex the request is.
  • If you go over the limit, you can't make more API calls until the 5-minute period is over.
  • The limit is at account level: tokens under the same account share the same credit limit. Different accounts, including sub accounts, have separate credit limits.
  • To increase the limit, contact the support team through the ticketing system. Increasing it to 200 credits per 5 minutes costs 10€ per month, and the limit can be changed or increased as much as you need.

Information about your credit limit is in these API response headers:

Header Value
x-five-min-limit-remaining The number of credits you have left for this 5-minute period
x-five-min-limit-resets-in The number of seconds until the current period resets
x-request-cost The number of credits this request cost

A POST payload is limited to approximately 1MB, and to 10000 top-level JSON array items per POST request.

Best practices

  • Reuse tokens. Tokens last 24 hours, so you don't need a new token for each request. Getting a new token costs credits, so use an existing one when possible.
  • Use webhooks instead of frequent GET requests. To get data such as new messages or bookings when they come in, use webhooks to be notified as soon as a new message, booking and so on arrives.
  • Send in bulk. If you send large amounts of information, such as messages, at high frequency, group them in bulk POST requests instead of one request per message. For example, send one POST request every 30 seconds with all messages from the past 30 seconds.
  • Get or send several items in one call. To retrieve information about several things, such as several properties, specify multiple IDs in one request instead of one GET request per property. The same applies to POST: you can create or update multiple properties in one call.

Common tasks

Task How
Make a new property, room, booking and so on Don't include an id in your POST request. See the examples for Properties/Rooms and Bookings.
See or set price rules Price rules are under /properties. To retrieve them, set the includePriceRules parameter to true.
See or set offers Offer setup rules are under /properties. To retrieve them, set the includeOffers parameter to true. Retrieve offers (calculated prices for specific dates) through the /inventory/rooms/offers endpoint.
See or set prices, min stay, availability and so on for specific dates, like in the calendar Read and set these per-date values through the /inventory/rooms/calendar endpoint.
Check if a date is available for check-in or check-out Use GET /inventory/rooms/availability. See Check-in and check-out availability.
Send pictures Not possible yet. This feature is coming soon.
Use only the channel management through the API Contact the Beds24 support team and open a ticket with your questions.
See the possible values for a booking's apiSourceId (API Source ID) See API V2.0 apisourceids.
See examples of how to use the API See beds24.com/api/v2.
See what changed in API V2 See the API V2.0 changelog.

Check-in and check-out availability

GET /inventory/rooms/availability returns whether dates are available. If a date is false, it isn't available for check-in. However, if the previous date is available, the date is available for check-out.

In this example, a booking can't check in on 2024-01-03 because that date is unavailable. Because the previous date, 2024-01-02, is available, 2024-01-03 is available for check-out.

"availability": {
  "2024-01-01": true,
  "2024-01-02": true,
  "2024-01-03": false
}

Coming soon, alpha and beta endpoints

Label Meaning
Coming soon The endpoint hasn't been developed yet and isn't usable. The schema indicates how the endpoint will eventually work, but the final version may change.
Alpha The endpoint is usable but still being developed, and not all features are implemented yet. Breaking changes are unlikely but may occur if necessary.
Beta The endpoint is mostly finished and being tested, and most features are implemented. Breaking changes aren't planned.

Related Articles

Related to

Was this article helpful?
0 out of 0 found this helpful

How to Contact us :