# Contacts

Guests and other contacts of the organization

Endpoint: `https://api.bookingmood.com/v1/contacts`, supporting `GET`, `POST`, `DELETE`, `PATCH`. Authenticate with the header `Authorization: Bearer YOUR_API_KEY` (see [authentication](https://www.bookingmood.com/be-BY/api-reference/authentication.md)).

## The contact object

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `uuid` | Unique identifier. |
| `creator_id` | `uuid \| null` | Identifier of the user that created the contact. References [`user_profiles.user_id`](https://www.bookingmood.com/be-BY/api-reference/user_profiles.md). |
| `organization_id` | `uuid` | Identifier of the organization this contact is defined in. References [`organizations.id`](https://www.bookingmood.com/be-BY/api-reference/organizations.md). |
| `created_at` | `timestamp with time zone` | Creation timestamp. Read-only: set by the database. |
| `updated_at` | `timestamp with time zone` | Last modification timestamp. Read-only: set by the database. |
| `address` | `text` | Address of the contact, as a single line. Read-only: set by the database. |
| `avatar` | `text \| null` | URL of the avatar image. |
| `city` | `text` | City of the contact. |
| `company_name` | `text` | Company name of the contact, for invoices. |
| `country` | `text` | Country of the contact. |
| `country_code` | `CountryCode \| ""` | ISO 3166-1 alpha-2 country code of the contact, or empty. |
| `e_invoice_address` | `text` | E-invoicing address of the contact. |
| `e_invoice_scheme` | `text` | Scheme of the contact's e-invoicing address, e.g. a Peppol scheme. |
| `email` | `text` | Email address of the contact. |
| `first_name` | `text` | First name of the contact. |
| `fts` | `tsvector` | Full text search index. Read-only: set by the database. |
| `language` | `Language \| null` | Language of the contact. |
| `last_name` | `text` | Last name of the contact. |
| `meta` | `Array<{ key: string, value: string }>` | Metadata of the contact. |
| `name` | `text` | Full name of the contact. Read-only: set by the database. |
| `notes` | `text` | Private notes about the contact. |
| `phone` | `text` | Phone number of the contact. |
| `province` | `text` | Province of the contact. |
| `sms_opt_in` | `boolean` | Whether the contact agreed to receive text messages. |
| `state` | `text` | State of the contact. |
| `street` | `text` | Street address of the contact. |
| `street2` | `text` | Second line of the street address of the contact. |
| `zip` | `text` | Postal code of the contact. |

```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "creator_id": "00000000-0000-0000-0000-000000000000",
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "created_at": "2026-10-30T23:37:06.265Z",
  "updated_at": "2026-10-30T23:37:06.265Z",
  "address": "",
  "avatar": "",
  "city": "",
  "company_name": "Summer cottage",
  "country": "NL",
  "country_code": "NL",
  "e_invoice_address": "",
  "e_invoice_scheme": "",
  "email": "guest@example.com",
  "first_name": "John",
  "language": "en-US",
  "last_name": "Doe",
  "meta": {},
  "name": "Summer cottage",
  "notes": "A short description.",
  "phone": "+31612345678",
  "province": "",
  "sms_opt_in": true,
  "state": "",
  "street": "",
  "street2": "",
  "zip": ""
}
```

### Types

```typescript
type Language = 
  | "be-BY"
  | "bg-BG"
  | "cs-CZ"
  | "da-DK"
  | "de-DE"
  | "en-GB"
  | "en-NZ"
  | "en-US"
  | "es-ES"
  | "eu-ES"
  | "fr-FR"
  | "gr-EL"
  | "he-IL"
  | "hr-HR"
  | "hu-HU"
  | "it-IT"
  | "ja-JP"
  | "lt-LT"
  | "lv-LV"
  | "nl-NL"
  | "nn-NO"
  | "pl-PL"
  | "pt-BR"
  | "ro-RO"
  | "ru-RU"
  | "sk-SK"
  | "sl-SI"
  | "sr-Cyrl"
  | "sr-Latn"
  | "sv-SE"
  | "tr-TR"
  | "uk-UA";
```

### Related resources

Embed related resources with the [`select` parameter](https://www.bookingmood.com/be-BY/api-reference/selecting.md), e.g. `select=*,organizations(*)`. Resources related through more than one column need the column as a hint, like `table!column(*)`.

| Embed | Type | Description |
| --- | --- | --- |
| `organizations(*)` | `object \| null` | The [organization](https://www.bookingmood.com/be-BY/api-reference/organizations.md) referenced by `organization_id`. |
| `user_profiles(*)` | `object \| null` | The [user profile](https://www.bookingmood.com/be-BY/api-reference/user_profiles.md) referenced by `creator_id`. |
| `contact_bookings(*)` | `array` | The [contact bookings](https://www.bookingmood.com/be-BY/api-reference/contact_bookings.md) referencing this contact through `contact_bookings.contact_id`. |

## List contacts

`GET /v1/contacts`

Filter on any attribute with `column=operator.value` (see [filtering](https://www.bookingmood.com/be-BY/api-reference/filtering.md)). Choose columns and embed related resources with `select` (see [selecting](https://www.bookingmood.com/be-BY/api-reference/selecting.md)), and sort and paginate with `order`, `limit` and `offset` (see [sorting and pagination](https://www.bookingmood.com/be-BY/api-reference/sorting-pagination.md)).

```bash
curl -X GET "https://api.bookingmood.com/v1/contacts?select=*&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Responses:

- `200`: A list of contacts with the selected columns. `206` when the list is a partial range.
- `400`: The request is malformed, for example an unknown column or an invalid filter.
- `401`: The API key is missing or invalid.

## Create contacts

`POST /v1/contacts`

Insert one contact or an array of contacts. The body is a `Partial` contact object, so columns with a default can be left out. Read-only attributes can't be written.

```bash
curl -X POST "https://api.bookingmood.com/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "00000000-0000-0000-0000-000000000000",
    "city": "",
    "company_name": "Summer cottage",
    "country": "NL",
    "country_code": "NL",
    "e_invoice_address": "",
    "e_invoice_scheme": "",
    "email": "guest@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "meta": {},
    "notes": "A short description.",
    "phone": "+31612345678",
    "province": "",
    "sms_opt_in": true,
    "state": "",
    "street": "",
    "street2": "",
    "zip": ""
  }'
```

Responses:

- `201`: The newly created contacts with the selected columns.
- `400`: The request is malformed, for example an unknown column, an invalid filter or an invalid body.
- `401`: The API key is missing or invalid.
- `403`: The API key has no permission for this change, for example when writing rows of another organization.
- `409`: The change conflicts with existing data, for example a duplicate key or a reference to a row that does not exist.

## Delete contacts

`DELETE /v1/contacts`

Filter on any attribute with `column=operator.value` (see [filtering](https://www.bookingmood.com/be-BY/api-reference/filtering.md)). Without filters, this request deletes all contacts you have access to. Always filter on at least one column, e.g. `id=eq.{id}`.

```bash
curl -X DELETE "https://api.bookingmood.com/v1/contacts?id=eq.00000000-0000-0000-0000-000000000000" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Responses:

- `200`: The deleted contacts with the selected columns. `204` without a body when sending the header `Prefer: return=minimal`.
- `400`: The request is malformed, for example an unknown column or an invalid filter.
- `401`: The API key is missing or invalid.
- `403`: The API key has no permission for this change, for example when writing rows of another organization.

## Update contacts

`PATCH /v1/contacts`

Filter on any attribute with `column=operator.value` (see [filtering](https://www.bookingmood.com/be-BY/api-reference/filtering.md)). Without filters, this request updates all contacts you have access to. Always filter on at least one column, e.g. `id=eq.{id}`. The body holds the attributes to change.

```bash
curl -X PATCH "https://api.bookingmood.com/v1/contacts?id=eq.00000000-0000-0000-0000-000000000000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "city": ""
  }'
```

Responses:

- `200`: The updated contacts with the selected columns. `204` without a body when sending the header `Prefer: return=minimal`.
- `400`: The request is malformed, for example an unknown column, an invalid filter or an invalid body.
- `401`: The API key is missing or invalid.
- `403`: The API key has no permission for this change, for example when writing rows of another organization.
- `409`: The change conflicts with existing data, for example a duplicate key or a reference to a row that does not exist.

Errors have a JSON body with a `code`, `message`, `details` and `hint`. See the [introduction](https://www.bookingmood.com/be-BY/api-reference.md) for more on errors. The full API is described by the OpenAPI spec at https://api.bookingmood.com/v1/openapi.json.