Contacts

Beta - Contact data is currently in beta. The payload structure may still evolve before general availability. Share your feedback at support@bookingshake.com.

Get a contact

Overview

GET /contacts/{id} returns a single contact (person) by its ID - useful to back-fill a missed contact.* webhook, reconcile your CRM, or re-fetch a person on demand.

Unlike the contact webhook - which omits fields without a value - this endpoint always returns every field with an explicit null when unset (consistent with GET /accounts, GET /invoices and GET /payments). The country field is returned verbatim as entered. account_id is the raw ID of the linked account (or null) - call GET /accounts/{id} to fetch the company details. Custom fields configured for your venue are included, also with explicit null when unset. Timestamps are Unix milliseconds.

Authentication

All requests require a Bearer token (your BookingShake API key):

Authorization: Bearer YOUR_API_KEY

Path Parameters

string

required

The contact ID - the id field carried by the contact.created webhook.

Request

curl https://api.bookingshake.io/api/contacts/contact-456 \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch("https://api.bookingshake.io/api/contacts/contact-456", {
  headers: { Authorization: `Bearer ${process.env.BOOKINGSHAKE_API_KEY}` },
});
const { data: contact } = await res.json();

import os, requests

res = requests.get(
    "https://api.bookingshake.io/api/contacts/contact-456",
    headers={"Authorization": f"Bearer {os.environ['BOOKINGSHAKE_API_KEY']}"},
)
contact = res.json()["data"]

<?php
$ch = curl_init("https://api.bookingshake.io/api/contacts/contact-456");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . getenv("BOOKINGSHAKE_API_KEY"),
]);
$contact = json_decode(curl_exec($ch), true)["data"];
curl_close($ch);

Response

The contact is returned wrapped in the standard { message, data } envelope.

{
  "message": "success",
  "data": {
    "id": "contact-456",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+33612345678",
    "landline_phone": "+33145678901",
    "title": "CEO",
    "position": "Head of Events",
    "avatar": null,
    "comments": null,
    "account_id": "account-123",
    "optin_marketing": true,
    "optin_general": false,
    "address_line_1": "10 rue Example",
    "address_line_2": null,
    "postal_code": "75001",
    "city": "Paris",
    "country": "France",
    "created_at": 1731493800000,
    "custom_u1v2w3x4y5": "VIP",
    "custom_z6a7b8c9d0": null
  }
}

Data Fields

Field	Type	Description
`id`	string	Unique contact ID
`first_name`	string \| null	First name
`last_name`	string \| null	Last name
`email`	string \| null	Email address
`phone`	string \| null	Mobile phone number
`landline_phone`	string \| null	Landline phone number
`title`	string \| null	Contact’s title
`position`	string \| null	Job position
`avatar`	string \| null	Avatar image URL
`comments`	string \| null	Free-text notes about the contact
`account_id`	string \| null	ID of the account this contact belongs to
`optin_marketing`	boolean \| null	Marketing communications opt-in
`optin_general`	boolean \| null	General communications opt-in
`address_line_1`	string \| null	Address
`address_line_2`	string \| null	Address, line 2
`postal_code`	string \| null	Postal code
`city`	string \| null	City
`country`	string \| null	Country, verbatim as entered
`created_at`	number \| null	Creation timestamp, Unix milliseconds
`custom_<uuid>`	any \| null	Custom fields configured for your venue

Errors

Status	Meaning
`400`	Missing/invalid token, or missing contact id
`404`	Contact not found - it does not exist, or belongs to another venue or venues group
`429`	Rate limit exceeded (60 requests/minute)
`500`	Internal server error

A 404 is returned uniformly whenever the contact is outside your scope, so the existence of another venue’s contact is never disclosed.

Next Steps

Contact Events

Receive contact changes in real time via the contact.* webhooks

Get an Account

Fetch the company a contact is attached to

Update a contact

Overview

PATCH /contacts/{id} updates a single contact (person) by its ID. It is a partial update: only the fields you include in the body are modified, everything else is left untouched. The request body uses the same conventions as the response - the English (snake_case) field names returned by GET /contacts/{id}. So you can read a contact, change a few fields, and send them straight back. Pass null on any field to clear it.

Updating a contact automatically emits the contact.updated webhook when at least one exposed field changes. The country field is stored verbatim as provided - no ISO normalization.

Authentication

All requests require a Bearer token (your BookingShake API key):

Authorization: Bearer YOUR_API_KEY

Path Parameters

string

required

The contact ID - the id field carried by the contact.* webhooks.

Body Parameters

All body fields are optional, but at least one must be provided. String fields are trimmed and limited to 255 characters. Pass null on any field to clear it. id and created_at are read-only and ignored.

string

First name.

string

Last name.

string

Email address. Must be a valid email when provided; pass null to clear it.

string

Mobile phone number.

string

Landline phone number.

string

Contact’s title.

string

Job position.

string

Avatar image URL.

string

Free-text notes about the contact.

string

ID of an existing account (company) to link the contact to. Must reference an account within the contact’s venue or venues group, otherwise the request is rejected with 400. Pass null to unlink.

boolean

Marketing communications opt-in. Must be true, false, or null.

boolean

General communications opt-in. Must be true, false, or null.

string

Address.

string

Address, line 2.

string

Postal code.

string

City.

string

Country, stored verbatim.

string | array

Custom fields configured for your venue. A single-value field takes a string; a multi-select field takes an array of strings. An unknown custom field key is rejected with 400.

Request

curl -X PATCH https://api.bookingshake.io/api/contacts/contact-456 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "position": "Head of Operations", "phone": "+33611111111", "optin_marketing": false }'

const res = await fetch("https://api.bookingshake.io/api/contacts/contact-456", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.BOOKINGSHAKE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    position: "Head of Operations",
    phone: "+33611111111",
    optin_marketing: false,
  }),
});
const { data: contact } = await res.json();

import os, requests

res = requests.patch(
    "https://api.bookingshake.io/api/contacts/contact-456",
    headers={"Authorization": f"Bearer {os.environ['BOOKINGSHAKE_API_KEY']}"},
    json={"position": "Head of Operations", "phone": "+33611111111", "optin_marketing": False},
)
contact = res.json()["data"]

<?php
$ch = curl_init("https://api.bookingshake.io/api/contacts/contact-456");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PATCH");
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "position" => "Head of Operations",
    "phone" => "+33611111111",
    "optin_marketing" => false,
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . getenv("BOOKINGSHAKE_API_KEY"),
    "Content-Type: application/json",
]);
$contact = json_decode(curl_exec($ch), true)["data"];
curl_close($ch);

Response

The full contact is returned in its post-update state, wrapped in the standard { message, data } envelope - identical in shape to GET /contacts/{id}.

{
  "message": "success",
  "data": {
    "id": "contact-456",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+33611111111",
    "landline_phone": "+33145678901",
    "title": "CEO",
    "position": "Head of Operations",
    "avatar": null,
    "comments": null,
    "account_id": "account-123",
    "optin_marketing": false,
    "optin_general": false,
    "address_line_1": "10 rue Example",
    "address_line_2": null,
    "postal_code": "75001",
    "city": "Paris",
    "country": "France",
    "created_at": 1731493800000,
    "custom_u1v2w3x4y5": "VIP",
    "custom_z6a7b8c9d0": null
  }
}

See the Get a Contact reference for the full field descriptions.

Errors

Status	Meaning
`400`	Missing/invalid token, missing contact id, empty/invalid body, no updatable fields, a wrongly-typed value (e.g. a non-string on a string field, a non-boolean opt-in), a value over 255 characters, an invalid email, an `account_id` outside the contact’s scope, or an unknown custom field key
`404`	Contact not found - it does not exist, or belongs to another venue or venues group
`429`	Rate limit exceeded (30 requests/minute)
`500`	Internal server error

A 404 is returned uniformly whenever the contact is outside your scope, so the existence of another venue’s contact is never disclosed.

Getting Started

Webhooks

REST API

Guides

Get a contact

Overview

Authentication

Path Parameters

Request

Response

Data Fields

Errors

Next Steps

Contact Events

Get an Account

Update a contact

Overview

Authentication

Path Parameters

Body Parameters

Request

Response

Errors

Next Steps

Get a Contact

Contact Events

​Get a contact

​Overview

​Authentication

​Path Parameters

​Request

​Response

​Data Fields

​Errors

​Next Steps

Contact Events

Get an Account

​Update a contact

​Overview

​Authentication

​Path Parameters

​Body Parameters

​Request

​Response

​Errors

​Next Steps

Get a Contact

Contact Events

Get a contact

Overview

Authentication

Path Parameters

Request

Response

Data Fields

Errors

Next Steps

Update a contact

Overview

Authentication

Path Parameters

Body Parameters

Request

Response

Errors

Next Steps