kakao developers

REST API Reference

This document provides the URL information required to make a request using a REST API and a list of response codes passed in response to your request.

Requirements

If you call the Kakao APIs through a REST API, your server and development environments must meet the following minimum versions:

Name	Supported version
OS X	Mavericks or higher
Windows	Windows XP SP3 or higher
Java	JRE 1.8.0_101 or higher
Browser	Chrome 49 or higher Firefox 50 or higher Safari 10 or higher Internet Explorer (IE) 9 or higher Microsoft Edge 14 or higher
CentOS/RHEL	ca-certificates-2015.2.4-65.0.1.el6_6.noarch or higher

* Notice: Replacing SSL certificates in Kakao Open 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. Refer Requirements together.

Note: Security settings

You can 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 Server 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 when you request the Kakao APIs and the descriptions.

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 you have exceeded the quota limit or request the limit per second for the API.
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 your request is failed for each API that the Kakao platform provides. If an error occurs, check the code you 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 if you request some actions that may cause the account to block.	403
-5	If you have 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 you request with the invalid header. Solution: Check the request header.	400
-9	If you call the API that has been terminated its service. Solution: Check the Notice mail or Notice.	400
-10	If you have exceeded the allowed quota limit. Solution: Check the allowed quota limit and request an API less than the quota limit. Refer to the quota and FAQ.	400
-401	If you call an API using an invalid app key or access token, or if the app you requested does not match the registered app information. Solution: Check your app key in [My Application] or retrieve the expired tokens. 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 you can upload.	400
-903	If you request an API using an unregistered developer's app key or an access token that consists of an unregistered developer's app key.	400
-911	If you upload an image file with the unsupported format.	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 your app makes a request. Solution: Retry after linking the Kakao Account to the app through Kakao Login.	400
-102	If you request to link a user who is already linked to an app using the user's access token.	400
-103	If you request an API with a dormant or invalid Kakao Account.	400
-201	If you attempt to retrieve or store the key value of a user property not registered in your app when calling the Retrieving user information API or the Storing user information API. Solution: Go to [My Application] > [Kakao Login] > [User Properties] to check what user properties you have registered, 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
-531	If the sender requests to send a message after exceeding the quota limit, allowed to send a message to a specific recipient from a specific app during a day.	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
-534	If exceeding the quota limit, allowed to receive a message from a specific app during a month.	400
-536	If exceeding the quota limit, allowed to send and receive a message between a sender and a recipient during a day.	400
-541	If the Kakao Talk Channel does not exist.	400

Kakao Story

code	Description	HTTP status code
-601	If a user who is not a Kakao Story user calls the API that is only allowed for Kakao Stroy users.	400
-604	If it fails to scrape in Kakao Story.	400
-605	If you request to retrieve my story that does not exist in Kakao Story.	400
-608	If a user who is not a Kakao Story Channel user requests the Kakao Story Channel API.	400

Kakao Talk Channel

Code	Description	HTTP status code
-815	Internal error related to Kakao Talk Channel's customer file management occurs.	400
-816	If you request an API using the 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 you request the Registering customer file API using the existing file name or unallowed file name.	400
-818	If exceeding the maximum number of the customer files you can register. You can upload up to 30 files 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 your Kakao Talk Channel and your 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

Kakao Pay

This section is available in Korean only. Refer to the original Korean documentation.

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 you send a push notification to a device that does not have any registered push token.	400

Artificial Intelligence

Code	Description	HTTP status code
-830	Internal error related to KoGPT and Karlo APIs occurs.	500
-831	If exceeding the server's processing capacity due to a temporary surge of requests.	503

Supported APIs

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

When you make an HTTP request, you must use HTTPS to secure the connection between browsers and web servers using the Secure Sockets Layer (SSL). You need a REST API key for a login, and you need the access token issued once logged in to call the APIs that require a login.

Kakao Login

URL	HOST	METHOD	Function
/oauth/authorize	https://kauth.kakao.com	GET	Getting authorization code, Requesting additional consent, Getting consent to desired 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
/v1/user/service/terms	https://kapi.kakao.com	GET	Retrieving user agreed 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 Story

URL	HOST	METHOD	Function
/v1/api/story/isstoryuser	https://kapi.kakao.com	GET	Validating Kakao Story user
/v1/api/story/profile	https://kapi.kakao.com	GET	Retrieving Kakao Talk profile
/v1/api/story/post/note	https://kapi.kakao.com	POST	Posting text story
/v1/api/story/post/photo	https://kapi.kakao.com	POST	Posting photo story
/v1/api/story/post/link	https://kapi.kakao.com	POST	Posting link story
/v1/api/story/mystory	https://kapi.kakao.com	GET	Retrieving specified story
/v1/api/story/mystories	https://kapi.kakao.com	GET	Retrieving multiple stories
/v1/api/story/delete/mystory	https://kapi.kakao.com	DELETE	Deleting story
/v1/api/story/upload/multi	https://kapi.kakao.com	POST	Uploading image
/v1/api/story/linkinfo	https://kapi.kakao.com	GET	Scraping web page

Kakao Talk Channel

URL	HOST	METHOD	Function
/v1/api/talk/channels	https://kapi.kakao.com	GET	Checking 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 Pay

URL	HOST	METHOD	Function
/v1/payment/ready	https://kapi.kakao.com	POST	Preparing single payment, Initial subscription payment
/v1/payment/approve	https://kapi.kakao.com	POST	Approving single payment
/v1/payment/subscription	https://kapi.kakao.com	POST	Second subscription payment request
/v1/payment/cancel	https://kapi.kakao.com	POST	Canceling payments
/v1/payment/order	https://kapi.kakao.com	POST	Viewing orders
/v1/payment/manage/subscription/status	https://kapi.kakao.com	POST	Retrieving subscription status
/v1/payment/manage/subscription/inactive	https://kapi.kakao.com	POST	Disabling subscription

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/calendar/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

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

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