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 [App] > [General] > [Platform]

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

If client information does not match the one registered in [App] > [General] > [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 [App] > [General] > [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

See Error code.

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	Get authorization code, Request additional consent, Get consent to desired service terms, Auto-login from Kakao Talk
/oauth/token	https://kauth.kakao.com	POST	Get tokens, Refresh 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	Get token information
/v2/user/me	https://kapi.kakao.com	GET/POST	Get user information
/v1/user/shipping_address	https://kapi.kakao.com	GET	Get shipping address
/v1/user/update_profile	https://kapi.kakao.com	POST	Store user information
/v1/user/ids	https://kapi.kakao.com	GET/POST	Get user list
/v2/app/users	https://kapi.kakao.com	GET	Get multiple user information
/v2/user/scopes	https://kapi.kakao.com	GET	Get consent details
/v2/user/revoke/scopes	https://kapi.kakao.com	POST	Revoke consent
/v2/user/service_terms	https://kapi.kakao.com	GET	Get consent details for service terms
/v2/user/revoke/service_terms	https://kapi.kakao.com	POST	Revoke 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	Get public key
/.well-known/openid-configuration	https://kauth.kakao.com	GET	Get Discovery document
/v1/oidc/userinfo	https://kapi.kakao.com	GET	Get user information for OIDC
/oauth/tokeninfo	https://kauth.kakao.com	POST	Get ID token information

Kakao Talk Social

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

Kakao Talk Message

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

Kakao Talk Channel

URL	Host	Method	Function
/v2/api/talk/channels	https://kapi.kakao.com	GET	Check Kakao Talk Channel relationship
/v2/api/talk/channels/multi	https://kapi.kakao.com	GET	Check 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	Register push token
/v2/push/tokens	https://kapi.kakao.com	GET	Retrieve push token
/v2/push/deregister	https://kapi.kakao.com	POST	Revoke push token
/v2/push/send	https://kapi.kakao.com	POST	Send push notifications

Talk Calendar

URL	Host	Method	Function
/v2/api/calendar/calendars	kapi.kakao.com	GET	Get list of calendars
/v2/api/calendar/create/calendar	kapi.kakao.com	POST	Create sub-calendar
/v2/api/calendcalendar-delete-subar/update/calendar	kapi.kakao.com	POST	Edit sub-calendar
/v2/api/calendar/delete/calendar	kapi.kakao.com	DELETE	Delete sub-calendar
/v2/api/calendar/create/event	kapi.kakao.com	POST	Create event
/v2/api/calendar/events	kapi.kakao.com	GET	Get list of events
/v2/api/calendar/event	kapi.kakao.com	GET	Get details of event
/v2/api/calendar/update/event/host	kapi.kakao.com	POST	Edit event for host
/v2/api/calendar/update/event/guest	kapi.kakao.com	POST	Edit event for attendee
/v2/api/calendar/delete/event	kapi.kakao.com	DELETE	Delete event
/v2/api/calendar/public/create/event	kapi.kakao.com	POST	Create public event
/v2/api/calendar/public/events	kapi.kakao.com	GET	Get list of public events
/v2/api/calendar/public/event	kapi.kakao.com	GET	Get details of public event
/v2/api/calendar/public/update/event	kapi.kakao.com	POST	Edit public event
/v2/api/calendar/public/delete/event	kapi.kakao.com	DELETE	Delete public event
/v2/api/calendar/public/follow	kapi.kakao.com	POST	Add public event to user calendar
/v2/api/calendar/subscribable/calendars	kapi.kakao.com	GET	Get 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	Get 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	Convert address to coordinates
/v2/local/geo/coord2regioncode.{format}	https://dapi.kakao.com	GET	Convert coordinates to region code
/v2/local/geo/coord2address.{format}	https://dapi.kakao.com	GET	Convert coordinates to address
/v2/local/geo/transcoord.{format}	https://dapi.kakao.com	GET	Transform coordinates
/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	Search web document
/v2/search/vclip	https://dapi.kakao.com	GET	Search video
/v2/search/image	https://dapi.kakao.com	GET	Search image
/v2/search/blog	https://dapi.kakao.com	GET	Search blog
/v3/search/book	https://dapi.kakao.com	GET	Search book
/v2/search/cafe	https://dapi.kakao.com	GET	Search Cafe

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