User API Overview

The User API

The User API is a REST API that gets, adds and updates user/group/department information.

PROTOCOL FORMAT CHARACTER ENCODING ESCAPE SEQUENCE
HTTPS JSON UTF-8 Use "\"

User Authentication

The User REST API requires password authentication, with the appropriate Keys and Values set in the header of the request. If the Basic authentication security feature is also set on your domain, both headers for the Password Authentication and the Basic Authentication will be required for the request.

Password Authentication

Set "X-Cybozu-Authorization" on the request header, with a BASE64 encoded login name and password as the value.
If your log in name is "kintone" and your password is "developer", BASE64 encode "kintone:developer" and set it on the header as follows:

X-Cybozu-Authorization: a2ludG9uZTpkZXZlbG9wZXI=

Basic Authentication

If your kintone environment has set the Basic authentication security feature, add "Authorization" on the request header, with the string "Basic " and a BASE64 encoded login name and password of the Basic authentication as the value.
If the basic authentication log in name is "chocolate" and the basic authentication password is "pudding", place "Basic " in the value, followed by a BASE64 encoded "chocolate:pudding" as follows:

Authorization: Basic Y2hvY29sYXRlOnB1ZGRpbmc=

Request Headers

These request headers are used for the REST API.

HEADER VALUE
Host {subdomain}.kintone.com:443

Request URI

PURPOSE URI DETAILS
General https://{subdomain}.kintone.com/v1/{API_command}.json

This is the general format for User APIs.

Responses

HTTP status code 200 denotes that the request was successful.
Treat any other status code as errors. Errors will respond with JSON data including the following information.

KEY VALUE
message The error message. The language of the message will differ depending on the user's language settings of the kintone user used for the authentication.
id The ID of the error.
code The code of the error, to specify the type of error it is.

Sample Error Response

{
    "message":"Invalid JSON string.",
    "id":"1505999166-897850006",
    "code":"CB_IJ01"
}

Data structures used with the User API

ID type

Used for entities (user/group/departments) in kintone.
An integer between 1 - Long.MAX.

user type

Key Type Details
id ID type The user ID.
code String The log in name of the User.
ctime ISO-8601 date and time format The created datetime of the User.
mtime ISO-8601 date and time format The updated datetime of the User.
valid Boolean If the Status of the user is Active or not.
name String The display name of the User.
surName String The last name of the User.
givenName String The first name of the User.
surNameReading String The phonetic reading of the Last name.
givenNameReading String The phonetic reading of the First name.
localName String The localized display name of the User.
localNameLocale String The locale of the localized display name of the User.
timezone String The timezone of the user.
locale String The language setting of the user.
description String The "About Me" section of the user's profile.
phone String The phone number of the User.
mobilePhone String The mobile phone number of the User.
extensionNumber String The extension number of the User.
email String The Email address of the User.
callto String The Skype ID of the User.
url String The "URL" section of the user's profile.
employeeNumber String The Employee Number of the User.
birthDate ISO-8601 date format or null The Birthday of the User.
joinDate ISO-8601 date format or null The Hire Date of the User.
primaryOrganization Integer or null The Department ID of the Priority Department of the User.
sortOrder Integer The Display Order priority of the User.
customItemValues customItemValue Arrays. A list of pairs of Custom Field Names and Custom Field Codes.

department type

Key Type Details
id ID type The ID of the Department.
code String The Code of the Department.
name String The display name of the Department.
localName String The localized name of the Department.
localNameLocale String The locale of the localized name of the Department.
parentCode String The code of the Parent Department. null, if the parent is the Root.
description String The description of the Department.

title type

Key Type Details
id ID type The ID of the Job Title.
code String The code of the Job Title.
name String The name of the Job Title.
description String The description of the Job Title.

group type

Key Type Details
id ID type The ID of the Group.
code String The code of the Group.
name String The display name of the Group.
description String The description of the Group.

organizationTitle type

Key Type Details
organization department type The Department information.
title title type or null The Job Title information. null for "no title".

userTitle type

Key Type Details
user user type The User information.
title title type or null The Job Title information. null for "no title".

customItemValue type

Key Type Details
code String Code
value String Value
Was this article helpful?
0 out of 0 found this helpful
Comments
Please sign in to leave a comment.