> ## Documentation Index
> Fetch the complete documentation index at: https://docs.daysync.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contacts

> The organization key-contact book, and the contacts attached to venues and stays.

Daysync models contacts two ways, and the distinction matters:

<CardGroup cols={2}>
  <Card title="Key contacts" icon="user">
    **People**, stored once in an organization-wide contact book and **linked** to venues and stays. A promoter used on twelve shows is one record with twelve links.
  </Card>

  <Card title="General contacts" icon="at">
    The venue's or stay's **own** emails, phone numbers, and URLs. Owned by that record and not shared.
  </Card>
</CardGroup>

So to attach a person to a venue you **create them in the book first**, then link them by ID.

All endpoints require the standard [authentication](/authentication) headers.

***

## The organization key-contact book

### List the book

```text theme={null}
GET /v1/organizations/{orgId}/key-contacts
```

**Scope:** `organization.read`

**Response `data`** — array of contacts:

```json theme={null}
[{
  "id": 1599,
  "first_name": "John",
  "last_name": "Smith",
  "email": "john.smith@example.com",
  "number": "0412345678",
  "country": "61",
  "role": "Promoter",
  "company": "Example Touring",
  "city": "Sydney",
  "url": null,
  "avatarColorType": { "id": 3, "type": "orange", "description": "orange" }
}]
```

### Add someone to the book

```text theme={null}
POST /v1/key-contacts
```

**Scope:** `accommodation.write`

**Body**

| Field           | Type          | Required | Description                      |
| --------------- | ------------- | -------- | -------------------------------- |
| `first_name`    | string        | Yes      |                                  |
| `last_name`     | string        | Yes      |                                  |
| `org_id`        | string (UUID) | Yes      | The book is organization-wide.   |
| `email`         | string        | No       |                                  |
| `number`        | number        | No       | Phone number, no country code.   |
| `country`       | number        | No       | Country calling code, e.g. `61`. |
| `role`          | string        | No       | e.g. `Promoter`.                 |
| `company`       | string        | No       |                                  |
| `city`          | string        | No       |                                  |
| `url`           | string        | No       |                                  |
| `avatarColorId` | number        | No       | An `AvatarColor` ID.             |

**Response `data`:** `{ "id": 88590, "first_name": "…", "last_name": "…", "email": "…" }`

### Update someone

```text theme={null}
PUT /v1/key-contacts/{keyContactId}
```

**Scope:** `accommodation.write`

Same fields, all optional — send only what changes. `org_id` cannot be changed.

<Warning>
  On **update**, `number` and `country` are **strings**; on **create** they are numbers. This is a long-standing quirk of the underlying API.
</Warning>

***

## Linking key contacts

```text theme={null}
GET /v1/venues/{venueId}/key-contacts
PUT /v1/venues/{venueId}/key-contacts

GET /v1/accommodation/{accommodationId}/key-contacts
PUT /v1/accommodation/{accommodationId}/key-contacts
```

**Scope:** `venues.read` / `venues.write`, `accommodation.read` / `accommodation.write`

`GET` returns the linked people, in the same shape as the book.

`PUT` links or unlinks. **Body:**

| Field          | Type  | Required | Description                |
| -------------- | ----- | -------- | -------------------------- |
| `key_contacts` | array | Yes      | The link changes to apply. |

Each entry:

| Field            | Type   | Description                |
| ---------------- | ------ | -------------------------- |
| `key_contact_id` | number | The contact from the book. |
| `operation`      | string | `ADD` or `REMOVE`.         |

<Note>
  Only the links you list change — this is not a full replace. The contact must already exist in the book; create it with `POST /v1/key-contacts` first.
</Note>

**Example**

```bash theme={null}
curl -X PUT "$BASE/v1/venues/3719/key-contacts" \
  -H "x-api-key: $KEY" -H "x-api-secret: $SECRET" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "key_contacts": [{ "key_contact_id": 88590, "operation": "ADD" }] }'
```

**Response `data`:** none.

Venue and stay create/update bodies also accept a `keyContactIds` array inline, which sets the links in the same call.

***

## General contacts

```text theme={null}
GET /v1/venues/{venueId}/contacts
PUT /v1/venues/{venueId}/contacts

GET /v1/accommodation/{accommodationId}/contacts
PUT /v1/accommodation/{accommodationId}/contacts
```

**Scope:** `venues.read` / `venues.write`, `accommodation.read` / `accommodation.write`

**Response `data`** — an array where each row carries exactly one of the three, the others `null`:

```json theme={null}
[
  { "email": { "id": 638, "label": "Box office", "email": "box@example.com", "is_google": true }, "phone": null, "url": null },
  { "email": null, "phone": { "id": 91, "label": "Front desk", "country": "61", "phone": "298765432", "is_google": false }, "url": null }
]
```

`is_google` marks a detail imported from Google Places rather than entered by a user.

### Writing them

**Body** — at least one of the three lists must be present:

| Field     | Type  | Description                                              |
| --------- | ----- | -------------------------------------------------------- |
| `emails`  | array | `{ id?, email, label, operation, is_google? }`           |
| `numbers` | array | `{ id?, number, country, label, operation, is_google? }` |
| `urls`    | array | `{ id?, url, label, operation, is_google? }`             |

`operation` is `ADD`, `UPDATE`, or `REMOVE`; `id` is required for the latter two.

<Note>
  In `numbers`, both `number` and `country` are **numbers**, not strings — `{ "number": 298765432, "country": 61 }`.
</Note>

**Example**

```bash theme={null}
curl -X PUT "$BASE/v1/venues/3719/contacts" \
  -H "x-api-key: $KEY" -H "x-api-secret: $SECRET" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "emails": [{ "email": "box@example.com", "label": "Box office", "operation": "ADD" }] }'
```

**Response `data`:** none.

As with key contacts, venue and stay create/update bodies accept `emails`, `numbers`, and `urls` inline (without `operation`, as a full replace).

***

See also: [Venues](/endpoints/venues), [Accommodation](/endpoints/accommodation), [Rooms](/endpoints/rooms).