---
title: "Create Calendar Event"
method: POST
path: "/v2.0/calendar"
tags: ["Calendar V2 API"]
---

# Create Calendar Event

`POST /v2.0/calendar`

Creates either a Task or an Appointment for the target lead, selected by the 'type' field (case-insensitive TASK / APPOINTMENT).

Notes:
- Caller must have manage permission on the lead; otherwise 400 PERMISSION_DENIED (20017).
- type, leadId, content, startAt and endAt are required. taskWay is additionally required when type = TASK.
- startAt and endAt must be later than the current server time.
- The returned data.id is a composite string ('<numericId>-task' or '<numericId>-appointment') and must be used as-is when updating, finishing or deleting this entry.
- When startAt and endAt are both exactly midnight (00:00:00) in their declared offsets, an appointment is automatically marked as all-day.

## Headers

- `Authorization` string, required
- `Content-Type` string, required

## Request body

- CalendarRequestV2 — Calendar payload. type decides whether a Task or Appointment is created.
  - `type` string, required — Calendar type: TASK or APPOINTMENT
  - `content` string, required — Content/Description of the calendar event
  - `leadId` integer, required — Lead ID associated with this calendar event
  - `startAt` string — Start time in ISO8601 format with timezone. Preferred over startAtMs when both are provided.
  - `endAt` string — End time in ISO8601 format. Preferred over endAtMs when both are provided.
  - `startAtMs` integer — Start time as Unix timestamp in milliseconds. Used when startAt is not provided.
  - `endAtMs` integer — End time as Unix timestamp in milliseconds. Used when endAt is not provided.
  - `timeZoneCode` string, required — Timezone code
  - `taskWay` string — Task way type: Call, Email, Text, Other (only for TASK)
  - `assignedRole` string — Assigned role: Agent or Assistant (only for TASK)
  - `address` string — Location/Address (only for APPOINTMENT)

## Response `200`

Calendar created. The response wraps CalendarCreateResult under the 'data' key.

- CreateCalendarResponseEnvelope — Calendar creation response envelope
  - `data` CalendarCreateResult — Calendar creation result
    - `id` string — Calendar ID with type suffix
    - `type` string — Calendar type
    - `message` string — Success message

## Other responses

- `400` — Validation failure or permission denied. Includes: missing required field, invalid type or taskWay, startAt/endAt not later than now (20012 INVALID_PARAMETER); caller is not the manager of the specified lead (20017 PERMISSION_DENIED).
- `401` — Missing or invalid authentication token.
- `500` — Internal server error.

---

[API](https://skmtc.net/lofty/apis/lofty-service-open-apis.md) · [All operations](https://skmtc.net/lofty/apis/lofty-service-open-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lofty/lofty-service-open-apis/revisions/23e640467118/schema)