Upload or remove the background photo
Sets the photo that fills a booking page behind its card, or deletes it. The body is the image itself, not JSON.
Runs any of 2 calls on your workspace.
PUT /booking-pages/{id}/background
Sets the photo that fills a booking page behind its card, or deletes it. The body is the image itself, not JSON.
Example
Needs calendar:write and emails:send. Send the bytes with their type in Content-Type: PNG, JPEG, WebP or GIF, up to 5 MB. The photo is fitted into 2560 by 1600 pixels and stored as WebP.
curl -X PUT "$OE/booking-pages/bkp_5c1e9a7b3d2f48e6a0b4c7d1/background" -H "$AUTH" \ -H "Content-Type: image/jpeg" --data-binary @office.jpgcurl -X DELETE "$OE/booking-pages/bkp_5c1e9a7b3d2f48e6a0b4c7d1/background" -H "$AUTH"{ "object": "booking_page", "id": "bkp_5c1e9a7b3d2f48e6a0b4c7d1", "slug": "intro-call", "name": "Intro call", "status": "active", "url": "https://nextmail.sh/book/intro-call", "problem": null, "config": { "description": "A first chat about your project.", "hostName": "Hana Sato", "durations": [30], "location": { "kind": "video", "value": "https://meet.example.com/hana" }, "availability": { "timezone": "Europe/Berlin", "weekly": [ [], [{ "start": 540, "end": 1020 }], [{ "start": 540, "end": 1020 }], [{ "start": 540, "end": 1020 }], [{ "start": 540, "end": 1020 }], [{ "start": 540, "end": 1020 }], [] ], "overrides": [{ "date": "2026-12-24", "ranges": [] }] }, "rules": { "noticeMinutes": 240, "horizonDays": 60, "intervalMinutes": null, "bufferBeforeMinutes": 0, "bufferAfterMinutes": 15, "dailyLimit": null }, "approval": false, "fromEmail": "hana@acme.com", "notifyHost": true, "questions": [ { "id": "notes", "kind": "long-text", "label": "Anything we should know?", "required": false, "options": [] } ], "confirmation": "", "redirectUrl": "", "appearance": { "accent": "#2563eb", "theme": "auto", "showAvatar": true, "background": "image", "fonts": { "primary": null, "secondary": null }, "backgroundImage": "https://cdn-prod.openemail.uk/booking/backgrounds/0199a1c3-0f2e-7c61-8d4a-5b1e9f7a2c36.webp" }, "guestChanges": { "cancel": true, "reschedule": true, "cutoffMinutes": 120 }, "busy": { "addresses": null, "subscriptions": true, "outOfOffice": true }, "seo": { "title": "", "description": "", "indexable": false }, "extraGuests": 0 }, "counts": { "upcoming": 3, "pending": 0 }, "away": [ { "address": "hana@acme.com", "startsAt": "2026-12-22T00:00:00.000Z", "endsAt": "2027-01-02T00:00:00.000Z" } ], "createdAt": "2026-10-13T07:00:05.870Z", "updatedAt": "2026-10-13T07:00:05.870Z"}Uploading replaces the photo there was, sets config.appearance.background to image and puts the address of the photo in config.appearance.backgroundImage.
To show a preset or a colour again and keep the photo for later, change config.appearance.background with a PATCH. A PATCH to image while no photo is uploaded answers 422 invalid_booking_page.
Removing deletes the stored photo. A page that showed it goes back to default, and removing a photo that is not set changes nothing.
An SVG, an image over 5 MB or one that cannot be read answers 422 invalid_image. A busy image service answers 503 image_busy, and a failed save 502 image_not_stored, so try again.
Google Workspace
Fastmail