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.
List venues
Section titled “List venues”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.
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/venues"One venue
Section titled “One venue”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.
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.
Change a venue
Section titled “Change a venue”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 |
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_detailsreplaces 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 withhttps://. - 409
conflictwhen 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.
Related
Section titled “Related”- Endpoints: every route, and the metrics that take
venue_ids. - Writing data: versions, retries and the write limit.
