Bookboost has two public APIs. They are not two versions of the same thing: they authenticate differently, return differently shaped data, and each can do things the other cannot. Choosing the wrong one usually shows up halfway through a build, when the endpoint you need turns out not to exist. This article tells you which one your project needs before you write any code.
The short answer
If the words consent, opt-in, newsletter, campaign, SMS, or email appear anywhere in your requirements, you need v1. For everything else you need v3. Plenty of projects need both.
Work down this list and stop at the first line that matches:
Does it record consent, trigger a campaign, or send a message? Use v1.
Are you syncing data in from an upstream system, such as a PMS or your own CRM? Use v3.
Do you need rooms, rate plans, policies, reviews, or access tokens? Use v3.
Are you only reading or writing guest profiles? Either works, and v3 gives you more to work with.
None of the above? Tell us what you are building and we will point you at the right one.
How the two APIs differ
v1 | v3 | |
Base URL |
|
|
Authentication | A long-lived API key, sent as a bearer token | OAuth 2.0 client credentials. You exchange a client ID and secret for a short-lived token |
Setup effort | Paste a key into an environment variable | A token endpoint, token caching, and refresh on expiry |
Response shape | The resource, more or less directly | A strict envelope: |
Request shape | Flat JSON body | Everything wrapped in a top-level |
Errors | JSON with a message | RFC 7807 Problem Details, with a machine-readable |
High-volume sync | Not really. One call per record | Yes. Asynchronous ingest endpoints, idempotent by source ID |
Best for | Website forms, marketing automation, one-off sends | System-to-system data sync, reading operational data |
Both APIs are rate limited. Ask support for the limits that apply to your account before you plan a high-volume sync.
What only v1 can do
Everything on this list is marketing and messaging. If your project needs one of these, it needs v1, whatever else it also does.
Record consent, both opt-in and opt-out. This is the single biggest gap between the two APIs. v3 has no consent endpoints at all.
Run a double opt-in or confirmation flow, which is driven entirely by consent state.
Trigger a campaign. v3 has no campaign or messaging surface.
Send a one-off email or SMS.
Read campaign metrics.
Tag profiles. Tags are a v1 concept.
What only v3 can do
Everything on this list is operational and reservation data, plus anything at volume.
Bulk-sync from a PMS using the ingest endpoints. They are asynchronous, idempotent, and they will not overwrite newer data with older data.
Rooms, spaces, and space types.
Rate plans and pricing.
Cancellation, deposit, and no-show policies.
Guest reviews and responses, including the insights drawn from them.
Master Profiles, which give you one view of a guest across sources. Read only.
Reservation groups, for multi-room bookings.
Door and gate access tokens.
What both can do
Create and update a guest profile. v3 has far richer structure, with several emails, phone numbers, addresses, and identifiers on a single profile.
Search and list guest profiles. v3 adds sorting, operator filters, related records, and pagination metadata.
Manage lists and list membership. These are called lists in v1 and profile lists in v3, over the same underlying data.
Create and update reservations. Use v3 for anything high volume.
Manage loyalty programmes and memberships. The two are comparable here.
Using both at once
For a lot of projects this is the right answer, because the two APIs read and write the same underlying data. A profile's uuid in v1 and its _identifier.id in v3 are the same value, so you can write a guest through one API and read them back through the other with no mapping table in between.
A split that works well: the website signup form on v1, because it needs consent and the confirmation campaign; the nightly guest sync on v3, because ingest is built for volume; guest history in your own app on v3, for the richer reads; and a "your room is ready" message on v1, because only v1 can trigger a campaign.
One caveat if both systems write profiles. The three write paths across the two APIs each deduplicate differently, so the same guest can be blocked, duplicated, or updated depending only on which path wrote them. Decide which system owns creation before you build. How guest profiles are shaped in v1 and v3 sets out the three rules.
Where to go next
Setting up v3 credentials? See Authenticating with the v3 API.
Setting up v1 credentials? See API keys.
Writing profiles, or porting code between the two? See How guest profiles are shaped in v1 and v3.
Looking for an endpoint you cannot find? See What the Bookboost APIs do not do.
Building a signup form? See Add subscribers to a list via the API.
Browsing endpoints? See the reference at docs.bookboost.io/reference.
Common questions
Should a new integration default to v3? For data, yes. For marketing and messaging you have no choice, because those capabilities only exist on v1.
Which is safer to retry? v3. It supports an Idempotency-Key header on creates, and ingest is idempotent by design.
Can I reduce read traffic? Yes, on v3. It supports ETag and If-None-Match, so unchanged data comes back as a 304 with no body.
Which has better reference documentation? v3. It has a full generated OpenAPI specification that you can import into Postman or use to generate a client.
What if I need something that is on neither? Tell us the use case rather than the endpoint you were looking for. There is often a route we can point you at.
Getting help
Open Help at the bottom of the left menu and choose Talk to Us, or email support@bookboost.io. When you get in touch about API choice, tell us what you are building and what triggers it. That is usually enough for us to point you at the right one in a single reply.