페이지 이동경로
  • Docs>
  • Talk Calendar>
  • REST API

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 Register platforms
Activate Kakao Login
Manage consent items		 Required Required:
Refer to Usage policy

This API lets your service retrieve 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
Subscribe
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 Register platforms
Activate Kakao Login
Manage consent items		 Required Required:
Refer to Usage policy

This API lets your service create 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 Register platforms
Activate Kakao Login
Manage consent items		 Required Required:
Refer to Usage policy

This API lets your service edit 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 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 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 Register platforms
Activate Kakao Login
Manage consent items		 Required Required:
Refer to Usage policy

This API lets your service delete 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://kauth.kakao.com/v2/api/calendar/create/event Access token
Permission Prerequisite Kakao Login User consent
Required Register platforms
Activate Kakao Login
Manage consent items		 Required Required:
Refer to Usage policy

This API lets users create 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 (reminder 5 minutes before the event ends) < reminder value ≤ 43200 (reminder 30 days before the event starts)
- One-time event: 0 (start time of event) ≤ reminder value ≤ 43200 (reminder 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
Location
Name Type Description Required
name String Location name.
Up to 100 characters are allowed.		 O*
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

* Required when creating an event.

Time
Name Type Description Required
start_at String Time when the event starts.
Can be set for 5 minute intervals.
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")		 O*
end_at String Time when the event ends.
Same format as start_at.		 O*
time_zone String Time zone. (Default: Asia/Seoul)
In the case of all-day event, time_zone is not ignored because a day is applied instead of start_at and end_at times.		 X
all_day Boolean Whether the event is all-day or timed event.
- true: All-day event.
- false: Timed event.
If set to true, the value of start_at and end_at must be "00:00:00Z". Otherwise, an error occurs.
(Default: false)		 X
lunar Boolean Whether the event is solar or lunar calendar.
- true: Lunar calendar.
- false: Solar calendar.
(Default: false)		 X

* Required when creating an event.

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

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 Register platforms
Activate Kakao Login
Manage consent items		 Required Required:
Refer to Usage policy

This API lets users retrieve 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 Register platforms
Activate Kakao Login
Manage consent items		 Required Required:
Refer to Usage policy

This API lets users retrieve 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
Location
Name Type Description Required
name String Location name. O
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
Name Type Description Required
start_at String Time when the event starts in YYYY-MM-DDThh:mm:ssZ format. (Example: "2022-05-17T00:00:00Z") O
end_at String Time when the event ends in YYYY-MM-DDThh:mm:ssZ format. (Example: "2022-05-17T00:00:00Z") O
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
time_zone String Time zone. (Default: Asia/Seoul) 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 Register platforms
Activate Kakao Login
Manage consent items		 Required Required:
Refer to Usage policy

This API lets a user edit 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.

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 (reminder 5 minutes before the event ends) < reminder value ≤ 43200 (reminder 30 days before the event starts)
- One-time event: 0 (start time of event) ≤ reminder value ≤ 43200 (reminder 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 Register platforms
Activate Kakao Login
Manage consent items		 Required Required:
Refer to Usage policy

This API lets a user delete 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.

You need to obtain permission to use public event APIs. Before permission is granted, you can test the following APIs via developers-sample app on [Tools] > [REST API Test]:

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 Register platforms
Activate Kakao Login
Manage consent items
Set Kakao Talk Channel		 Required Required:
Refer to Usage policy

This API lets your service create a public event.

Send a POST request with your admin key in the request header. You must pass your service's Kakao Talk Channel 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 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 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 (reminder 5 minutes before the event ends) < reminder value ≤ 43200 (reminder 30 days before the event starts)
- One-time event: 0 (start time of event) ≤ reminder value ≤ 43200 (reminder 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 Register platforms
Activate Kakao Login
Manage consent items
Set Kakao Talk Channel		 Required Required:
Refer to Usage policy

This API lets your service retrieve 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 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 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 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 as PUBLIC.		 O
time TimeDefault Time information. O
color String Color of the event.
Refer to Color.		 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). (Example: "2022-05-17T00:00:00Z")		 O
end_at String Time when the event ends.
Same format as start_at.		 O
all_day Boolean Whether the event is all-day or timed event.
- true: All-day event.
- false: Timed event.		 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 Register platforms
Activate Kakao Login
Manage consent items
Set Kakao Talk Channel		 Required Required:
Refer to Usage policy

This API lets your service retrieve 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 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 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 as 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 Register platforms
Activate Kakao Login
Manage consent items
Set Kakao Talk Channel		 Required Required:
Refer to Usage policy

This API lets your service edit 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 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.

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 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 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 (reminder 5 minutes before the event ends) < reminder value ≤ 43200 (reminder 30 days before the event starts)
- One-time event: 0 (start time of event) ≤ reminder value ≤ 43200 (reminder 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 Register platforms
Activate Kakao Login
Manage consent items
Set Kakao Talk Channel		 Required Required:
Refer to Usage policy

This API lets your service delete 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 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 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 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 Register platforms
Activate Kakao Login
Manage consent items
Set Kakao Talk Channel		 Required Required:
Refer to Usage policy

This API let users follow public events published by your service's Kakao Talk Channel.

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 Messaging 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 Register platforms
Activate Kakao Login
Manage consent items		 Required Required:
Refer to Usage policy

This API lets your service retrieve the list of the available calendars that a user can subscribe to. You are required to obtain permission to use this API. See Request permission.

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
Category
Name Type Description Required
name String Category name which the subscribed calendars are included in. O
subcategories Subcategory[] List of subscribed calendars. 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"
                        }
                    ]
                }
            ]
        }
    ]
}

Subscribe

Basic information
Method URL Authorization
POST https://kapi.kakao.com/v2/api/calendar/subscribe Access token
Permission Prerequisite Kakao Login User consent
Required Register platforms
Activate Kakao Login
Manage consent items		 Required Required:
Refer to Usage policy

This API lets users subscribe to your service's calendar. You are required to obtain permission to use this API. See Request permission. 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 Register platforms
Activate Kakao Login
Manage consent items		 Required Required:
Refer to Usage policy

This API lets users unsubscribe from your service's calendar. You are required to obtain permission to use this API. See Request permission.

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 Messaging 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.

Edit event for attendee

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 Register platforms
Activate Kakao Login
Manage consent items		 Required Required:
Refer to Usage policy

This API lets a user edit a particular public event or subscribed event added to a user's calendar.

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.

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 (reminder 5 minutes before the event ends) < reminder value ≤ 43200 (reminder 30 days before the event starts)
- One-time event: 0 (start time of event) ≤ reminder value ≤ 43200 (reminder 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
- Register platforms
Activate Kakao Login
Manage consent items		 - -

This API retrieves holidays in the Republic of Korea for a certain requested period of time 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

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 holidays and celebrations 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
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 Register platforms
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.

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.		 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 Register platforms
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 following:
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 Register platforms
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 Register platforms
Activate Kakao Login
Manage consent items		 Required Required:
Refer to Usage policy

Edit a particular task. Cannot edit the tasks registered on KakaoTalk 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)

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)		 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 Register platforms
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 Register platforms
Activate Kakao Login
Manage consent items		 Required Required:
Refer to Usage policy

Deletes a particular task. Cannot delete the tasks registered on KakaoTalk 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}"
}

See more

Talk Calendar> REST API