Create Custom Calendar Event

Description

Creates a calendar event associated with a case, allowing internal systems to schedule case-related meetings or activities with defined time, timezone, location, and optional meeting link.

---

Endpoint

POST /api/v1/cases/{caseId}

---

Headers

Header	Required	Description
content-type	Yes	application/json
cv-api-key	Yes	Organization API key

---

Path Parameters

Name	Type	Description
caseId	UUID	Case identifier

---

Request Body

{
  "action": "CREATE_CALENDAR_EVENT",
  "calendar": {
    "title": "Quarterly Planning Meeting",
    "agentName": "custom",
    "description": "Review priorities and align on next-quarter goals.",
    "startTime": "2025-03-10T14:00:00Z",
    "endTime": "2025-03-10T15:00:00Z",
    "timeZone": "America/New_York",
    "meetingLink": "https://example.com/meet/123",
    "location": "gotomeeting_conference",
    "provider": {
      "email": "provider@example.com",
      "name": "Dr. Smith"
    }
  }
}

---

Field Reference

Root

Field	Type	Required
action	string	Yes (CREATE_CALENDAR_EVENT)
calendar	object	Yes

calendar

Field	Type	Required	Notes
title	string	Yes	Event title
agentName	string	Yes	custom
description	string	No	Agenda
startTime	ISO 8601	Yes	UTC
endTime	ISO 8601	Yes	UTC
timeZone	IANA TZ	Yes	e.g. America/New_York
meetingLink	URL	Yes	Virtual meeting
location	string	Yes	"google_conference"|"zoom_conference"|"microsoft_teams_conference"|"webex_conference"
provider	object	No	Provider information

provider

Field	Type	Required	Notes
email	string	Yes	Provider email address
name	string	Yes	Provider name

---

Example cURL

curl --request POST \
  --url http://localhost:4000/api/v1/cases/{{caseId}} \
  --header 'content-type: application/json' \
  --header 'cv-api-key: {{generated_organization_api_key}}' \
  --data '{
    "action": "CREATE_CALENDAR_EVENT",
    "calendar": {
      "title": "Quarterly Planning Meeting",
      "agentName": "custom",
      "description": "Review priorities and align on next-quarter goals.",
      "startTime": "2025-12-31T14:00:00Z",
      "endTime": "2025-12-31T15:00:00Z",
      "timeZone": "America/New_York",
      "meetingLink": "https://example.com/meet/123",
      "location": "gotomeeting_conference",
      "provider": {
        "email": "provider@example.com",
        "name": "Dr. Smith"
      }
    }
  }'

---

Success Response

{
    "status": 200,
    "success": true,
    "message": "Case calendar event created successfully",
    "data": {
        "success": true
    }
}

---

Errors

Status	Meaning
400	Invalid payload
401	Invalid or missing API key
404	Case not found
422	Time validation failed
500	Internal error

Example Error Response

A request can fail for several reasons, returning a 400 Bad Request or a specific error message.

Invalid action in the request body:

If the action field is not a recognized value like CREATE_CALENDAR_EVENT, the API will return a bad request error.

{
  "status": 400,
  "success": false,
  "message": "Invalid request",
  "error": "Invalid action"
}

Missing required fields

If the productBundle.id field is missing or empty, the API will return a specific error message.

{
  "status": 400,
  "success": false,
  "message": "Invalid request parameters",
  "error": "calendar.meetingLink, Invalid input: expected string, received undefined"
}

Case Not Found

This response is returned if no case exists with the provided caseId.

{
  "status": 404,
  "success": false,
  "message": "Invalid request",
  "error": "No Case found for provided details!"
}

---

Notes

• startTime < endTime required.
• Times are stored in UTC display uses timeZone.