Connecting many hosts

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

  1. 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.
  2. 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.
  • 403 means the host has not approved you, or has removed the approval.
  • 503 means 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 hostId is the value to send in X-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 /listings with that host in X-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, MessageId and ListingId. No message text is sent: fetch the message from the messaging endpoints.
  • Partner events go to your partners address. They carry EventType: PartnerApproved when the host in HostId approved you, PartnerRemoved when that host removed the approval. Timestamp is 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 2xx status within 30 seconds. Any other answer, or a time-out, makes us send the event again later.
  • A repeat has the same EventId. Store the EventId of 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 Timestamp is older than the last one you processed for that HostId, or check the current state with GET /v2/partner/hosts.

Testing on staging

You can test all of this on staging, at https://api.stg.plumguide.io:

  1. Ask Plum Guide to set up your staging account as a software partner, and to connect a staging test host to you.
  2. Call GET /v2/partner/hosts and use the host id in X-Plum-Host-Id.
  3. 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.