---
title: "Create or update calendar event (Admin)"
description: "Create a new calendar event or update an existing one. Requires admin authentication."
---

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

Path: Channel Automation API › Calendar

`POST /api/calendar/events`

Create a new calendar event or update an existing one. Requires admin authentication.

## Authentication

Requires one of the following:

- `BearerAuth`, http, header `Authorization`, format `JWT`
- `ApiKeyAuth`, apiKey, in header, header `X-API-Key`, format `API_KEY`

## Request body

_Required._

- `workspace_id` (`post/api/calendar/events.workspace_id`; string, required) — Workspace ID
  - example `"workspace-uuid"`
- `start_time` (`post/api/calendar/events.start_time`; string, required) — Start time of the appointment
  - format `date-time`; example `"2025-07-15T09:00:00Z"`
- `end_time` (`post/api/calendar/events.end_time`; string, required) — End time of the appointment
  - format `date-time`; example `"2025-07-15T10:00:00Z"`
- `id` (`post/api/calendar/events.id`; string, optional) — Unique identifier (for updates)
  - example `"appointment-uuid"`
- `contact_id` (`post/api/calendar/events.contact_id`; string, optional) — Associated contact ID
  - example `"contact-uuid"`
- `admin_id` (`post/api/calendar/events.admin_id`; string, optional) — Admin/agent ID
  - example `"admin-uuid"`
- `event_title` (`post/api/calendar/events.event_title`; string, optional) — Title of the event/appointment
  - example `"Product Consultation"`
- `event_description` (`post/api/calendar/events.event_description`; string, optional) — Description of the event
  - example `"Initial consultation meeting"`
- `status` (`post/api/calendar/events.status`; string, optional) — Status of the appointment
  - example `"scheduled"`
- `location` (`post/api/calendar/events.location`; string, optional) — Location of the appointment
  - example `"Virtual Meeting"`
- `notes` (`post/api/calendar/events.notes`; string, optional) — Additional notes
  - example `"Customer interested in kitchen renovation"`

## Example requests

### Create new event

```json
{
  "workspace_id": "workspace-uuid",
  "event_title": "Product Consultation",
  "event_description": "Initial consultation meeting",
  "start_time": "2025-07-15T09:00:00Z",
  "end_time": "2025-07-15T10:00:00Z",
  "status": "scheduled",
  "location": "Virtual Meeting",
  "notes": "Customer interested in kitchen renovation"
}
```

### Update existing event

```json
{
  "id": "appointment-uuid",
  "event_title": "Updated Consultation",
  "start_time": "2025-07-15T10:00:00Z",
  "end_time": "2025-07-15T11:00:00Z"
}
```

## Code samples

### cURL

```bash
curl --request POST \
  --url https://api.channelautomation.com/api/calendar/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "workspace_id": "workspace-uuid",
  "event_title": "Product Consultation",
  "event_description": "Initial consultation meeting",
  "start_time": "2025-07-15T09:00:00Z",
  "end_time": "2025-07-15T10:00:00Z",
  "status": "scheduled",
  "location": "Virtual Meeting",
  "notes": "Customer interested in kitchen renovation"
}
'
```

### TypeScript

```typescript
const url = 'https://api.channelautomation.com/api/calendar/events';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', Authorization: 'Bearer <token>'},
  body: JSON.stringify({
    workspace_id: 'workspace-uuid',
    event_title: 'Product Consultation',
    event_description: 'Initial consultation meeting',
    start_time: '2025-07-15T09:00:00Z',
    end_time: '2025-07-15T10:00:00Z',
    status: 'scheduled',
    location: 'Virtual Meeting',
    notes: 'Customer interested in kitchen renovation'
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://api.channelautomation.com/api/calendar/events"

payload = {
    "workspace_id": "workspace-uuid",
    "event_title": "Product Consultation",
    "event_description": "Initial consultation meeting",
    "start_time": "2025-07-15T09:00:00Z",
    "end_time": "2025-07-15T10:00:00Z",
    "status": "scheduled",
    "location": "Virtual Meeting",
    "notes": "Customer interested in kitchen renovation"
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

## Responses

### 200

Event created or updated successfully

#### Example

```json
{
  "success": true,
  "appointment": {
    "id": "appointment-uuid",
    "contact_id": "contact-uuid",
    "admin_id": "admin-uuid",
    "workspace_id": "workspace-uuid",
    "event_title": "Product Consultation",
    "event_description": "Initial consultation meeting",
    "start_time": "2025-07-15T09:00:00Z",
    "end_time": "2025-07-15T10:00:00Z",
    "status": "scheduled",
    "location": "Virtual Meeting",
    "notes": "Customer interested in kitchen renovation"
  }
}
```

- `success` (`post/api/calendar/events.response.200.success`; boolean, optional)
  - example `true`
- `appointment` (`post/api/calendar/events.response.200.appointment`; object, optional)
  - `workspace_id` (`post/api/calendar/events.response.200.appointment.workspace_id`; string, required) — Workspace ID
    - example `"workspace-uuid"`
  - `start_time` (`post/api/calendar/events.response.200.appointment.start_time`; string, required) — Start time of the appointment
    - format `date-time`; example `"2025-07-15T09:00:00Z"`
  - `end_time` (`post/api/calendar/events.response.200.appointment.end_time`; string, required) — End time of the appointment
    - format `date-time`; example `"2025-07-15T10:00:00Z"`
  - `id` (`post/api/calendar/events.response.200.appointment.id`; string, optional) — Unique identifier (for updates)
    - example `"appointment-uuid"`
  - `contact_id` (`post/api/calendar/events.response.200.appointment.contact_id`; string, optional) — Associated contact ID
    - example `"contact-uuid"`
  - `admin_id` (`post/api/calendar/events.response.200.appointment.admin_id`; string, optional) — Admin/agent ID
    - example `"admin-uuid"`
  - `event_title` (`post/api/calendar/events.response.200.appointment.event_title`; string, optional) — Title of the event/appointment
    - example `"Product Consultation"`
  - `event_description` (`post/api/calendar/events.response.200.appointment.event_description`; string, optional) — Description of the event
    - example `"Initial consultation meeting"`
  - `status` (`post/api/calendar/events.response.200.appointment.status`; string, optional) — Status of the appointment
    - example `"scheduled"`
  - `location` (`post/api/calendar/events.response.200.appointment.location`; string, optional) — Location of the appointment
    - example `"Virtual Meeting"`
  - `notes` (`post/api/calendar/events.response.200.appointment.notes`; string, optional) — Additional notes
    - example `"Customer interested in kitchen renovation"`

### 400

Missing required fields

#### Example

```json
{
  "success": false,
  "error": "Missing contact information: provide contact_id, contact_phone, or contact_name + contact_email"
}
```

- `success` (`post/api/calendar/events.response.400.success`; boolean, optional)
  - example `false`
- `error` (`post/api/calendar/events.response.400.error`; string, optional)

### 401

Authentication required

#### Example

```json
{
  "error": "Authentication required",
  "success": false
}
```

- `error` (`post/api/calendar/events.response.401.error`; string, optional)
  - example `"Authentication required"`
- `success` (`post/api/calendar/events.response.401.success`; boolean, optional)
  - example `false`

### 403

Admin privileges required

#### Example

```json
{
  "error": "Admin privileges required",
  "success": false
}
```

- `error` (`post/api/calendar/events.response.403.error`; string, optional)
  - example `"Admin privileges required"`
- `success` (`post/api/calendar/events.response.403.success`; boolean, optional)
  - example `false`

### 500

Internal server error

#### Example

```json
{
  "error": "Internal server error",
  "details": "string",
  "success": false
}
```

- `error` (`post/api/calendar/events.response.500.error`; string, optional)
  - example `"Internal server error"`
- `details` (`post/api/calendar/events.response.500.details`; string, optional)
- `success` (`post/api/calendar/events.response.500.success`; boolean, optional)
  - example `false`


Source: https://developer.channelautomations.com/api/post-api-calendar-events/index.md