Skip to content

Writing data

How the Bookline API changes data: versions with ETag and If-Match, safe retries with Idempotency-Key, the write limit and why a write can be refused.

Some domains can be changed through the API: venues, agents, knowledge bases, contacts, campaigns and team members. Every write follows the rules on this page; each domain’s page says which fields it takes.

Method What it does Answer
POST Creates a resource. Needs an Idempotency-Key 201 with the new resource and its ETag
PATCH Changes the fields you send. Needs If-Match 200 with the resource as stored and its new ETag
DELETE Deletes a resource. Needs If-Match 204, no body
  • The key needs the write scope of the domain (venues:write, contacts:write…), and its owner’s access in the portal must allow the change. See what each key can change.
  • A key with a write scope expires within 90 days.
  • The body is JSON, sent with Content-Type: application/json. A field the route does not take, or a value outside its rules, is 422 validation_failed, and the message names the field. A body over 865,536 bytes is 413 validation_failed.
  • PATCH changes only what you send. A field you leave out stays as it is. Where a page says so, null removes a value.

Every resource you can change has a version. The detail read (GET by id) answers it in the ETag header, and so does every write.

  1. Read the resource: GET /v1/<domain>/{id}, and keep its ETag.
  2. Send it, as you received it, in the If-Match header of the PATCH or DELETE.
  3. If nobody changed the resource since your read, the write is applied. If someone did, the answer is 412 precondition_failed and nothing is written: read it again, decide again and resend with the new ETag.
Ventana de terminal
ETAG=$(curl -s -D - -o /dev/null -H "apikey: $BOOKLINE_API_KEY" "$BASE/agents/<agent_id>" | awk 'tolower($1)=="etag:" {print $2}' | tr -d '\r')
curl -s -X PATCH "$BASE/agents/<agent_id>" \
-H "apikey: $BOOKLINE_API_KEY" \
-H "Content-Type: application/json" \
-H "If-Match: $ETAG" \
-d '{"name": "Front desk"}'

A PATCH or DELETE without If-Match is 428 precondition_required. The answer to a PATCH carries the new ETag, so you can make a second change without reading again.

A write that changes nothing (the same name, a campaign already paused) writes nothing and answers the resource with its current ETag.

A POST creates something, so retrying it after a network error could create it twice. To avoid that, every POST needs an Idempotency-Key header: a value you choose, unique per create, of 1 to 255 printable characters without spaces (a UUID works well). Without it, the answer is 400 invalid_query.

Ventana de terminal
curl -s -X POST "$BASE/contacts" \
-H "apikey: $BOOKLINE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"phone": "+34600111222", "given_name": "Ana"}'

Bookline remembers each key for 24 hours:

You resend the same key… Answer
With the same request, after it was applied The first answer again, with the resource as it is now and the header Idempotent-Replayed: true. Nothing is created twice
With the same request, after it was refused with a 4xx It is processed again: fix the request and resend it with the same key
With another body, or for another customer 409 conflict: “this Idempotency-Key was used for a different request”
While the first request is still running, or after it stopped without finishing 409 conflict: check whether it was applied before using a new key
After an answer that does not say whether it was applied (a 502, a 504, or a 503 from the service behind) 409 conflict: “the request with this Idempotency-Key may have been applied; check before sending it with a new key”
After the created resource was deleted 409 conflict: the request was applied, but what it created no longer exists

So, when a create times out or fails with a 5xx: list the resource first (the knowledge bases list and the contacts list are never cached) and create again with a new key only if it is not there.

Writes have their own limit of 10 per minute per key, apart from the 60 reads. A write whose answer is personal data (creating or changing a contact, changing a team member’s access) also counts in the personal-data limit of 30 per minute, and is recorded like a personal-data read. Over the limit, the answer is 429 rate_limited with Retry-After. See Errors and rate limits.

Writes are never cached, and neither is the detail read of anything you can change: a GET by id right after a write returns the new data. Other lists can take up to a minute to show it.

Bookline records every write with the key that made it.

Besides the general error codes, a write can be refused by a rule of the domain. The message then explains the reason:

Status Message Where
403 This needs a key with access to the whole customer, not only to some venues. Writes on contacts, campaigns, team members; creating a knowledge base
403 A key cannot change its own owner’s access. Team members
403 Only a customer key, or the key of one of the customer’s own users holding ADMIN access to ALL of it, can change team access. Team members
403 This member is a partner of the customer: their access is set by Bookline. Team members
409 The customer must keep at least one of its own users (not a partner) with ADMIN access to ALL. Team members
422 access: every venue_ids entry must be a live venue of the customer. Team members
409 Only a TEXT knowledge base can be changed or deleted through the API: change this one in the portal. Knowledge bases
409 A venue still uses this knowledge base: unlink it from its venues first. Knowledge bases
409 Another contact of the customer already has this phone or email. Contacts
422 A contact needs a valid phone number or an email. Contacts
409 The venue’s references do not allow this change: a booking integration it uses was deleted, or one of its agents needs a phone or an email in its contact details. Venues