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 |
Before you write
Section titled “Before you write”- 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 422validation_failed, and the message names the field. A body over 865,536 bytes is 413validation_failed. PATCHchanges only what you send. A field you leave out stays as it is. Where a page says so,nullremoves a value.
Versions: ETag and If-Match
Section titled “Versions: ETag and If-Match”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.
- Read the resource:
GET /v1/<domain>/{id}, and keep itsETag. - Send it, as you received it, in the
If-Matchheader of thePATCHorDELETE. - If nobody changed the resource since your read, the write is applied. If someone did, the answer is 412
precondition_failedand nothing is written: read it again, decide again and resend with the newETag.
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.
Retries: Idempotency-Key
Section titled “Retries: Idempotency-Key”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.
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.
Write limit
Section titled “Write limit”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.
Reading after a write
Section titled “Reading after a write”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.
Why a write can be refused
Section titled “Why a write can be refused”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 |
Related
Section titled “Related”- Keys and scopes: the write scopes and the 90-day rule.
- Errors and rate limits: every error code and when to retry.
