API: build your own offer website and course planner
You can display offers on your own website or in an external course planner and let the actual booking continue to take place in edoobox. This guide describes a server-side synchronization with your own detail pages, specifically adopted texts, and a local cache.
Separate display, synchronization, and booking
The website backend reads the released offer data via the API and stores the required fields in its own database. The public website reads this prepared content. The registration button opens the booking path provided by edoobox. The binding check of bookability, price, capacity, and prerequisites continues to take place in the edoobox booking process.
For a ready-made embedded offer, use the WordPress plugin or Preview/Share and iFrame. A custom API website requires development for data storage, updates, navigation and SEO. Rendered templates return HTML; this is a different output format from the raw data used here.
Prepare access and publication scope
- Create your own API key and limit it to the required read permissions, for example for offers, texts, and if needed sessions, locations, or prices.
- Set up the server-side authentication with the correct host, token, and
edid. - Determine which offers and languages may appear on the website. An administrative API read permission is not an automatic public release of all read content.
- Store the edoobox offer ID as an unchanged assignment to your own website page.
- Define an update frequency and a behavior for missing or outdated data.
Internal offers and their access codes should not be included unchecked in a public data set. Only adopt the explicitly released fields; do not pass API access data to the website browser.
Read offer data completely and language-specifically
Use GET /v2/offer/list and select the required fields. A starting point is id, number, name, status, date_start, date_end, archive, trash, shortdescription, and image. Explicitly set language to a used language, for example de. The API-v2 reference describes the individual resources.
Read all pages via limit.start, limit.reply, and the response data. The guide Retrieve lists completely explains the structure. Use the same filters and a unique sorting over a complete run.
shortdescription is a derived short description. It is not a freely named additional text and not a replacement for the complete HTML description. For your own editorial summary, use an agreed additional text.
Read description and own additional texts via the text resource
The texts are their own data records. GET /v2/text/list supports the fields id, resource, resource_id, language, and value. Filter the text type, the offer ID, and the language together:
| Desired content | Value for resource |
|---|---|
| Complete description | description |
| Additional text 1 | additionaltext1 |
| Additional text 2 | additionaltext2 |
| Additional text 3 | additionaltext3 |
// offerId is taken unchanged from the offer response.
const url = new URL('https://app2.edoobox.com/v2/text/list');
url.searchParams.set('fields', JSON.stringify([
'id', 'resource', 'resource_id', 'language', 'value'
]));
url.searchParams.set('filter', JSON.stringify([
{ property: 'resource', expression: '=', value: 'additionaltext1' },
{ property: 'resource_id', expression: '=', value: offerId },
{ property: 'language', expression: '=', value: 'de' }
]));
url.searchParams.set('response_type', 'array');
// Fetch on the server using the same edid and Authorization headers.The matching entry contains its text in value. An empty result must be treated as a missing text version; the integration deliberately decides on a replacement text or hiding. A category text is its own entry via the category ID. It is not automatically loaded by this offer filter.
For example, agree that additional text 1 contains the external course planner’s editorial summary while the description remains the detailed course information. First check other uses of the additional texts in emails and PDFs. Changing the text also affects those outputs when they use the same text. Process HTML appropriately and securely in the target system; HTML content is not automatically plain text.
Adopt current booking links
Read GET /v2/offer/{id}/shareurl for the offer. The response contains the intended direct booking link under data.shareurl.url.booknow and the language-specific offer paths under data.shareurl.url.segment. Use the actually delivered values. The selection in the Preview/Share dialog is additionally helpful if you need a complete public language, category, or embedding link.
Link your own detail page permanently through the offer ID and update the edoobox URLs during synchronization. Names, category paths and language can change; an edoobox link assembled from the visible offer name is not a reliable alternative. Do not use a personal booking session or participant access link as a general registration button.
For a sub-offer of a multi-offer, the share process delivers the booking path of the parent multi-offer. Therefore, check the actual selection in the target process. Internal codes from a share response may only reach the intended protected distribution.
Check image URLs, variants, and original proportions
The offer field image can be false. For an assigned image, it contains, among other things, name, type, url, and url300. Use the returned URLs unchanged. image.url has no general guarantee for a fixed pixel size or for the unchanged original file.
edoobox processes images differently depending on the upload path and stored image type. Existing preview images may be cropped to fixed aspect ratios; other image paths use the public source file or their own size variants. An uploaded portrait file therefore does not mean that every offer view or API URL delivers the portrait format.
| Output | What you can use |
|---|---|
| REST offer response | The actually delivered image.url and image.url300. A generic field image.original, url600 or url900 is not output here. |
| WordPress header data | The plugin uses the image variants delivered by the template for its OpenGraph output. These header data are a separate output context. |
| Social media preview image | Custom generated crops for the link preview. They are not an original image interface for your frontend. |
A manually added suffix like _900 does not work for every image type and storage. Do not build a general image contract on it. Check the actually delivered file, resolution, and proportion with multiple offers and after an image change.
If your own course planner definitely requires an uncropped original or a specific large resolution, manage this web image with a fixed assignment to the offer ID in your CMS or clarify the appropriate file retrieval for your specific integration. Upscaling a small preview does not create additional image details.
Update your own cache and handle failures
- Load the intended offers, texts, and booking links into a new prepared state. Check every API response for HTTP and functional errors.
- Adopt the new complete state only after all required pages and mandatory data have been successfully read.
- Save the timestamp of the last successful synchronization and the assignment per offer ID.
- In case of an error, retain the last checked state, mark the disturbance internally, and repeat the retrieval in a controlled manner. An error must not replace the inventory as a seemingly empty result.
- Define from which data age prices, available places, or registration buttons are no longer displayed unchecked. The edoobox booking process remains decisive for the actual completion.
An interval such as 15 minutes is a decision of your integration. It does not create a reservation in edoobox and does not guarantee unchanged places until the next run. Adjust completed, archived, or no longer released offers appropriately in your own inventory. Remove a data record only after a fully checked synchronization and not because of a failed page.
With Webhooks you can use appropriate changes as an occasion for a targeted reload. Maintain the regular synchronization. For adopted bookings, API: Synchronize bookings explains the own processing status and later cancellations.
Example: External course planner with own summary
An organization maintains complete course information in edoobox and a short editorial introduction in additional text 1. Your website backend reads offers and the German text version, stores them by offer ID, and displays its own pages under https://example.org/kurse/…. The registration button uses the last successfully loaded edoobox booking link.
After a text change, the next complete run imports the new summary. During an API outage, the last checked content remains available; handle stale availability information according to the agreed website rule. After moving an offer to another category, retrieve its current link from edoobox again. The website does not derive its own binding booking confirmation from the cache.
Check before publication and in case of errors
- Compare an offer with complete text, one without additional text, and a multilingual offer.
- Consider more than one list page, a deleted or archived offer, and a failed API page.
- Check portrait, landscape, and replaced images in the actually used resolution.
- Check the public booking link, multi-offer, and a protected area separately.
- Maintain the title, description, and canonical URL of your own website in your own CMS; distinguish OpenGraph and Canonical.
- For operation, log the timestamp, offer ID, and error category; omit credentials and unnecessary personal data.