Talk Calendar

REST API

This document describes how to integrate the Talk Calendar APIs into your service with a REST API.

You can test the features described in this document in [Tools] > [REST API Test].

User calendar

This section introduces the APIs to manage a user's calendar. To see the calendar types, read Concepts > Calendar types.

Retrieve list of calendars

Basic information

Method	URL	Authorization
`GET`	`https://kapi.kakao.com/v2/api/calendar/calendars`	Access token

Permission	Prerequisite	Kakao Login	User consent
Required	Activate Kakao Login Manage consent items	Required	Required: Refer to Usage policy

Retrieves user's all calendars (My Calendar, sub-calendar, and subscribed calendar).

You can use this API to get a calendar ID that is used to specify which calendar an event will be added to, or to retrieve the events added in the desired calendar. You can also need to use this API before editing or deleting a sub-calendar.

Send a GET request with the issued access token in the request header. If the request is successful, this API returns a list of calendars in JSON format. In the case of the calendars that other services have created, only the calendar's id is returned.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` Access token as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
filter	`String`	Type of calendar to be retrieved. One of the followings: `ALL`: All calendars are retrieved. `USER`: My Calendar and sub-calenders are retrieved. `SUBSCRIBE`: Subscribed calendars added to user's calendar are retrieved. If not specified, all events are retrieved. (Default: `ALL`) For multiple values, use a comma(,) to separate each value. (Example: `USER,SUBSCRIBE`)	X

Response

Body

Name	Type	Description	Required
calendars	`Calendar[]`	List of My Calendar and sub-calendars.	X
subscribe_calendars	`Subscribe[]`	List of subscribed calendars.	X

Calendar

Name	Type	Description	Required
id	`String`	Calendar ID. In the case of My Calendar, `primary` is returned.	O
name	`String`	Calendar name.	X
reminder	`Integer`	Default time of reminder applied to all events in the corresponding calendar. (Example: `15`) If `reminders` is not set for an event, a default reminder value is applied to the event.	X
reminder_all_day	`Integer`	Default time of reminder applied to all-day events in the corresponding calendar. If `reminders` is not set for an all-day event, a default reminder value is applied to the all-day event.	X
color	`String`	Calendar color. Refer to `Color`.	X

Name	Type	Description	Required
id	`String`	Subscribed calendar ID.	O
name	`String`	Subscribed calendar name.	X
color	`String`	Subscribed calendar color. Refer to `Color`.	X
reminder	`Integer`	Default time of reminder applied to all events in the corresponding calendar (Example: `15`)	X
reminder_all_day	`Integer`	Default time of reminder applied to all-day events in the corresponding calendar.	X
description	`String`	Description of the subscribed calendar. This field is set by a service channel.	X
profile_image_url	`String`	URL of the profile image of the subscribed calendar. This field is set by a service channel.	X
thumbnail_url	`String`	URL of the thumbnail image displayed in a chat bubble of the subscribed calendar. This field is set by a service channel.	X

Sample

Request

curl -v -G GET "https://kapi.kakao.com/v2/api/calendar/calendars" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "filter=USER"

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "calendars":[
        {
            "id":"primary",
        },
        {
            "id":"user_6364dcb910662e4ed8823c96",
            "name":"Test sub-calendar",
            "color":"ROYAL_BLUE",
            "reminder":15,
            "reminder_all_day":-540
        },
        {
            "id":"user_6364df33d89d8b4150bbbbc6",
        }
    ],
    "subscribe_calendars":[
        {
            "id":"subscribe_62fc58a57499cb775018baf1",
            "name":"Test subscribed calendar",
            "color":"NAVY_BLUE",
            "reminder":15,
            "reminder_all_day":-540,
            "profile_image_url":"https://t1.kakaocdn.net/calendar/event/700053900/62ce299e2e0c0300b49286cd/banner_mo.gif?831"
        },
        ...
    ]
}

Create sub-calendar

Basic information

Method	URL	Authorization
`POST`	`https://kapi.kakao.com/v2/api/calendar/create/calendar`	Access token

Permission	Prerequisite	Kakao Login	User consent
Required	Activate Kakao Login Manage consent items	Required	Required: Refer to Usage policy

Creates a sub-calendar on user's calendar under the Talk Calendar category.

If you service wants to manage all the events that your service creates in a single calendar, you can use this API.

You can use the created sub-calendar by specifying its calendar ID when you call the following APIs :

Send a POST request with the issued access token in the request header. You must pass the required parameters to create a calendar. If the request is successful, the API returns the created calendar ID in JSON format.

Restrictions

Each service can create up to three sub-calendars.
Total sub-calendars are allowed up to 99.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` Access token as a type of user authentication.	O

Body

Name	Type	Description	Required
name	`String`	Calendar name. Up to 50 characters are allowed.	O
color	`String`	Calendar color. Use one of the values in the `Color` table. (Default: `BLUE`)	X
reminder	`Integer`	Default time of reminder applied to all events in the corresponding calendar (Example: `15`) Can be set for 5 minute intervals. If `reminders` is not set for an event, a default reminder value is applied to the event.	X
reminder_all_day	`Integer`	Default time of reminder applied to all-day events in the corresponding calendar. Can be set for 5 minute intervals. If `reminders` is not set for an all-day event, a default reminder value is applied to the all-day event.	X

Response

Body

Name	Type	Description	Required
calendar_id	`String`	ID of the created sub-calendar.	O

Sample

Request

curl -v -X POST "https://kapi.kakao.com/v2/api/calendar/create/calendar" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "name=Service calendar" \
  -d "color=RED" \
  -d "reminder=15" \
  -d "reminder_all_day=30"

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "calendar_id": "user_6359e5226b03401878f0f2fe"
}

Edit sub-calendar

Basic information

Method	URL	Authorization
`POST`	`https://kapi.kakao.com/v2/api/calendar/update/calendar`	Access token

Permission	Prerequisite	Kakao Login	User consent
Required	Activate Kakao Login Manage consent items	Required	Required: Refer to Usage policy

Edits a particular sub-calendar.

You can edit only the sub-calendar that your service has created.

Send a POST request with the issued access token in the request header. You must pass a calendar ID. To get the ID of the sub-calendar that you want to edit, you can call the Retrieving list of calendars API and get id. You also must pass one or more fields to be edited with calendar_id when you request this API. Otherwise, an error occurs. The fields that are not input remain the same as the initial value.

If the request is successful, this API returns the changed calendar's ID in JSON format.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` Access token as a type of user authentication.	O
Content-Type	`Content-Type: application/x-www-form-urlencoded;charset=utf-8` The data type of the request.	O

Body

Name	Type	Description	Required
calendar_id	`String`	Calendar ID. (Default: `primary` (My calendar))	O
name	`String`	Calendar name. Up to 50 characters are allowed.	X
color	`String`	Calendar color. Use one of the values in the `Color` table.	X
reminder	`Integer`	Default time of reminder applied to all events in the corresponding calendar (Example: `15`) Can be set in 5-minute intervals, and passing `null` resets the value. If `reminders` is not set for an event, a default reminder value is applied to the event.	X
reminder_all_day	`Integer`	Default time of reminder applied to all-day events in the corresponding calendar. Can be set in 5-minute intervals, and passing `null` resets the value. If `reminders` is not set for an all-day event, a default reminder value is applied to the all-day event.	X

Response

Body

Name	Type	Description	Required
calendar_id	`String`	ID of the requested sub-calendar.	O

Sample

Request

curl -v -X POST "https://kapi.kakao.com/v2/api/calendar/update/calendar" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -d "calendar_id=user_6359e5226b03401878f0f2fe" \
    -d "name="Edit service calendar" \
    -d "color=BLUE" \
    -d "reminder=20" \
    -d "reminder_all_day=30"

Response: Success

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "calendar_id": "user_6359e5226b03401878f0f2fe"
}

Delete sub-calendar

Basic information

Method	URL	Authorization
`DELETE`	`https://kapi.kakao.com/v2/api/calendar/delete/calendar`	Access token

Permission	Prerequisite	Kakao Login	User consent
Required	Activate Kakao Login Manage consent items	Required	Required: Refer to Usage policy

Deletes a particular sub-calendar.

You can delete only the sub-calendar that your service has created.

If you delete a sub-calendar by using this API, all of the events added into the sub-calendar are also deleted. Only the person who has created the sub-calendar can delete it.

Send a DELETE request with the issued access token in the request header. You must pass a calendar ID. To get the ID of the sub-calendar that you want to delete, you can call the Retrieving list of calendars API and get id. If the request is successful, the API returns the deleted calendar ID in JSON format.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` Access token as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
calendar_id	`String`	Calendar ID you want to delete. Important: Not allowed to set to `primary` (My calendar) because you cannot delete a user's My Calendar which is set as a default calendar.	O

Response

Name	Type	Description	Required
calendar_id	`String`	ID of the deleted sub-calendar.	O

Sample

Request

curl -v -G -X DELETE "https://kapi.kakao.com/v2/api/calendar/delete/calendar" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "calendar_id=user_6359e5226b03401878f0f2fe"

Response: Success

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "calendar_id": "user_6359e5226b03401878f0f2fe"
}

User event

This section introduces the APIs to manage the events in user's My Calendar or sub-calendars. To learn about the calendar and event types, read Concepts.

Create event

Basic information

Method	URL	Authorization
`POST`	`https://kapi.kakao.com/v2/api/calendar/create/event`	Access token

Permission	Prerequisite	Kakao Login	User consent
Required	Activate Kakao Login Manage consent items	Required	Required: Refer to Usage policy

Creates an event on a user's calendar.

Users can see the created events under the Talk Calendar category. You cannot create a public event and subscribed event with this API. To see how to create each type of event, see Concepts > Event types.

Send a POST request with the issued access token in the request header. You must pass the required parameters to create an event. You can only specify the ID of the user's My Calendar (primary) or a sub-calendar created by the service. If you do not specify a calendar ID, the event is automatically created in the user's My Calendar. To find the desired calandar ID which an event will be added to, call the Retrieving list of calendars API and get id.

If you want to create a recurring event, you must set rrule when you request this API. If not, a one-time event is created. Before creating an event, you can show the user's events or calendars in advance by calling the Retrieving list of events API to let users select an empty time slot and then create an event at that time.

If the request is successful, the API returns the created event ID in JSON format.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` Access token as a type of user authentication.	O

Body

Name	Type	Description	Required
calendar_id	`String`	Calendar ID that a new event is added to. (Default: `primary` (My Calendar)) Note: Possible to specify the ID of My Calendar or a sub-calendar created directly by the service.	X
event	`EventCreate`	Event information that you want to create.	O

EventCreate

Name	Type	Description	Required
title	`String`	Event title. Up to 50 characters are allowed.	O
time	`Time`	Event time information, including start and end time, all-day, lunar or time zone information.	O
rrule	`String`	Interval of recurring events. Use the properties of `RRULE` which are defined in RFC5545. (Example: `"FREQ=DAILY;UNTIL=20221030T000000Z"`) Only used when creating recurring events. If not specified, a one-time event is created.	X
description	`String`	Event description. Up to 5,000 characters are allowed.	X
location	`Location`	Location information of where the event is held.	X
reminders	`Integer[]`	Time of reminders in minutes applied to an event. You can set a maximum of two reminders in multiples of five in the following ranges: All-day event: `-1435` (11:55 p.m. on the day of the event) ≤ reminder value ≤ `43200` (30 days before the event starts) One-time event: `0` (start time of the event) ≤ reminder value ≤ `43200` (30 days before the event starts) To see the examples, refer to `Reminder`. If an empty array is passed, no reminder is set for the event. If not specified, the default reminder values, which are set as `reminder` and `reminder_all_day` when creating or editing the calendar, are applied.	X
color	`String`	Color of the event. One of the color names that are described in `Color`. If not specified when creating an event, the color of the calendar to which the event will be added is automatically applied to the event color.	X

* Required when creating an event.

Reminder

Value (minute)	Description
0	On time
5	5 minutes before event
15	15 minutes before event
30	30 minutes before event
60	60 minutes before event
1440	1 day before event (60x24 minutes)
10080	1 week before event (60x24x7 minutes)
43200	30 days before event (60x24x30 minutes)
-540	9 a.m. on the day of the event
-720	12 p.m. on the day of the event
-1435	11:55 p.m. on the day of the event

Response

Body

Name	Type	Description	Required
event_id	`String`	ID of the created event.	O

Sample

Request: Creating event

curl -v -X POST "https://kapi.kakao.com/v2/api/calendar/create/event" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "calendar_id=user_63759daa38e1f752188e0cc9" \
  -d 'event={
        "title": "Event title",
        "time": {
            "start_at": "2022-10-27T03:00:00Z",
            "end_at": "2022-10-27T06:00:00Z",
            "time_zone": "Asia/Seoul",
            "all_day": false,
            "lunar": false
        },
        "rrlue":"FREQ=DAILY;UNTIL=20221031T000000Z",
        "description": "Event description",
        "location":{
            "name":"Kakao",
            "location_id":18577297,
            "address":"235, Pangyoyeok-ro, Bundang-gu, Seongnam-si, Gyeonggi-do",
            "latitude":37.39570088983171,
            "longitude":127.1104335101161
        },
        "reminders": [15, 30],
        "color": "RED"
    }'

Response: Success

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "event_id":"63630868d89d8b4150bbb712"
}

Retrieve list of events

Basic information

Method	URL	Authorization
`GET`	`https://kapi.kakao.com/v2/api/calendar/events`	Access token

Permission	Prerequisite	Kakao Login	User consent
Required	Activate Kakao Login Manage consent items	Required	Required: Refer to Usage policy

Retrieves all events (personal, public, or subscribed events) added on the requested calendar.

You can use this API to find an event ID before retrieving details, editing, or deleting an event. You can also leverage this API to show all events on a particular calendar so that a user can see an available time slot before creating an event.

Send a GET request with the issued access token in the request header. You also must pass a calendar ID. To find the calendar ID which you want to retrieve from, call the Retrieving list of calendars API and get id.

If the request is successful, this API returns a list of events in JSON format. In the case of the events that your service has not created, only the time information is returned.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` Access token as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
calender_id	`String`	Calendar ID that you want to retrieve. (Default: Retrieves all calendars.)	X
preset	`String`	Retrieval period preset. One of the followings: `TODAY`: The day of the retrieval. `THIS_WEEK`: A week with retrieval days starting on Sunday. `THIS_MONTH`: A month with retrieval days starting on the 1st. Important: Required if `from` and `to` are not set. Important: Ignored if `next_page_token` is set.	X
from	`String`	Start time to retrieve events. In Coordinated Universal Time (UTC), `YYYY-MM-DDThh:mm:ssZ` format as defined in Date and Time on the Internet: Timestamps (RFC3339). (Example: `"2022-05-17T00:00:00Z"`) Period between `from` and `to` must be within 31 days. Important: Ignored if `preset` or `next_page_token` is set.	X
to	`String`	End time to retrieve events. In Coordinated Universal Time (UTC), `YYYY-MM-DDThh:mm:ssZ` format as defined in Date and Time on the Internet: Timestamps (RFC3339). (Example: `"2022-06-16T00:00:00Z"`) Period between `from` and `to` must be within 31 days. Important: Ignored if `preset` or `next_page_token` is set.	X
limit	`Integer`	Maximum number of events to be retrieved per page. (Default: `100`, Maximum: `1000`) Important: Ignored if `preset` or `next_page_token` is set.	X
next_page_token	`String`	Token used to filter events. The token contains the filtering conditions (`from`, `to`, `limit`) and is encoded from JSON to Base64 format. If you pass `next_page_token`, then `from`, `to`, and `limit` are ignored.	X

Response

Body

Name	Type	Description	Required
events	`EventBrief`[]	List of events. If there is no event, an empty array is returned.	O
has_next	`Boolean`	Whether a next page exists.	O
after_url	`String`	URL used to request the next page. Only returned if `has_next` is `true`.	X

EventBrief

For schedules that are not created by your service, only time field is included in the response.

Name	Type	Description	Required
id	`String`	Event ID.	X
title	`String`	Event title.	X
type	`String`	Event type. One of the followings: `USER`: Event that a user added. `PUBLIC`: Public event. `SUBSCRIBE`: Subscribed event.	X
calendar_id	`String`	Calendar ID. `primary`: My Calendar that is automatically created by default for each user.	X
is_host	`Boolean`	Whether the user is a host of the event. `true`: Personal event that the user has created. `false`: Personal event that the user has not created, public event, or subscribed event.	X
time	`Time`	Event time information, including start and end time, all-day, lunar or time zone information.	O
is_recur_event	`Boolean`	Whether the event is recurring. `true`: Recurring event. `false`: One-time event. Only returned if `type` is `USER`.	X
color	`String`	Color of the event. Refer to `Color`. Not returned if not specified when creating or editing an event.	X

Sample

Request

curl -v -G GET "https://kapi.kakao.com/v2/api/calendar/events" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "calendar_id=user_63759daa38e1f752188e0cc9" \
  -d "from=2022-10-26T00:00:00Z" \
  -d "to=2022-10-30T00:00:00Z" \
  -d "limit=2"

Request: retrieve the next page

curl -v -G GET "${AFTER_URL}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "events": [
        {
            "id": "6358e3987ec8e318d0b813bc",
            "title": "Test event",
            "type": "USER",
            "calendar_id": "primary",
            "time": {
                "start_at": "2022-10-27T00:00:00Z",
                "end_at": "2022-10-28T00:00:00Z",
                "all_day": true,
                "lunar": false
            },
            "is_owner": true,
            "is_recur_event": false,
            "color": "RED"
        },
        ...
        {
            "time": {
                "start_at": "2022-10-29T03:00:00Z",
                "end_at": "2022-10-29T06:00:00Z",
                "time_zone": "Asia/Seoul",
                "all_day": false,
                "lunar": false
            }
        }
    ],
    "has_next": true,
    "after_url": "https://kapi.kakao.com/v2/api/calendar/events?target_id=1376016924430355247&target_id_type=user_id&calendar_id=primary&next_page_token=eyJmIjoiMjAyMjEwMjZUMDAwMDAwWiIsInQiOiIyMDIyMTAzMFQwMDAwMDBaIiwibCI6MywicmV2IjoxNjY2Nzc0NjU0MzQ1LCJwbGkiOm51bGwsInFsIjpudWxsfQ%3D%3D"
}

Retrieve details of event

Basic information

Method	URL	Authorization
`GET`	`https://kapi.kakao.com/v2/api/calendar/event`	Access token

Permission	Prerequisite	Kakao Login	User consent
Required	Activate Kakao Login Manage consent items	Required	Required: Refer to Usage policy

Retrieves the details of a user's personal event.

Send a GET request with the issued access token and an event ID. To find the desired event ID, call the Retrieving list of events API. and get id.

If the request is successful, this API returns the detailed information of the event in JSON format.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` Access token as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
event_id	`String`	ID of the event to be retrieved.	O

Response

Body

Name	Type	Description	Required
event	`EventDetail`	Detailed information of the requested event.	O

EventDetail

Name	Type	Description	Required
id	`String`	Event ID.	O
title	`String`	Event title.	O
type	`String`	Event type. One of the followings: `USER`: Event that a user added. `PUBLIC`: Public event. `SUBSCRIBE`: Subscribed event.	O
calendar_id	`String`	Calendar ID. In the case of My Calendar, `primary` is returned.	O
time	`Time`	Event time information, including start and end time, all-day, lunar or time zone information.	O
is_host	`Boolean`	Whether the user is a host of the event. `true`: Personal event that the user has created. `false`: Personal event that the user has not created, public event, or subscribed event.	O
is_recur_event	`Boolean`	Whether the event is recurring. `true`: Recurring event. `false`: One-time event. Only returned if `type` is `USER`.	X
rrule	`String`	Only returned in the case of a recurring event. Value of `rrule` that is passed when you request to edit the event. Example: `"FREQ=DAILY;UNTIL=20221030T000000Z"`	X
dt_start	`String`	Time when a recurring event starts. Only returned if an event is a recurring event. In Coordinated Universal Time (UTC), `YYYY-MM-DDThh:mm:ssZ` format as defined in Date and Time on the Internet: Timestamps (RFC3339). (Example: `"2022-05-17T00:00:00Z"`)	X
description	`String`	Event description. Up to 5,000 characters are allowed.	X
location	`Location`	Location information of where the event is held.	X
reminders	`Integer[]`	Reminder time until the event in minutes. Up to two reminders are allowed.	X
color	`String`	Color of the event. Refer to `Color`.	X
memo	`String`	Note that a user has input. Up to 5,000 characters are allowed. Not returned if user has not input any note.	X
banner	`Banner`	Banner information used to promote a subscribed event. Not retured if banner information is not specified when creating a subscribed event.	X

Banner

Name	Type	Description	Required
pc_image_url	`String`	URL of the banner image to be used on a web.	X
mobile_image_url	`String`	URL of the banner image to be used on mobile.	X
bg_color	`String`	Background color displayed in the margin of the banner image. (Example: `F3F3F3`) `null`: Transparent background.	X
link	`Link`	Link informaiton applied to the image banner.	X

Link

Name	Type	Description	Required
web_url	`String`	URL that is directed to when the button is invoked in a PC environment.	X
mobile_web_url	`String`	URL that is directed to when the button is invoked in a mobile environment.	X

Sample

Request

curl -v -G GET "https://kapi.kakao.com/v2/api/calendar/event" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "event_id=6554545a5df8367886f9d2c5"

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "event": {
    "id": "6554545a5df8367886f9d2c5",
    "title": "Event title",
    "type": "USER",
    "calendar_id": "primary",
    "is_recur_event": false,
    "is_host": true,
    "time": {
      "start_at": "2022-10-27T03:00:00Z",
      "end_at": "2022-10-27T06:00:00Z",
      "time_zone": "Asia/Seoul",
      "all_day": false,
      "lunar": false
    },
    "description": "Event description",
    "location":{
        "name":"Kakao",
        "location_id":18577297,
        "address":"235, Pangyoyeok-ro, Bundang-gu, Seongnam-si, Gyeonggi-do",
        "latitude":37.39570088983171,
        "longitude":127.1104335101161
    },
    "reminders": [
      15,
      30
    ],
    "color": "RED"
  }
}

Edit event for host

Basic information

Method	URL	Authorization
`POST`	`https://kapi.kakao.com/v2/api/calendar/update/event/host`	Access token

Permission	Prerequisite	Kakao Login	User consent
Required	Activate Kakao Login Manage consent items	Required	Required: Refer to Usage policy

Edits a particular personal event that a user has created.

To edit a public event or subscribed event, use the Editing event for attendee API instead. You can refer to is_host to check if a user is a host or an attendee of the event.

Send a POST request with the issued access token in the request header. You must pass one or more fields to be edited with event_id when you request this API. Otherwise, an error occurs. To find the ID of the event that you want to edit, you can call the Retrieving list of events API and get id. To delete a particular field, pass an empty string. If you want to change a recurring event to a one-time event, pass rrule as an empty string, and then all recurring events are changed to a single event.

Refer to the request values by parameter type to remove existing values:

Primitive types (Integer, Boolean, Double, String, etc.): null.
Other types: null or {}.

If a host edits an event, the changes are applied to the events added to attendees' calendars. If attendees edit an event on their own calendar, the changes do not affect the host's event.

If the request is successful, this API returns the event ID in JSON format. In the case of a recurring event, it returns the HTTP status code 200 without the response body.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` Access token as a type of user authentication.	O

Body

Name	Type	Description	Required
event_id	`String`	ID of the event you want to change. To edit a recurring event, you must pass `event_id` in `{EVENT_ID}_{START_DAY_OF_RECURRING_EVENT}` format. (Example: `628b480206f6aa08208c849c_20221010T000000Z`)	O
calendar_id	`String`	Calendar ID. Used to change a calendar which the event is included in. Note: Possible to specify the ID of My Calendar or a sub-calendar created directly by the service.	X
recur_update_type	`String`	Scope of recurring events to which the changes are applied. One of the followings: `ALL`: Update all recurring events associated with the specified `event_id`. `THIS`: Update this event only. `THIS_AND_FOLLOWING`: Update this and following events. Important: Required in case of recurring events. If `recur_update_type` is set to `THIS`, you cannot update `calendar_id`, `memo`, `reminders`, `color`, `rrule`, `time.lunar` and `time.all_day`.	X
event	EventUpdate	Event information to be updated. Important: If you pass `event`, at least one of the parameters must be specified. Otherwise, an error occurs. To delete the existing value, pass an empty value for a string type of the fields. For integer or long type of fields, pass `null` to delete the existing value. The fields that are not input remain the same as the initial value.	X

EventUpdate

Name	Type	Description	Required
title	`String`	Event title. Up to 50 characters are allowed.	X
time	`Time`	Event time information. If `recur_update_type` is set to `THIS` (edit this recurring event only), you cannot edit `lunar` and `all_day`.	X
rrule	`String`	Interval of recurring events. Use the properties of `RRULE` which are defined in RFC5545. (Example: `"FREQ=DAILY;UNTIL=20221030T000000Z"`) Used to change the interval of recurring events. To change a recurring event to a one-time event, pass an empty string. Important: When changing `rrule`, `recur_update_type` must not be `THIS`.	X
description	`String`	Event description. Up to 5,000 characters are allowed.	X
location	`Location`	Location information of where the event is held.	X
reminders	`Integer[]`	Time of reminders in minutes applied to an event. You can set a maximum of two reminders in multiples of five in the following ranges: All-day event: `-1435` (11:55 p.m. on the day of the event) ≤ reminder value ≤ `43200` (30 days before the event starts) One-time event: `0` (start time of the event) ≤ reminder value ≤ `43200` (30 days before the event starts) To see the examples, refer to `Reminder`. If an empty array is passed, no reminder is set for the event. If not specified, the default reminder values, which are set as `reminder` and `reminder_all_day` when creating or editing the calendar, are applied.	X
color	`String`	Color of the event. One of the color names that are described in `Color`. If not specified when creating an event, the color of the calendar to which the event will be added is automatically applied to the event color.	X

Response

Body

Name	Type	Description	Required
event_id	`String`	Event ID. Not returned if you request to change a recurring event even if the request is successful.	X

Sample

Request: Editing a one-time event

curl -v -X POST "https://kapi.kakao.com/v2/api/calendar/update/event/host" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "event_id=6375b0e938e1f752188e0fba" \
  -d "calendar_id=primary" \
  -d "recur_update_type=ALL" \
  -d 'event={
        "title":"Edit event title",
        "time":{
            "start_at":"2022-10-28T03:00:00Z",
            "end_at":"2022-10-29T06:00:00Z",
            "time_zone":"Asia/Seoul",
            "all_day":false,
            "lunar":false
        },
        "rrule":"FREQ=DAILY;UNTIL=20221031T000000Z",
        "description":"Edit event description",
        "location":{
            "name":"Kakao",
            "location_id":18577297,
            "address":"235, Pangyoyeok-ro, Bundang-gu, Seongnam-si, Gyeonggi-do",
            "latitude":37.39570088983171,
            "longitude":127.1104335101161
        },
        "reminders":[0,15],
        "color":"RED"
    }'

Response: Success

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "event_id":"6375b0e938e1f752188e0fba"
}

Delete event

Basic information

Method	URL	Authorization
`DELETE`	`https://kapi.kakao.com/v2/api/calendar/delete/event`	Access token

Permission	Prerequisite	Kakao Login	User consent
Required	Activate Kakao Login Manage consent items	Required	Required: Refer to Usage policy

Deletes the user's personal event or public event added on a user's calendar.

However, you cannot delete subscribed events with this API.

Send a DELETE request with the issued access token in the request header. You also must pass an event ID. To find the event ID that you want to delete, you can call the Retrieving list of events API and get id. If the request is successful, the API returns the deleted event ID in JSON format. If you delete a recurring event, the HTTP status code 200 is returned only.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` Access token as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
event_id	`String`	Event ID.	O
recur_update_type	`String`	Scope of recurring events to which the changes are applied. One of the followings: `ALL`: Delete all recurring events associated with the specified `event_id`. `THIS`: Delete this event only. `THIS_AND_FOLLOWING`: Delete this and following events. Important: Required in case of recurring events.	X

Response

Body

Name	Type	Description	Required
event_id	`String`	ID of the deleted personal event. Not returned if you request to change a recurring event even if the request is successful.	X

Sample

Request: One-time event

curl -v -G -X DELETE "https://kapi.kakao.com/v2/api/calendar/delete/event" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "event_id=63630c44d89d8b4150bbb716"

Response: Success

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "event_id":"63630c44d89d8b4150bbb716"
}

Public event

This section introduces the APIs to manage public events. To see what a public event is, read Concepts > Event types.

Create public event

Basic information

Method	URL	Authorization
`POST`	`https://kapi.kakao.com/v2/api/calendar/public/create/event`	Service app admin key

Permission	Prerequisite	Kakao Login	User consent
Required	Admin key Activate Kakao Login Manage consent items Set Kakao Talk Channel	Required	Required: Refer to Usage policy

Creates a public event.

Send a POST request with your admin key in the request header. You must pass your service's Kakao Talk Channel profile ID and public event information. You can set the content of the notification message that alerts before and after the schedule starts, as well as the details of the custom button.

If the request is successful, the API returns the created public event ID in JSON format.

After a public event is created with this API, you can encourage users to add the event to their calendar by sending a calendar message with a Follow button or by calling Adding public event to user calendar API.

Request

Header

Name	Description	Required
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` Service app admin key as a type of user authentication.	O

Body

Name	Type	Description	Required
channel_public_id	`String`	Kakao Talk Channel profile ID of your service. If your app is connected with only one Kakao Talk Channel, the value of `channel_public_id` will be automatically set to the connected Kakao Talk Channel's ID. In other cases, you must specify a Kakao Talk Channel profile ID.	X
event	`EventPublic`	Information of public event to be created.	O

EventPublic

Name	Type	Description	Required
title	`String`	Event title. Up to 50 characters are allowed.	O
time	`Time`	Event time information, including start and end time, all-day, lunar or time zone information.	O
description	`String`	Event description. Up to 5,000 characters are allowed.	X
location	`Location`	Location information of where the event is held.	X
reminders	`Integer[]`	Time of reminders in minutes applied to an event. You can set a maximum of two reminders in multiples of five in the following ranges: All-day event: `-1435` (11:55 p.m. on the day of the event) ≤ reminder value ≤ `43200` (30 days before the event starts) One-time event: `0` (start time of the event) ≤ reminder value ≤ `43200` (30 days before the event starts) To see the examples, refer to `Reminder`. If not specified, the default reminder values of a sub-calendar is applied.	X
color	`String`	Color of the event. Use one of the values in the `Color` table.	X
notification_message	`NotificationMessage`	Information of notification message that will be sent when a user adds the public event to a calendar or at the time of the set reminders.	X

NotificationMessage

Name	Type	Description	Required
display_custom_button	`Boolean`	Whether to enable custom buttons `true`: Enable a custom button (Default) `false`: Disable	X
before_event_reminder	`EventReminder`	Custom setting for the notification message before the event starts.	X
after_event_reminder	`EventReminder`	Custom setting for the notification message after the event starts.	X

EventReminder

Name	Type	Description	Required
button	`Button`	Custom button information in notification messages, apply default custom button (`공유하기`) if not included	X

Button

Name	Type	Description	Required
title	`String`	Button name. Used to customize a button in the notification message. If not set, the default name `공유하기`(Share) is applied. Use one of the followings: `시청하기` meaning 'Watch'. `예매하기` meaning 'Ticketing'. `예약하기` meaning 'Reserve'. `참여하기` meaning 'Join'. `상세보기` meaning 'Details'. Important: Only Korean is supported for this button name.	X
link	`Link`	Used to set a link applied to the button customized through `title`. Important: Only used when `title` is set to customize a button. If `link` is not set, the default button title (`공유하기`) is displayed even though `title` is set.	X

Link

Name	Type	Description	Required
web_url	`String`	URL that is directed to when the button is invoked in a PC environment, ignore custom button settings and apply the default custom button (`공유하기`) when an invalid URL is entered.	O*
mobile_web_url	`String`	URL that is directed to when the button is invoked in a mobile environment, ignore custom button settings and apply the default custom button (`공유하기`) when an invalid URL is entered.	O*

* Either web_url or mobile_web_url is required.

Response

Body

Name	Type	Description	Required
event_id	`String`	ID of the created public event.	O

Sample

Request

curl -v -X POST "https://kapi.kakao.com/v2/api/calendar/public/create/event" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "channel_public_id=_xnrxjem" \
  -d 'event={
        "title":"Public event test",
        "time":{
            "start_at":"2022-12-10T03:00:00Z",
            "end_at":"2022-12-10T06:00:00Z",
            "time_zone":"Asia/Seoul",
            "all_day":false,
            "lunar":false
        },
        "description":"Public event description",
        "location":{
            "name":"Kakao",
            "location_id":18577297,
            "address":"235, Pangyoyeok-ro, Bundang-gu, Seongnam-si, Gyeonggi-do",
            "latitude":37.39570088983171,
            "longitude":127.1104335101161
        },
        "reminders":[15,30],
        "color":"RED",
        "notification_message":{
            "display_custom_button": true,
            "before_event_reminder":{
                "button":{
                    "title":"예약하기",
                    "link":{
                        "web_url":"https://pf.kakao.com/_ZRQBh/43170951",
                        "mobile_web_url":"https://pf.kakao.com/_ZRQBh/43170951"
                    }
                }
            },
            "after_event_reminder":{
                "button":{
                    "title":"참여하기",
                    "link":{
                        "web_url":"https://pf.kakao.com/_ZRQBh/43170951",
                        "mobile_web_url":"https://pf.kakao.com/_ZRQBh/43170951"
                    }
                }
            }
        }
    }'

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "event_id":"6377474a71fdf754fbbf6465"
}

Retrieve list of public events

Basic information

Method	URL	Authorization
`GET`	`https://kapi.kakao.com/v2/api/calendar/public/events`	Service app admin key

Permission	Prerequisite	Kakao Login	User consent
Required	Admin key Activate Kakao Login Manage consent items Set Kakao Talk Channel	Required	Required: Refer to Usage policy

Retrieves all public events that your service has created.

You can use this API to find a public event ID before viewing details, editing, or deleting a public event.

Send a GET request with your admin key in the request header. You also must pass your service's Kakao Talk Channel profile ID.

If the request is successful, this API returns a list of public events in JSON format.

Request

Header

Name	Description	Required
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` Service app admin key as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
channel_public_id	`String`	Kakao Talk Channel profile ID of your service. If your app is connected with only one Kakao Talk Channel, the value of `channel_public_id` will be automatically set to the connected Kakao Talk Channel's ID. In other cases, you must specify a Kakao Talk Channel profile ID.	X
from	`String`	Start time to retrieve events. In Coordinated Universal Time (UTC), `YYYY-MM-DDThh:mm:ssZ` format as defined in Date and Time on the Internet: Timestamps (RFC3339). (Example: `"2022-05-17T00:00:00Z"`) Important: Period between `from` and `to` must be within 31 days.	O
to	`String`	End time to retrieve events. In Coordinated Universal Time (UTC), `YYYY-MM-DDThh:mm:ssZ` format as defined in Date and Time on the Internet: Timestamps (RFC3339). (Example: `"2022-06-16T00:00:00Z"`) Important: Period between `from` and `to` must be within 31 days.	O
limit	`Integer`	Maximum number of events to be retrieved per page. (Default: `10`, Maximum: `30`)	X
offset	`Integer`	Order that the list of public events starts from. For example, if it is set to `10`, the tenth and the following public events are retrieved. (Default: `0`)	X

Response

Body

Name	Type	Description	Required
events	`EventPublicBrief`[]	List of public event information.	O
has_next	`Boolean`	Whether a next page exists.	O
after_url	`String`	URL used to request the next page. Only returned if `has_next` is `true`.	X

EventPublicBrief

Name	Type	Description	Required
id	`String`	Event ID.	O
title	`String`	Event title.	O
type	`String`	Event type. Fixed to `PUBLIC`.	O
time	`TimeDefault`	Time information.	O
color	`String`	Color of the event. Refer to `Color`.	X

Sample

Request

curl -v -G GET "https://kapi.kakao.com/v2/api/calendar/public/events" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "channel_public_id=_xnrxjem" \
  -d "from=2022-12-01T00:00:00Z" \
  -d "to=2022-12-11T00:00:00Z" \
  -d "limit=3"

Request: retrieve the next page

curl -v GET "${AFTER_URL}" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}"

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "events": [
        {
            "id": "638db634577cba184608ef56",
            "title": "Public event test",
            "type": "PUBLIC",
            "time": {
                "start_at": "2022-12-10T03:00:00Z",
                "end_at": "2022-12-10T06:00:00Z",
                "all_day": false
            },
            "color": "RED"
        },
        ...
    ],
    "has_next": false,
    "after_url": "https://kapi.kakao.com/v2/api/calendar/public/events?channel_public_id=_xnrxjem&from=2022-12-01T00%3A00%3A00Z&to=2022-12-11T00%3A00%3A00Z&offset=2"
}

Retrieve details of public event

Basic information

Method	URL	Authorization
`GET`	`https://kapi.kakao.com/v2/api/calendar/public/event`	Service app admin key

Permission	Prerequisite	Kakao Login	User consent
Required	Admin key Activate Kakao Login Manage consent items Set Kakao Talk Channel	Required	Required: Refer to Usage policy

Retrieves the details of a particular public event that your service has created.

Send a GET request with your admin key and a public event ID. To find the desired public event ID, you can call the Retrieving list of public events API and get id.

If the request is successful, this API returns the detailed information of the public event in JSON format.

Request

Header

Name	Description	Required
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` Service app admin key as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
channel_public_id	`String`	Kakao Talk Channel profile ID of your service. If your app is connected with only one Kakao Talk Channel, the value of `channel_public_id` will be automatically set to the connected Kakao Talk Channel's ID. In other cases, you must specify a Kakao Talk Channel profile ID.	X
event_id	`String`	ID of the public event to be retrieved.	O

Response

Body

Name	Type	Description	Required
id	`String`	Event ID.	O
title	`String`	Event title.	O
type	`String`	Event type. Fixed to `PUBLIC`.	O
time	`Time`	Time information.	O
reminders	`Integer[]`	Reminder time until the event in minutes. Up to two reminders are allowed.	X
location	`Location`	Location information of where the event is held.	X
description	`String`	Event description. Up to 5,000 characters are allowed.	X
color	`String`	Color of the event. Refer to `Color`.	X
notification_message	`NotificationMessage`	Settings for notification messages Include in response when using notification messages	X

NotificationMessage

Name	Type	Description	Required
before_event_reminder	`EventReminder`	Custom setting for the notification message before the event starts.	X
after_event_reminder	`EventReminder`	Custom setting for the notification message after the event starts.	X

Sample

Request

curl -v -G GET "https://kapi.kakao.com/v2/api/calendar/public/event" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "channel_public_id=_xnrxjem" \
  -d "event_id=638db6d5577cba184608ef58"

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "event": {
        "id": "638db6d5577cba184608ef58",
        "title": "Public event title",
        "type": "PUBLIC",
        "time": {
            "start_at": "2022-12-10T03:00:00Z",
            "end_at": "2022-12-10T06:00:00Z",
            "time_zone": "Asia/Seoul",
            "all_day": false,
            "lunar": false
        },
        "description": "Public event description",
        "location": {
            "name": "카카오",
            "location_id": 18577297,
            "address": "경기 성남시 분당구 판교역로 166",
            "latitude": 37.39570088983171,
            "longitude": 127.1104335101161
        },
        "reminders": [
            15, 30
        ],
        "color": "RED",
        "notification_message": {
            "before_event_reminder": {
                "button": {
                    "title": "예약하기",
                    "link": {
                        "web_url": "https://pf.kakao.com/_ZRQBh/43170951",
                        "mobile_web_url": "https://pf.kakao.com/_ZRQBh/43170951"
                    }
                }
            },
            "after_event_reminder": {
                "button": {
                    "title": "참여하기",
                    "link": {
                        "web_url": "https://pf.kakao.com/_ZRQBh/43170951",
                        "mobile_web_url": "https://pf.kakao.com/_ZRQBh/43170951"
                    }
                }
            }
        }
    }
}

Edit public event

Basic information

Method	URL	Authorization
`POST`	`https://kapi.kakao.com/v2/api/calendar/public/update/event`	Service app admin key

Permission	Prerequisite	Kakao Login	User consent
Required	Admin key Activate Kakao Login Manage consent items Set Kakao Talk Channel	Required	Required: Refer to Usage policy

Edits a particular public event.

For this API, you must use an admin key instead of an access token. Send a POST request with your admin key in the request header. You must pass your service's Kakao Talk Channel profile ID and public event information to be edited with event_id. To find the desired public event ID, you can call the Retrieving list of public events API and get id.

Primitive types (Integer, Boolean, Double, String, etc.): null.
Other types: null or {}.

If the request is successful, this API returns the event ID in JSON format. If you edit a public event by using this API, the changes are applied to all of the events added to users' calendars.

Request

Header

Name	Description	Required
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` Service app admin key as a type of user authentication.	O

Body

Name	Type	Description	Required
channel_public_id	`String`	Kakao Talk Channel profile ID of your service. If your app is connected with only one Kakao Talk Channel, the value of `channel_public_id` will be automatically set to the connected Kakao Talk Channel's ID. In other cases, you must specify a Kakao Talk Channel profile ID.	X
event_id	`String`	ID of the public event you want to change.	O
event	`EventUpdatePublic`	Event information to be updated. Important: If you pass `event`, at least one of the parameters must be specified. Otherwise, an error occurs. To delete the existing value, pass an empty value for a string type of the fields. For integer or long type of fields, pass `null` to delete the existing value. The fields that are not input remain the same as the initial value.	X

EventUpdatePublic

Name	Type	Description	Required
title	`String`	Event title. Up to 50 characters are allowed.	X
time	`Time`	Event time information, including start and end time, all-day, lunar or time zone information.	X
description	`String`	Event description. Up to 5,000 characters are allowed.	X
location	`Location`	Location information of where the event is held.	X
reminders	`Integer[]`	Time of reminders in minutes applied to an event. You can set a maximum of two reminders in multiples of five in the following ranges: All-day event: `-1435` (11:55 p.m. on the day of the event) ≤ reminder value ≤ `43200` (30 days before the event starts) One-time event: `0` (start time of the event) ≤ reminder value ≤ `43200` (30 days before the event starts) To see the examples, refer to `Reminder`. If an empty array is passed, no reminder is set for the event. If not specified, the default reminder values, which are set as `reminder` and `reminder_all_day` when creating or editing the calendar, are applied.	X
color	`String`	Color of the public event.	X
notification_message	`NotificationMessage`	Used to update the customized button in a notification message that will be sent to the user who added the public event to their calendar.	X

Response

Body

Name	Type	Description	Required
event_id	`String`	Public event ID.	O

Sample

Request

curl -v -X POST "https://kapi.kakao.com/v2/api/calendar/public/update/event" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "channel_public_id=_xnrxjem" \
  -d "event_id=638db6d5577cba184608ef58" \
  -d 'event={
        "title":"Edit public event title",
        "time":{
            "start_at":"2022-12-10T03:00:00Z",
            "end_at":"2022-12-10T06:00:00Z",
            "time_zone":"Asia/Seoul",
            "all_day":false,
            "lunar":false
        },
        "description":"Edit public event description",
        "location":{
            "name":"Kakao",
            "location_id":18577297,
            "address":"235, Pangyoyeok-ro, Bundang-gu, Seongnam-si, Gyeonggi-do",
            "latitude":37.39570088983171,
            "longitude":127.1104335101161
        },
        "reminders":[15,30],
        "color":"RED",
        "notification_message":{
            "before_event_reminder":{
                "title":"예약하기",
                "link":{
                    "web_url":"https://pf.kakao.com/_ZRQBh/43170951",
                    "mobile_web_url":"https://pf.kakao.com/_ZRQBh/43170951"
                }
            },
            "after_event_reminder":{
                "title":"참여하기",
                "link":{
                    "web_url":"https://pf.kakao.com/_ZRQBh/43170951",
                    "mobile_web_url":"https://pf.kakao.com/_ZRQBh/43170951"
                }
            }
        }
    }'

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "event_id":"638db6d5577cba184608ef58"
}

Delete public event

Basic information

Method	URL	Authorization
`DELETE`	`https://kapi.kakao.com/v2/api/calendar/public/delete/event`	Service app admin key

Permission	Prerequisite	Kakao Login	User consent
Required	Admin key Activate Kakao Login Manage consent items Set Kakao Talk Channel	Required	Required: Refer to Usage policy

Deletes a particular public event.

Send a DELETE request with the issued access token in the request header. You also must pass a Kakao Talk Channel profile ID and a public event ID. To find the public event ID that you want to delete, you can call the Retrieving list of public events API and get id. If the request is successful, the API returns the deleted public event ID in JSON format.

Ensure that if you delete a public event by using this API, all of the events added to users' calendars are also deleted.

Request

Header

Name	Description	Required
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` Service app admin key as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
channel_public_id	`String`	Kakao Talk Channel profile ID of your service. If your app is connected with only one Kakao Talk Channel, the value of `channel_public_id` will be automatically set to the connected Kakao Talk Channel's ID. In other cases, you must specify a Kakao Talk Channel profile ID.	X
event_id	`String`	ID of the public event to be deleted.	O

Response

Body

Name	Type	Description	Required
event_id	`String`	ID of the deleted public event.	O

Sample

Request

curl -v -G -X DELETE "https://kapi.kakao.com/v2/api/calendar/public/delete/event" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "channel_public_id=_xnrxjem" \
  -d "event_id=637b3bc671fdf754fbbf6f08"

Response: Success

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "event_id":"637b2d3471fdf754fbbf6e94"
}

Add public event to user calendar

Basic information

Method	URL	Authorization
`POST`	`https://kapi.kakao.com/v2/api/calendar/public/follow`	Access token

Permission	Prerequisite	Kakao Login	User consent
Required	Activate Kakao Login Manage consent items Set Kakao Talk Channel	Required	Required: Refer to Usage policy

Adds public events published by your service's Kakao Talk Channel to a user's calendar.

Send a POST request with the issued access token with a pubic event ID. To get the desired public event ID, you can call the Retrieving list of public events API and get id.

If the request is successful, the API returns the public event ID in JSON format. If a user selects to follow a public event of your service, the event is added to the user's calendar depending on the specified calendar_id. To unfollow a public event, call the Deleting events API in the same way as a user's personal event.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` Access token as a type of user authentication.	O

Body

Name	Type	Description	Required
event_id	`String`	Public event ID.	O
calendar_id	`String`	ID of user's calendar that the public event will be added to. (Default: `primary` (My calendar))	X

Response

Body

Name	Type	Description	Required
event_id	`String`	Public event ID.	O

Sample

Request

curl -v -X POST "https://kapi.kakao.com/v2/api/calendar/public/follow" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "event_id=637b3d0471fdf754fbbf6f0e" \
  -d "calendar_id=user_6375c8e638e1f752188e114e"

Response: Success

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "event_id":"637b3d0471fdf754fbbf6f0e"
}

Send a calendar message

You can attract more people and promote a one-time event that your service has published by sending a Kakao Talk message with the 일정 등록하기(Add event) button through the Kakao Talk Share API or the Kakao Talk Message API.

To add the 일정 등록하기(Add event) button to a message, you must set id_type to event and set id to a public event ID when you configure a calendar message. You can find the development guides in Concepts > Send a calendar message.

Subscribed calendar

This section introduces the APIs to manage Subscribed calendars. Users can see the Subscribed calendars that they are subscribing to under the Subscribed Calendars category. To see the calendar types, read Concepts > Calendar types.

Retrieve list of subscribable calendars

Basic information

Method	URL	Authorization
`GET`	`https://kapi.kakao.com/v2/api/calendar/subscribable/calendars`	Service app admin key

Permission	Prerequisite	Kakao Login	User consent
Required	Admin key Activate Kakao Login Manage consent items	Required	Required: Refer to Usage policy

Retrieves the list of the available calendars that a user can subscribe to.

You are required to obtain permission to use this API. See How to use.

For this API, you must use an admin key instead of an access token. Send a GET request with your admin key in the request header. If the request is successful, this API returns a list of subscribed calendars in JSON format.

Request

Header

Name	Description	Required
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` Service app admin key as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
category_name	`String`	Used to retrieve only the subscribed calendars included in a particular category. (Example: `스포츠`(Sports), `카카오`(Kakao)) If not specified, all subscribed calendars are retrieved. Important: Required if you pass `subcategory_name`.	X
subcategory_name	`String`	Used to retrieve only the subscribed calendars included in a particular sub-category. (Example: `Baseball`)	X

Response

Body

Name	Type	Description	Required
categories	`Category[]`	List of subscribed calendars by category.	O

Subcategory

Name	Type	Description	Required
name	`String`	Sub-category name which the subscribed calendars are included in. Not returned if a sub-category name is not specified.	X
calendars	`Calendar[]`	List of subscribed calendar information.	O

Calendar

Name	Type	Description	Required
id	`String`	Subscribed calendar ID.	O
name	`String`	Subscribed calendar name.	O
profile_image_url	`String`	URL of the profile image of the subscribed calendar.	O

Sample

Request

curl -v -G GET "https://kapi.kakao.com/v2/api/calendar/subscribable/calendars" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}"

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "categories":[
        {
            "category_name":"대분류",
            "subcategories":[
                {
                    "subcategory_name":"소분류",
                    "calendars":[
                        {
                            "id":"subscribe_5efad4e3890efb10051630f2",
                            "name":"구독 가능 캘린더 1",
                            "profile_image_url":"https://t1.daumcdn.net/media/img-section/sports13/logo/team/6/K05_300300.png"
                        },
                        {
                            "id":"subscribe_5efc1e655642c30ba8a6743b",
                            "name":"구독 가능 캘린더 2"
                        }
                    ]
                }
            ]
        }
    ]
}

Basic information

Method	URL	Authorization
`POST`	`https://kapi.kakao.com/v2/api/calendar/subscribe`	Access token

Permission	Prerequisite	Kakao Login	User consent
Required	Activate Kakao Login Manage consent items	Required	Required: Refer to Usage policy

Subscribes to your service's calendar.

You are required to obtain permission to use this API. See How to use. To add a new subscribed calendar, request at DevTalk.

To add a subscribed calendar to a user's calendar, send a POST request with the issued access token and your service's subscribed calendar ID. To retrieve the desired subscribed calendar ID, you can call the Retrieving list of subscribable calendars API or Retrieving list of calendars API.

If the request is successful, this API returns the subscribed calendar ID in JSON format. If a user subscribes to your service's subscribed calendar, all events of the subscribed calendar are added to the user's calendar. Users can edit the subscribed events' reminder, note, and event color through the Editing event for attendee API.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` Access token as a type of user authentication.	O

Body

Name	Type	Description	Required
calendar_id	`String`	Subscribed calendar ID that a user will subscribe to.	O

Response

Body

Name	Type	Description	Required
calendar_id	`String`	Subscribed calendar ID.	O

Sample

Request

curl -v -X POST "https://kapi.kakao.com/v2/api/calendar/subscribe" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "calendar_id=subscribe_5efad4e3890efb10051630f2"

Response: Succcess

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "calendar_id":"subscribe_5efad4e3890efb10051630f2"
}

Unsubscribe

Basic information

Method	URL	Authorization
`DELETE`	`https://kapi.kakao.com/v2/api/calendar/unsubscribe`	Access token

Permission	Prerequisite	Kakao Login	User consent
Required	Activate Kakao Login Manage consent items	Required	Required: Refer to Usage policy

Unsubscribes from your service's calendar.

You are required to obtain permission to use this API. See How to use.

To remove a subscribed calendar from a user's calendar, send a DELETE request with the issued access token and your service's subscribed calendar ID. To retrieve the desired subscribed calendar ID, you can call the Retrieving list of subscribable calendars API or Retrieving list of calendars API.

If the request is successful, the API returns the subscribed calendar ID in JSON format.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` Access token as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
calendar_id	`String`	Subscribed calendar ID to be removed from a user's calendar.	O

Response

Body

Name	Type	Description	Required
calendar_id	`String`	Subscribed calendar ID.	O

Sample

Request

curl -v -G -X DELETE "https://kapi.kakao.com/v2/api/calendar/unsubscribe" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "calendar_id=subscribe_5efad4e3890efb10051630f2"

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "calendar_id":"subscribe_5efad4e3890efb10051630f2"
}

Send a calendar message

If your service has a subscribed calendar, you can encourage users to subscribe to your subscribed calendar by sending a Kakao Talk message with the 캘린더 구독 하기(Subscribe to calendar) button through the Kakao Talk Share API or the Kakao Talk Message API.

To add the 캘린더 구독 하기(Subscribe to calendar) button to a message, you must set id_type to calendar and set id to your service's subscribed calendar ID when you configure a calendar message. You can find the development guides in Concepts > Send a calendar message.

Guest event

Edit guest event

Basic information

Method	URL	Authorization
`POST`	`https://kapi.kakao.com/v2/api/calendar/update/event/guest`	Access token

Permission	Prerequisite	Kakao Login	User consent
Required	Activate Kakao Login Manage consent items	Required	Required: Refer to Usage policy

Edits a particular public event or subscribed event added to a user's calendar.

Primitive types (Integer, Boolean, Double, String, etc.): null.
Other types: null or {}.

You can edit only the reminders, memo, color of the desired event, or calendar ID with this API. To delete a particular field, pass an empty string.

If the request is successful, this API returns the event ID in JSON format.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` Access token as a type of user authentication.	O

Body

Name	Type	Description	Required
event_id	`String`	ID of the event you want to change. To obtain the desired event ID, call the Retrieving list of events API and get `id`.	O
calendar_id	`String`	Calendar ID. To obtain the desired calendar ID, call the Retrieving list of calendars API and get `id`. Used to change a calendar which the event is included in.	X
event	EventGuest	Event information to be changed. Important: If you pass `event`, at least one of the parameters must be specified. Otherwise, an error occurs. To delete the existing value, pass an empty value for a string type of the fields. For integer or long type of fields, pass `null` to delete the existing value. The fields that are not input remain the same as the initial value.	X

EventGuest

Name	Type	Description	Required
reminders	`Integer[]`	Time of reminders in minutes applied to an event. You can set a maximum of two reminders in multiples of five in the following ranges: All-day event: `-1435` (11:55 p.m. on the day of the event) ≤ reminder value ≤ `43200` (30 days before the event starts) One-time event: `0` (start time of the event) ≤ reminder value ≤ `43200` (30 days before the event starts) To see the examples, refer to `Reminder`. If an empty array is passed, no reminder is set for the event. If not specified, the default reminder values, which are set as `reminder` and `reminder_all_day` when creating or editing the calendar, are applied.	X
color	`String`	Color of the event. Use one of the values in the `Color` table.	X
memo	`String`	Note that a user has input. Up to 5,000 characters are allowed.	X

Response

Body

Name	Type	Description	Required
event_id	`String`	Event ID.	O

Sample

Request

curl -v -X POST "https://kapi.kakao.com/v2/api/calendar/update/event/guest" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "event_id=6351f57c7ec8e318d0b809a0" \
  -d 'event={
        "reminders":[30,45],
        "color":"RED",
        "memo":"Edit memo"
    }'

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "event_id":"6351f57c7ec8e318d0b809a0"
}

Retrieve holidays and celebrations

Basic information

Method	URL	Authorization
`GET`	`https://kapi.kakao.com/v2/api/calendar/holidays`	Service app admin key

Permission	Prerequisite	Kakao Login	User consent
-	Admin key	-	-

Retrieves holidays in the Republic of Korea for a requested period on a calendar.

For example, you can show users the dates of holidays when promoting a public event.

The holidays retrieved in response to this API include:

National holidays
Public holidays
Some of the major traditional holidays
Jeolgi seasons (Korean seasonal divisions)
Celebration days
Observances

Request

Header

Name	Description	Required
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` Service app admin key as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
from	`String`	Start time to retrieve events. In Coordinated Universal Time (UTC), `YYYY-MM-DDThh:mm:ssZ` format as defined in Date and Time on the Internet: Timestamps (RFC3339). (Example: `"2022-05-17T00:00:00Z"`) Important: Period between `from` and `to` must be within 31 days.	O
to	`String`	End time to retrieve events. In Coordinated Universal Time (UTC), `YYYY-MM-DDThh:mm:ssZ` format as defined in Date and Time on the Internet: Timestamps (RFC3339). (Example: `"2022-06-16T00:00:00Z"`) Important: Period between `from` and `to` must be within 31 days.	O

Response

Body

Name	Type	Description	Required
events	`EventSpecial[]`	List of holidays and celebrations.	O

EventSpecial

Name	Type	Description	Required
id	`String`	Event ID.	O
title	`String`	Event title.	O
time	TimeDefault	Holiday time information.	O
holiday	`Boolean`	Whether the day is a public holiday.	O

Sample

Request: Using admin key

curl -v -G GET "https://kapi.kakao.com/v2/api/calendar/holidays" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "from=2022-10-01T00:00:00Z" \
  -d "to=2022-10-20T00:00:00Z"

Response: Success

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "events":[
        {
            "id":"S5d5ba43907d5351aba275d72",
            "title":"국군의날",
            "time":{
                "start_at":"2022-10-01T00:00:00Z",
                "end_at":"2022-10-02T00:00:00Z",
                "all_day":true
            },
            "holiday":false
            },
            {
            "id":"S5d5ba43907d5351aba275d73",
            "title":"개천절",
            "time":{
                "start_at":"2022-10-03T00:00:00Z",
                "end_at":"2022-10-04T00:00:00Z",
                "all_day":true
            },
            "holiday":true
        },
        {
            "id":"S5d5ba43907d5351aba275d74",
            "title":"한글날",
            "time":{
                "start_at":"2022-10-09T00:00:00Z",
                "end_at":"2022-10-10T00:00:00Z",
                "all_day":true
            },
            "holiday":true
        }
    ]
}

Task

Create task

Basic information

Method	URL	Authorization
`POST`	`https://kapi.kakao.com/v1/api/calendar/create/task`	Access token

Permission	Prerequisite	Kakao Login	User consent
Required	Activate Kakao Login Manage consent items	Required	Required: Refer to Usage policy

Creates a task.

Send a POST request with the issued access token in the request header.

If you include rrule, it creates a recurring task that has a regular interval from the due date; if you don't include it, it creates a regular task that ends with a single occurrence.

The recurring task is marked as a single event, and if the current time passes the due date, the due date is automatically modified to the next recurring date. If you set the recurring task's record_on to true, you can enable the [My Challenge Record] to see its completion history.

If the request is successful, the response is a JSON object containing the task ID. If the request fails, check the Error Code for the reason.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` Access token as a type of user authentication.	O

Body

Name	Type	Description	Required
task	`Task`	Task information.	O

Task

Name	Type	Description	Required
content	`String`	Content. (Maximum: `1000`)	O
due_info	`DueInfo`	Due date information. (Default: No due date)	X

DueInfo

Name	Type	Description	Required
due_date	`String`	Due date, `yyyyMMdd` format. (Maximum: `20501231`) Important: Cannot be set to a point in the past.	O
time_zone	`String`	Time zone. (Default: `Asia/Seoul`)	X
alarm_time	`String`	Alarm time in `HHmm` format every 5 minutes. (Unit: Minutes, Default: No alarm)	X
recur	`Recur`	Recurring information. (Default: No recurring)	X

Recur

Name	Type	Description	Required
rrule	`String`	Recurring interval. Use the properties of `RRULE` which are defined in RFC5545. (Example: `"FREQ=DAILY;UNTIL=20221030T000000Z"`) `UNTIL` can only be specified after `due_date` in `yyyyMMdd'T'000000Z` format and must exist at least one day that satisfies the `rrule` condition. (Maximum: `2050-12-31T235959Z`)	X
record_on	`Boolean`	Whether to enable [My Challenge Record]. `true`: Enable `false`: Disable(Default)	X

Response

Body

Name	Type	Description	Required
task_id	`String`	Created task ID.	O

Sample

Request

curl -v -X POST "https://kapi.kakao.com/v1/api/calendar/create/task" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d 'task={
        "content": "Today task",
        "due_info": {
            "due_date": "${DUE_DATE}",
            "time_zone": "Asia/Seoul",
            "alarm_time": "0900",
            "recur": {
                "rrule": "FREQ=DAILY;COUNT=3",
                "record_on": true
            }
        }
    }'

Response

HTTP/1.1 200 OK
{
    "task_id": "${TASK_ID}"
}

Retrieve task

Basic information

Method	URL	Authorization
`GET`	`https://kapi.kakao.com/v1/api/calendar/tasks`	Access token

Permission	Prerequisite	Kakao Login	User consent
Required	Activate Kakao Login Manage consent items	Required	Required: Refer to Usage policy

Retrieves a particular or list of task.

Send a GET request with the issued access token in the request header.

You can retrieves a perticular task by including the task ID as a parameter, or list of task by including the time period. When retrieving list, it is sorted by most recently edited.

Recurring task are shown as one task, and if the current time is past the due date, the due date is automatically edited to the next recurring date.

If the request is successful, the response is a JSON object containing task information. If the request fails, check the Error Code for the reason.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` Access token as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
task_id	`String`	Task ID. Important: If included, only the task corresponding to the ID will be retrieved, and all other request parameters will be ignored.	X
from	`String`	Start time to retrieve, `yyyyMMdd` format. Note: Required when `task_id` is not included.	X
to	`String`	End time to retrieve, `yyyyMMdd` format. Within 31 days of `from`. Note: Required when `task_id` is not included.	O
task_status	`String`	Task status, One of the followings: `COMPLETED`: Completed `TODO`: Not completed (Default) `ALL`: All status (Displays `TODO` status first)	X
task_filter	`String`	Task condition to retrieve (Default: All conditions) Comma (",") as a separator to pass multiple values (Example: "authorized,bookmark") One of the followings: `authorized`: Tasks that can be edited or deleted `bookmark`: Tasks that have been bookmarked.	X
offset	`Integer`	Offset value that the list of tasks starts from. (Default: 0)	X
limit	`Integer`	Number of results per page. (Default: 100, Maximum: 1000)	X
time_zone	`String`	Time zone. (Default: `Asia/Seoul`) Note: Time calculation criteria of `status` response.	X

Response

Body

Name	Type	Description	Required
task	`Task[]`	list of task information.	O
count	`Integer`	The total number of tasks in the search period. Up to the number specified by `limit`, and the list of uncompleted tasks can be retrieved by `after_url`.	O
has_next	`Boolean`	Whether a next page exists.	O
after_url	`String`	URL used to request the next page. Only returned if `has_next` is `true`.	X

Task

Name	Type	Description	Required
task_id	`String`	Task ID.	O
content	`String`	Content.	O
status	`String`	Task status. `SCHEDULED`: Before the due date. `COMPLETED`: Completed. `DELAYED`: After the due date.	O
bookmark	`Boolean`	Whether the tasks that have been bookmarked.	O
authorized	`Boolean`	Whether the tasks that can be edited or deleted.	O
due_info	`DueInfo`	Due date information.	X

DueInfo

Name	Type	Description	Required
due_date	`String`	Due date, `yyyyMMdd` format.	O
alarm_time	`String`	Alarm time in `HHmm` format every 5 minutes. (Unit: Minutes)	X
recur	`Recur`	Recurring information.	X

Recur

Name	Type	Description	Required
rrule	`String`	Recurring interval. Use the properties of `RRULE` which are defined in RFC5545. (Example: `"FREQ=DAILY;UNTIL=20221030T000000Z"`)	X
record_on	`Boolean`	Whether to enable [My Challenge Record]. `true`: Enable `false`: Disable	X
is_ended	`Boolean`	Whether the task has been completed, `true` if the last to-do has been completed.	O

Sample

Request: Retrieving the single task

curl -v -G GET "https://kapi.kakao.com/v1/api/calendar/tasks" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "time_zone=Asia/Seoul" \
  -d "task_id=${TASK_ID}"

Request: Retrieving the list in the period

curl -v -G GET "https://kapi.kakao.com/v1/api/calendar/tasks" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "from=20231208" \
  -d "to=20231215" \
  -d "time_zone=Asia/Seoul" \
  -d "task_status=ALL" \
  -d "task_filter=authorized" \
  -d "offset=0" \
  -d "limit=4"

Response

HTTP/1.1 200 OK
{
  "tasks": [
    {
      "task_id": "${TASK_ID}",
      "content": "Test task 1",
      "status": "SCHEDULED",
      "bookmark": false,
      "authorized": true
    },
    {
      "task_id": "${TASK_ID}",
      "content": "Test task 2",
      "status": "DELAYED",
      "bookmark": true,
      "authorized": true,
      "due_info": {
        "due_date": "20231211",
        "alarm_time": "0900"
      }
    },
    {
      "task_id": "${TASK_ID}",
      "content": "Test task 3",
      "status": "SCHEDULED",
      "bookmark": false,
      "authorized": true,
      "due_info": {
        "due_date": "20231212",
        "alarm_time": "0900",
        "recur": {
          "rrule": "FREQ=DAILY;",
          "record_on": false,
          "is_ended": false
        }
      }
    },
    {
      "task_id": "${TASK_ID}",
      "content": "Test task 4",
      "status": "SCHEDULED",
      "bookmark": false,
      "authorized": true,
      "due_info": {
        "due_date": "20231212",
        "alarm_time": "0900",
        "recur": {
          "rrule": "FREQ=DAILY;",
          "record_on": false,
          "is_ended": false
        }
      }
    }
  ],
  "count": 22,
  "has_next": true,
  "after_url": "https://kapi.kakao.com/v1/api/calendar/tasks?task_status=ALL&target_id_type=user_id&limit=4&target_id=${TASK_ID}&from=20231208&to=20231215&task_filter=authorized&time_zone=Asia%2FSeoul&offset=4"
}

Check challenge record

Basic information

Method	URL	Authorization
`GET`	`https://kapi.kakao.com/v1/api/calendar/task/records`	Access token

Permission	Prerequisite	Kakao Login	User consent
Required	Activate Kakao Login Manage consent items	Required	Required: Refer to Usage policy

Checks the challenge history of a specific recurring task.

Only available for tasks that have [My Challenge Record] enabled.

Send a GET request with the issued access token in the request header. You must include the task ID as a parameter. If you specify a time period, you will only see records within that period.

If the request is successful, the response is a JSON object containing completion status by date. If the request fails, check the Error Code for the reason.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` Access token as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
task_id	`String`	Task ID.	O
from	`String`	The beginning month and year of the retrieving period, `yyyyMM` format.	X
to	`String`	The ending month and year of the retrieving period, `yyyyMM` format.	X

Response

Body

Name	Type	Description	Required
records	`Record[]`	List of challenge record information Respond with an empty array if there is no record of completion or failure, or if it is not recurring task.	X
start_at	`String`	The beginning month and year of the challenge, `yyyyMM` format. Note: Only include challenge record in the response if it exists.	X
end_at	`String`	The ending month and year of the challenge, `yyyyMM` format. Note: Only include challenge record in the response if it exists.	X

Record

Name	Type	Description	Required
date	`String`	Challenge date, `yyyyMMdd` format.	O
complete	`Boolean`	Whether the task was completed on that challenge date.	O

Sample

Request

curl -v -G GET "https://kapi.kakao.com/v1/api/calendar/task/records" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "task_id=${TASK_ID}" \
  -d "from=202311" \
  -d "to=202312"

Response

HTTP/1.1 200 OK
{
    "records": [
        {
            "date": "20231211",
            "complete": true
        }
    ],
    "start_at": "202312",
    "end_at": "202312"
}

Edit task

Basic information

Method	URL	Authorization
`POST`	`https://kapi.kakao.com/v1/api/calendar/update/task`	Access token

Permission	Prerequisite	Kakao Login	User consent
Required	Activate Kakao Login Manage consent items	Required	Required: Refer to Usage policy

Edits a particular task.

You cannot edit the tasks registered on Kakao Talk profile sticker.

Send a POST request with the issued access token in the request header. You must include the task ID and at least one modification in the parameter. Pass null to delete the value assigned to the parameter.

Deleting a task's due date also deletes the recurring information and disables [My Challenge Record], which can only be set for recurring tasks.

If the request is successful, the response is a JSON object containing the task ID. If the request fails, check the Error Code for the reason.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` Access token as a type of user authentication.	O

Body

Name	Type	Description	Required
task_id	`String`	Task ID.	O
task	Task	Task information.	O

Task

Name	Type	Description	Required
content	`String`	Content. (Maximum: `1000`, Default: Not edited)	X
bookmark	`Boolean`	Whether the tasks that have been bookmarked. (Default: Not edited)	X
due_info	`DueInfo`	Due date information. (Default: Not edited)	X

DueInfo

Name	Type	Description	Required
due_date	`String`	Due date, `yyyyMMdd` format. (Default: Not edited, Maximum: `20501231`) Important: Cannot be set to a point in the past.	X
time_zone	`String`	Time zone. (Default: Not edited)	X
alarm_time	`String`	Alarm time in `HHmm` format every 5 minutes. (Unit: Minutes, Default: Not edited)	X
recur	`Recur`	Recurring information. (Default: Not edited)	X

Recur

Name	Type	Description	Required
rrule	`String`	Recurring interval. Use the properties of `RRULE` which are defined in RFC5545. (Example: `"FREQ=DAILY;UNTIL=20221030T000000Z"`) `UNTIL` can only be specified after `due_date` in `yyyyMMdd'T'000000Z` format and must exist at least one day that satisfies the `rrule` condition. (Default: Not edited, Maximum: `2050-12-31T235959Z`)	X
record_on	`Boolean`	Whether to enable [My Challenge Record]. (Default: Not edited)	X

Response

Body

Name	Type	Description	Required
task_id	`String`	Edited task ID.	O

Sample

Request

curl -v -X POST "https://kapi.kakao.com/v1/api/calendar/update/task" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d 'task={
        "content": "Edit test task",
        "due_info": {
            "due_date": "${DUE_DATE}",
            "time_zone": "Asia/Seoul",
            "alarm_time": "0900",
            "recur": {
                "rrule": "FREQ=DAILY;",
                "record_on": false
            }
        },
        "bookmark": true
    }' \
  -d "task_id=${TASK_ID}"

Request: Delete due date information

curl -v -X POST "https://kapi.kakao.com/v1/api/calendar/update/task" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d 'task={
        "due_info": null
    }' \
  -d "task_id=${TASK_ID}"

Request: Delete recurring information

curl -v -X POST "https://kapi.kakao.com/v1/api/calendar/update/task" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d 'task={
        "due_info": {
            "due_date": "${DUE_DATE}",
            "time_zone": "Asia/Seoul",
            "alarm_time": "0900",
            "recur": null
        }
    }' \
  -d "task_id=${TASK_ID}"

Response

HTTP/1.1 200 OK
{
    "task_id": "${TASK_ID}"
}

Set completion status

Basic information

Method	URL	Authorization
`POST`	`https://kapi.kakao.com/v1/api/calendar/complete/task`	Access token

Permission	Prerequisite	Kakao Login	User consent
Required	Activate Kakao Login Manage consent items	Required	Required: Refer to Usage policy

Sets the completion status of task.

Send a POST request with the issued access token in the request header. You must pass the task ID and completion status in the parameters.

If the request is successful, the response is a JSON object containing the task ID. If the request fails, check the Error Code for the reason.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` Access token as a type of user authentication.	O

Body

Name	Type	Description	Required
task_id	`String`	Task ID.	O
complete	`Boolean`	Whether a task is complete. `true`: Complete `false`: Incomplete	O

Response

Body

Name	Type	Description	Required
task_id	`String`	Completion status set task ID	O

Sample

Request

curl -v -X POST "https://kapi.kakao.com/v1/api/calendar/complete/task" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "task_id=${TASK_ID}" \
  -d "complete=true"

Response

HTTP/1.1 200 OK
{
    "task_id": "${TASK_ID}"
}

Delete task

Basic information

Method	URL	Authorization
`DELETE`	`https://kapi.kakao.com/v1/api/calendar/delete/task`	Access token

Permission	Prerequisite	Kakao Login	User consent
Required	Activate Kakao Login Manage consent items	Required	Required: Refer to Usage policy

Deletes a particular task.

Cannot delete the tasks registered on Kakao Talk profile sticker.

Send a DELETE request with the issued access token in the request header. You must pass the task ID in the parameters.

If the request is successful, the response is a JSON object containing the task ID. If the request fails, check the Error Code for the reason.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` Access token as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
task_id	`String`	Task ID.	O

Response

Body

Name	Type	Description	Required
task_id	`String`	Deleted task ID.	O

Sample

Request

curl -v -G -X DELETE "https://kapi.kakao.com/v1/api/calendar/delete/task" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "task_id=${TASK_ID}"

Response

HTTP/1.1 200 OK
{
    "task_id": "${TASK_ID}"
}

Common parameter

Location

Required parameters
- User event > Create event: name
Default values
- User event > Create event
  - location_id, address, latitude, longitude: None
- User event > Edit event for host
  - name, location_id, address, latitude, longitude: Existing value

Name	Type	Description	Required
name	`String`	Location name. Up to 100 characters are allowed.	X
location_id	`Long`	Location ID.	X
address	`String`	Address of the location.	X
latitude	`Double`	Latitude of the location.	X
longitude	`Double`	Longitude of the location.	X

Time

Required parameters
- User event > Create event: start_at, end_at
Default values
- User event > Create event
  - time_zone: Asia/Seoul
- User event > Edit event for host
  - start_at, end_at, time_zone, all_day, lunar: Existing value

Name	Type	Description	Required
start_at	`String`	Time when the event starts in `YYYY-MM-DDThh:mm:ssZ` format. (Maximum: `2050-12-31T14:50:00Z`)	X
end_at	`String`	Time when the event ends in `YYYY-MM-DDThh:mm:ssZ` format. (Maximum: `2050-12-31T14:55:00Z`)	X
time_zone	`String`	Time zone. (Default: `Asia/Seoul`)	X
all_day	`Boolean`	Whether the event is all-day or timed event. `true`: All-day event. `false`: Timed event.	X
lunar	`Boolean`	Whether the event is solar or lunar calendar. `true`: Lunar calendar. `false`: Solar calendar.	X

TimeDefault

Name	Type	Description	Required
start_at	`String`	Time when the event starts. In Coordinated Universal Time (UTC), `YYYY-MM-DDThh:mm:ssZ` format as defined in Date and Time on the Internet: Timestamps (RFC3339). (Maximum: `2050-12-31T14:50:00Z`)	O
end_at	`String`	Time when the event ends. Same format as `start_at`. (Maximum: `2050-12-31T14:55:00Z`)	O
all_day	`Boolean`	Whether the event is all-day or timed event. `true`: All-day event. `false`: Timed event.	X

Color

For the color parameter, input a color name such as BLUE. Do not use the hexadecimal color code which is provided as a reference value.

Name	Hexadecimal color code
BLUE	2C88DE
ROYAL_BLUE	2D69E0
NAVY_BLUE	223788
RED	D42726
PINK	ED5683
ORANGE	FF9429
GREEN	149959
LIME	7CB343
OLIVE	A4AD15
MINT	5CC5BE
MAGENTA	AB47BC
VIOLET	8A4B9B
LAVENDER	7986CB
BROWN	945C1F
GRAY	666666

See more

Reference for REST API

사이드 메뉴

Docs Home

Getting started

Kakao Developers

Login

Communication

Kakao Map

Navigation

Advertisement

Search

More

REST API

User calendar

Retrieve list of calendars

Basic information

Request

Header

Query parameter

Response

Body

Calendar

Subscribe

Sample

Request

Response

Create sub-calendar

Basic information

Restrictions

Request

Header

Body

Response

Body

Sample

Request

Response

Edit sub-calendar

Basic information

Request

Header

Body

Response

Body

Sample

Request

Response: Success

Delete sub-calendar

Basic information

Request

Header

Query parameter

Response

Sample

Request

Response: Success

User event

Create event

Basic information

Request

Header

Body

EventCreate

Reminder

Response

Body

Sample

Request: Creating event

Response: Success

Retrieve list of events

Basic information

Request

Header

Query parameter

Response

Body

EventBrief

Sample

Request

Request: retrieve the next page

Response