Skip to content

Venues

Your venues: the list of ids, each venue's detail, and how to change its name, website or contact details.

The venues endpoints return your venues and let you change a venue’s name, website and contact details. Reading needs venues:read (the list also works with metrics:read); changing needs venues:write.

Endpoint Route Scope
List venues GET /v1/venues venues:read or metrics:read
One venue GET /v1/venues/{venue_id} venues:read
Change a venue PATCH /v1/venues/{venue_id} venues:write

In the examples, $BASE is https://api.bookline.ai/v1 and $BOOKLINE_API_KEY is your key, as in the quick start.

GET /v1/venues returns, in data[], the id and name of the venues your key reads. Use those ids in venue_ids on the other routes. Accepts only customer_id.

Ventana de terminal
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/venues"

GET /v1/venues/{venue_id} returns one venue’s detail, with an ETag header: the version to send as If-Match when you change it.

Ventana de terminal
curl -s -i -H "apikey: $BOOKLINE_API_KEY" "$BASE/venues/<venue_id>"
Field What it is
id, name The venue’s identifier and name
type Its kind: RESTAURANT, HOTEL, CAMPING, APARTMENTS, HOSTEL, TAXI_DISPATCHER, OTHER; others may appear
subtype Its subtype, if one
parent_venue_id The venue this one is inside of, e.g. a hotel’s restaurant
language The venue’s language as set in the portal: SPANISH, CATALAN, ENGLISH…
currency ISO 4217 code, e.g. EUR
timezone IANA zone of the venue
country ISO 3166-1 alpha-2; null when unknown
city, street_address, postal_code The address
website The venue’s website
contact_details[] Ways to reach the venue: channel (PHONE_NUMBER, WHATSAPP_BUSINESS_PHONE, EMAIL, FACEBOOK, INSTAGRAM; others may appear) and value

A venue that is not your customer’s, or outside the venues your key is limited to, is 404 not_found.

PATCH /v1/venues/{venue_id} changes the fields you send and leaves the rest as they are. Send at least one; an empty body {} is 422 validation_failed. Send the venue’s ETag as If-Match (see Writing data).

Field Rules
name 1 to 200 characters. A new name also replaces how the agents pronounce it: set a custom pronunciation in the portal if you need one
website An http:// or https:// URL, up to 2048 characters, or null to remove it
contact_details Up to 20 entries of channel and value (up to 320 characters). channel is PHONE_NUMBER, WHATSAPP_BUSINESS_PHONE, EMAIL, FACEBOOK or INSTAGRAM. A phone must be a valid number in E.164, starting with + and its country code, e.g. +34600111222; an email must be an email address
Ventana de terminal
curl -s -X PATCH "$BASE/venues/<venue_id>" \
-H "apikey: $BOOKLINE_API_KEY" \
-H "Content-Type: application/json" \
-H 'If-Match: "<etag>"' \
-d '{"website": "https://www.example.com", "contact_details": [{"channel": "PHONE_NUMBER", "value": "+34910000000"}, {"channel": "EMAIL", "value": "hello@example.com"}]}'

The answer is the venue as stored, with its new ETag.

  • contact_details replaces the list. The entries you send replace every stored entry on the five channels above. Entries on other channels, set in the portal (e.g. Telegram), are kept.
  • Send back what you read in the right form. A phone stored in national format or a website stored without https:// (both possible when they were set in the portal) are read back as stored: when you send them back, write the phone in E.164 and the website with https://.
  • 409 conflict when the venue’s setup does not allow the change: a booking integration it uses was deleted, or one of its agents needs a phone or an email in the contact details. Fix it in the portal, or keep that entry in the list.
  • Endpoints: every route, and the metrics that take venue_ids.
  • Writing data: versions, retries and the write limit.