Two ways: a credential for each host, or one credential for every host that approves you.
This page is for software that manages many Plum Guide hosts, such as a property management system or a channel manager.
Two ways to connect a host
- The host gives you its own credentials. The host creates a client id and secret for its Plum Guide account and enters them in your software. You use one credential for each host.
- The host approves your company. The host approves your company on the Connected software page of its Plum Guide host dashboard. You use one credential, your own, for every host that approved you.
Both ways are valid, and you can use both. The first way works like any other API credential. The rest of this page explains the second way.
Get your partner credential
Ask Plum Guide to set up your company as a software partner. We give you a client id and a client secret for your own account.
Get a token as with any other credential:
POST https://api.plumguide.com/authenticate
{ "clientId": "<your client id>", "clientSecret": "<your client secret>" }
The reply has token (already starting with Bearer ) and expiresIn in seconds. Send the token in the Authorization header. Get a new token when it expires.
How a request says which host it is for
Send the header X-Plum-Host-Id with the host's user id on each request:
Authorization: Bearer <your token>
X-Plum-Host-Id: 6f9619ff-8b86-d011-b42d-00c04fc964ff
- The request then works for that host on every endpoint: listings, availability, prices, discounts, bookings and messages.
- Only that host's listings can be read or changed.
- Without the header, a request works for your own account only.
403means the host has not approved you, or has removed the approval.503means we could not check the approval. Nothing was changed. Try again later.
The approval is checked on every request. When a host removes the approval, your next request for that host gets 403.
How you find out which hosts approved you
Call GET /v2/partner/hosts with your own token (no X-Plum-Host-Id needed):
{
"hosts": [
{ "hostId": "6f9619ff-8b86-d011-b42d-00c04fc964ff", "approvedAt": "2026-11-16T09:30:00Z" }
]
}- Each
hostIdis the value to send inX-Plum-Host-Id. - The list is oldest approval first.
- The list is empty when no host approved you, or when Plum Guide has switched off your partner account.
- To see a host's homes, call
GET /listingswith that host inX-Plum-Host-Id.
We also send you a webhook when a host approves you or removes the approval (see below). Still call GET /v2/partner/hosts at least once a day, to catch an event you missed.
Webhooks
You have one webhook configuration, on your own account. It receives the events of every host that approved you. Set it with PUT /v2/webhooks/config:
{
"isActive": true,
"endpoints": {
"bookings": "https://example.com/webhooks/bookings",
"listings": "https://example.com/webhooks/listings",
"messages": "https://example.com/webhooks/messages",
"partners": "https://example.com/webhooks/partners"
}
}The webhook configuration endpoints always use your own account, with or without X-Plum-Host-Id. Every address must use HTTPS.
Every event has HostId, the host it is for. Use it in X-Plum-Host-Id to fetch the details:
{
"EventId": "0b0c4c2e-3f6e-4b8e-9f3a-2d7c1d1f5a10",
"Timestamp": "2026-11-16T10:15:00Z",
"HostId": "6f9619ff-8b86-d011-b42d-00c04fc964ff",
"BookingCode": "BK123456"
}- Booking events carry
BookingCode. - Listing events carry
ListingId. - Message events carry
EventType(GuestMessageReceived),ConversationId,MessageIdandListingId. No message text is sent: fetch the message from the messaging endpoints. - Partner events go to your
partnersaddress. They carryEventType:PartnerApprovedwhen the host inHostIdapproved you,PartnerRemovedwhen that host removed the approval.Timestampis when the host made the change.
Checking X-Signature
When your configuration has a signing secret, each delivery has the header X-Signature: sha256=<hex>. The value is the HMAC-SHA256 of the raw request body, keyed with your signing secret, in lowercase hex. Compute it over the exact bytes you received, before you parse the JSON, and compare it in constant time. Refuse the delivery when it does not match. Rotate the secret with POST /v2/webhooks/config/secret/rotate.
Repeats and order
- Answer with a
2xxstatus within 30 seconds. Any other answer, or a time-out, makes us send the event again later. - A repeat has the same
EventId. Store theEventIdof each event you process, and drop an event you have already seen. - Events can arrive out of order. For partner events, ignore an event whose
Timestampis older than the last one you processed for thatHostId, or check the current state withGET /v2/partner/hosts.
Testing on staging
You can test all of this on staging, at https://api.stg.plumguide.io:
- Ask Plum Guide to set up your staging account as a software partner, and to connect a staging test host to you.
- Call
GET /v2/partner/hostsand use the host id inX-Plum-Host-Id. - To receive webhooks on staging, send us the domain of your test webhook receiver. Staging sends webhooks only to addresses we have added. Use a fixed address: a temporary tunnel address that changes on each restart will stop working.
