Reference

This document guides the specification of the REST API provided by the Kakao API platform.

Request

The request format for Kakao APIs consists of the elements below.

Element	Description
Method	An HTTP request method is required to be specified for a Kakao API request. (Example: GET, POST, PUT, DELETE)
Host	The domain that receives requests for Kakao APIs. (Example: kapi.kakao.com)
URL	The URL indicates the path to request each resource provided by Kakao APIs. The endpoint of each Kakao API consists of the URL and the host. (Example: /v2/user/me)
Header	The header is used to pass data for authorization or additional data. An access token or an app key is used as the authorization information. Some Kakao APIs require additional information in the header, such as ad account ID. (Example: Authorization: Bearer ${ACCESS_TOKEN})
Path variable	The path variable is used to specify the URL, including the custom value. Some Kakao APIs include path variables in the URL. (Example: /openapi/v4/campaigns/${id})
Parameter	The parameter is used to pass data for the request. The parameter can be passed through a query string or in the body. The parameter consists of a key and a value. The data type and whether it is required for the request are specified for each parameter.

The specification for each Kakao API is indicated in each product's documentation.

Note: Security settings

Set a list of Allowed IP address, or use a client secret code to enhance security.

Response

Response format

The Kakao API server returns the response in the following format for each request:

• On success: HTTP status code, a JSON including response fields
• On failure: HTTP status code, a JSON including an error code including code as an integer and msg as a string

Here are some sample responses below.

Example: Fail, Invalid token

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error=invalid_token

{
  "code":-401,
  "msg":"InvalidTokenException"
}

Example: Fail, Exceeding API quota limit

HTTP/1.1 400 Forbidden  
{
  "code":-10,
  "msg":"API limit has been exceeded."
}

Example: Fail, No permission to send Kakao Talk message

HTTP/1.1 403 Forbidden
{
  "msg": "insufficient scopes.",
  "code": -402,
  "api_type": "TALK_MEMO_DEFAULT_SEND",
  "required_scopes": [
    "talk_message"
  ],
  "allowed_scopes": [
    "profile",
    "account_email"
  ]
}

The code passed in the error response message body is a negative integer without any specific rule. The msg, passed along with the code, indicates the cause of request failure and may be different depending on the requested APIs. For example, in the case of code is -401, different msg can be passed according to the APIs as follows:

If requesting with invalid app key or access token

"this access token does not exist", "this access token is already expired", "appKey(xxxxxxxx) is already deactivated"

If requesting API from domain not registered in [My Application] > [Platform]

"domain mismatched! caller=xxxxxxxx. check out registered web domains."

If client information does not match the one registered in [My Application] > [Platform]

"android keyhash mismatched! caller=xxxxxxxx. check out registered keyhash."
"ios bundle id mismatched! caller=xxxxxxxx. check out registered bundle id."

If requesting with IP address not registered in [My Application] > [Allowed IP Address]

"ip mismatched! callerIp=xxxxxxxx. check out registered ips."

Response code

Response codes include an HTTP status code indicating the status of the request and an error code about the error information. If the request is successful, the response body is returned with a status code of 200. If failed, an error code with the code and msg is returned.

HTTP status code

The HTTP status code is a 3-digit integer in the first line of a response message, indicating the request result (success or failure). The status codes are classified into five, and the first digit of the status code defines the types of response. Refer to RFC 2616 to see more about HTTP status code.

Here is the list of HTTP status codes that the Kakao platform transmits.

Status code	Status	Description
200 OK	Success	Indicates that the server has received and processed the client's request successfully. The format of the response body may differ depending on APIs. Refer to the detailed description of each API.
400 Bad Request	Fail	General error Indicates the state in which the server has detected a client error related to required parameters and cannot process the request.
401 Unauthorized	Fail	Authorization error (mostly related to tokens) Indicates that the request has failed because the client has no valid authorization credentials for the resource. NOTE: As specified in OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC6750), the 401 errors include the WWW-Authenticate header field as follows: - If access token is used,    "WWW-Authenticate: Bearer error=invalid_token" - If app admin key is used,    "WWW-Authenticate: KakaoAK error=invalid_token" invalid_token is fixed for 401 errors. Refer to the error response body to figure out the error in detail.
403 Forbidden	Fail	Permission Error Indicates that the server has received the client's request but rejected it because the client has no permission.
429 Too Many Request	Fail	Quota exceeded (Only for Daum Search, Local, Moment, and Keyword Ad APIs) Indicates that the quota limit or the limit per second for the API has been exceeded.
500 Internal Server Error	Fail	System error 500 refers to the class of server errors, indicating that the server is in an unexpected situation while processing the request.
502 Bad Gateway	Fail	System error Indicates that communication is not working properly because a gateway converts to another wrong protocol or has something wrong with the converting protocol.
503 Service Unavailable	Fail	Undergoing maintenance Indicates that the server is not ready to process the request.

Error code

Here are the lists of codes passed when the request fails for each API that the Kakao platform provides. If an error occurs, check the code received in the following table to figure out its cause.

Common

code	Description	HTTP status code
-1	If an error occurs while the server is internally processing. Solution: Retry.	400
-2	If some required parameters are not included, or if the argument value has the wrong data type or is out of the acceptable range. Solution: Check the request parameters.	400
-3	If the required function for the API, such as Simple Signup, Consent Items, services settings, etc.), is not activated. Solution: Select [My application] > {SERVICE_NAME}, enable the function under the Activation Settings and then make a request again.	403
-4	If an account has been blocked or restricted to do some actions.	403
-5	If the app has no permission to request the API. Solution: Request a review to use the API, and then make a request again.	403
-7	If the service is undergoing maintenance or has an internal problem. Solution: Check the Notice on the service.	400
-8	If the header is invalid. Solution: Check the request header.	400
-9	If the API has been terminated its service. Solution: Check the Notice mail or Notice.	400
-10	If the allowed quota limit has been exceeded. Solution: Check the allowed quota limit and request an API less than the quota limit. Refer to the quota.	400
-401	If the request has been made with an invalid app key or access token, or if the app does not match the registered app information. Solution: Check the app key in [My Application] or reissue an access token. Check the app information registered in [My Application].	401
-501	If a user who has not signed up for Kakao Talk or suspended calls the Kakao Talk Messaging API or the Talk Calendar API.	400
-602	If the file size of the uploaded image exceeds the maximum size.	400
-603	If a timeout occurs while processing the request on the Kakao Platform.	400
-606	If exceeding the maximum number of images to upload.	400
-903	If the request has been made with an unregistered developer's app key or an access token that consists of an unregistered developer's app key.	400
-911	If using an image file with the unsupported format to upload.	400
-9798	If the service is undergoing maintenance.	503

Kakao Login

To use login-based APIs, the Kakao Account of the object who uses the APIs must link with the service app.

Code	Description	HTTP status code
-101	If a user whose Kakao Account is not linked to the app makes a request. Solution: Retry after linking the Kakao Account to the app through Kakao Login.	400
-102	If requested the manual signup API with an access token of a user who is already linked to the app.	400
-103	If the request has been made with a dormant or invalid Kakao Account.	400
-201	If tried to retrieve or store the value of the invalid user property key. Solution: Go to [My Application] > [Kakao Login] > [User Properties] to check registered keys, and add a new user properly or use the registered user property for the request parameter.	400
-402	If a user has not agreed to provide the user information (scope) that the API attempts to access. Solution: Check the required_scopes in the response body, and request additional consent to the scope.	403
-406	If a user under age 14 calls the API from the app that does not allow the users under age 14.	401

Message

Code	Description	HTTP status code
-502	If the recipient is not the sender's friend. Solution: Retry to make a request after cached data expires.	400
-530	If the recipient refuses to receive a message.	400
-532	If the sender requests to send a message after exceeding the quota limit allowed to send a message regardless of recipients from a specific app during a day.	400
-533	If exceeding the quota limit, allowed to receive a message from a specific app during a day.	400
-536	If exceeding the quota limit, allowed to send and receive a message between a sender and a recipient during a day.	400

Kakao Talk Channel

Code	Description	HTTP status code
-541	If the Kakao Talk Channel does not exist.	400
-544	If the Kakao Talk Channel is banned.	400
-815	Internal error related to Kakao Talk Channel API.	400
-816	If used a wrong customer file ID, or if it fails to find the customer file ID among the uploaded Kakao Talk Channel customer files.	400
-817	If tried to register customer file API using the existing file name or unallowed file name.	400
-818	If exceeding the maximum number of the customer files. Up to 30 files are allowed including the files uploaded to the Kakao Talk Channel Admin Center.	400
-819	If a Kakao Talk Channel and a service app are not connected. Solution: Connect the Kakao Talk Channel and the app in Kakao Business.	400

Talk Calendar

Code	Description	HTTP status code
-520	If the requsted public event ID or calendar ID does not exist.	400
-521	If tried to edit or delete a task on the Kakao Talk profile sticker.	400

Kakao Moment

For more error code information, refer to Kakao Moment > Reference.

Code	Description	HTTP status code
-813	Internal error related to Kakao Moment APIs occurs.	400

Kakao Keyword Ad

This section is available in Korean only. For more error code information, refer to the original Korean documentation.

Code	Description	HTTP status code
-820	Internal error related to Kakao Keyword Ad APIs occurs.	400

Push Notification

Code	Description	HTTP status code
-901	If a push notification sent to a device that does not have any registered push token.	400

API list

Here are the lists of URLs, hosts, and methods required when making a request to use each function that the REST API supports.

Kakao Login

URL	Host	Method	Function
/oauth/authorize	https://kauth.kakao.com	GET	Getting authorization code, Requesting additional consent, Getting consent to desired service terms, Auto-login from Kakao Talk
/oauth/token	https://kauth.kakao.com	POST	Getting tokens, Refreshing tokens
/v1/user/logout	https://kapi.kakao.com	POST	Logout
/v1/user/signup	https://kapi.kakao.com	POST	Manual signup
/v1/user/unlink	https://kapi.kakao.com	POST	Unlink
/v1/user/access_token_info	https://kapi.kakao.com	GET	Retrieving token information
/v2/user/me	https://kapi.kakao.com	GET/POST	Retrieving user information
/v1/user/shipping_address	https://kapi.kakao.com	GET	Retrieving shipping address
/v1/user/update_profile	https://kapi.kakao.com	POST	Storing user information
/v1/user/ids	https://kapi.kakao.com	GET/POST	Retrieving user list
/v2/app/users	https://kapi.kakao.com	GET	Retrieving multiple user information
/v2/user/scopes	https://kapi.kakao.com	GET	Retrieving consent details
/v2/user/revoke/scopes	https://kapi.kakao.com	POST	Revoking consent
/v2/user/service_terms	https://kapi.kakao.com	GET	Retrieving consent details for service terms
/v2/user/revoke/service_terms	https://kapi.kakao.com	POST	Revoking consent for service terms
/v2/user/upgrade/service_terms	https://kapi.kakao.com	POST	Set consent to service terms
/v1/user/signup	https://kapi.kakao.com	POST	Manual signup

OpenID Connect

URL	Host	Method	Function
/.well-known/jwks.json	https://kauth.kakao.com	GET	Getting public key
/.well-known/openid-configuration	https://kauth.kakao.com	GET	Retrieving Discovery document
/v1/oidc/userinfo	https://kapi.kakao.com	GET	Retrieving user information for OIDC
/oauth/tokeninfo	https://kauth.kakao.com	POST	Getting ID token information

Kakao Talk Social

URL	Host	Method	Function
/v1/api/talk/profile	https://kapi.kakao.com	GET	Retrieving Kakao Talk profile
/v1/api/talk/friends	https://kapi.kakao.com	GET	Retrieving list of friends

Message

URL	Host	Method	Function
/v2/api/talk/memo/default/send	https://kapi.kakao.com	POST	Sending me message with default template
/v2/api/talk/memo/send	https://kapi.kakao.com	POST	Sending me message with custom template
/v2/api/talk/memo/scrap/send	https://kapi.kakao.com	POST	Sending me scrap message with default template, Sending me scrap message with custom template
/v1/api/talk/friends/message/default/send	https://kapi.kakao.com	POST	Sending friends message with default template
/v1/api/talk/friends/message/send	https://kapi.kakao.com	POST	Sending friends message with custom template
/v1/api/talk/friends/message/scrap/send	https://kapi.kakao.com	POST	Sending friends scrap message with default template, Sending friends scrap message with custom template

Kakao Talk Channel

URL	Host	Method	Function
/v2/api/talk/channels	https://kapi.kakao.com	GET	Checking Kakao Talk Channel relationship
/v2/api/talk/channels/multi	https://kapi.kakao.com	GET	Checking multiple users' Kakao Talk Channel relationship
/v1/talkchannel/create/target_user_file	https://kapi.kakao.com	POST	Customer management: Register customer file
/v1/talkchannel/target_user_file	https://kapi.kakao.com	GET	Customer management: View customer file
/v1/talkchannel/update/target_users	https://kapi.kakao.com	POST	Customer management: Add user
/v1/talkchannel/delete/target_users	https://kapi.kakao.com	POST	Customer management: Delete user

Kakao Moment

Refer to Kakao Moment API reference.

Kakao Keyword Ad

Refer to Kakao Keyword Ad API reference. This document is available in Korean only.

Push Notification

URL	Host	Method	Function
/v2/push/register	https://kapi.kakao.com	POST	Registering push token
/v2/push/tokens	https://kapi.kakao.com	GET	Retrieving push token
/v2/push/deregister	https://kapi.kakao.com	POST	Deleting push token
/v2/push/send	https://kapi.kakao.com	POST	Sending push notifications

Talk Calendar

URL	Host	Method	Function
/v2/api/calendar/calendars	kapi.kakao.com	GET	Retrieving list of calendars
/v2/api/calendar/create/calendar	kapi.kakao.com	POST	Creating sub-calendar
/v2/api/calendcalendar-delete-subar/update/calendar	kapi.kakao.com	POST	Editing sub-calendar
/v2/api/calendar/delete/calendar	kapi.kakao.com	DELETE	Deleting sub-calendar
/v2/api/calendar/create/event	kapi.kakao.com	POST	Creating event
/v2/api/calendar/events	kapi.kakao.com	GET	Retrieving list of events
/v2/api/calendar/event	kapi.kakao.com	GET	Retrieving details of event
/v2/api/calendar/update/event/host	kapi.kakao.com	POST	Editing event for host
/v2/api/calendar/update/event/guest	kapi.kakao.com	POST	Editing event for attendee
/v2/api/calendar/delete/event	kapi.kakao.com	DELETE	Deleting event
/v2/api/calendar/public/create/event	kapi.kakao.com	POST	Creating public event
/v2/api/calendar/public/events	kapi.kakao.com	GET	Retrieving list of public events
/v2/api/calendar/public/event	kapi.kakao.com	GET	Retrieving details of public event
/v2/api/calendar/public/update/event	kapi.kakao.com	POST	Editing public event
/v2/api/calendar/public/delete/event	kapi.kakao.com	DELETE	Deleting public event
/v2/api/calendar/public/follow	kapi.kakao.com	POST	Adding public event to user calendar
/v2/api/calendar/subscribable/calendars	kapi.kakao.com	GET	Retrieving list of subscribable calendars
/v2/api/calendar/subscribe	kapi.kakao.com	POST	Subscribe
/v2/api/calendar/unsubscribe	kapi.kakao.com	DELETE	Unsubscribe
/v2/api/calendar/holidays	kapi.kakao.com	GET	Retrieving holidays and celebrations
/v1/api/calendar/create/task	https://kapi.kakao.com	POST	Create task
/v1/api/calendar/tasks	https://kapi.kakao.com	GET	Retrieve task
/v1/api/calendar/task/records	https://kapi.kakao.com	GET	Check challenge record
/v1/api/calendar/update/task	https://kapi.kakao.com	POST	Edit task
/v1/api/calendar/complete/task	https://kapi.kakao.com	POST	Set completion status
/v1/api/calendar/delete/task	https://kapi.kakao.com	DELETE	Delete task

Local

URL	Host	Method	Function
/v2/local/search/address.{format}	https://dapi.kakao.com	GET	Address search
/v2/local/geo/coord2regioncode.{format}	https://dapi.kakao.com	GET	Convert coordinates to administrative information
/v2/local/geo/coord2address.{format}	https://dapi.kakao.com	GET	Convert coordinates to address
/v2/local/geo/transcoord.{format}	https://dapi.kakao.com	GET	Convert coordinate system
/v2/local/search/keyword.{format}	https://dapi.kakao.com	GET	Place search by keyword
/v2/local/search/category.{format}	https://dapi.kakao.com	GET	Place search by category

Daum Search

URL	Host	Method	Function
/v2/search/web	https://dapi.kakao.com	GET	Web document search
/v2/search/vclip	https://dapi.kakao.com	GET	Video search
/v2/search/image	https://dapi.kakao.com	GET	Image search
/v2/search/blog	https://dapi.kakao.com	GET	Blog search
/v3/search/book	https://dapi.kakao.com	GET	Book search
/v2/search/cafe	https://dapi.kakao.com	GET	Cafe search

Utility API

URL	Host	Method	Function
/v1/system/ips	kapi.kakao.com	GET	Retrieve Kakao IP list
/api/health/current	api-status.kakao.com	GET	Check current status
api/health/history	api-status.kakao.com	GET	Check history