Organization

워크스페이스에서 부서, 직위, 직책과 같은 조직도 정보를 조회하기 위해 다음과 같은 API를 사용합니다.

표Organization API 리스트

구분	API 명	설명
부서 정보 조회	departments.list	특정 워크스페이스에 속한 전체 부서 목록 및 상세 정보 조회
직위 정보 조회	positions.list	특정 워크스페이스에 속한 전체 직위 목록 및 상세 정보 조회
직책 정보 조회	responsibilities.list	특정 워크스페이스에 속한 전체 직책 목록 및 상세 정보 조회

departments.list

워크스페이스에 속한 전체 부서 정보를 조회합니다.

Request

Request Syntax

코드예제departments.list Request Syntax

BASH

  curl -X GET https://api.kakaowork.com/v1/departments.list \
   -H "Authorization: Bearer {YOUR_APP_KEY}"

표API 호출 방식

메서드	요청 URL
GET	`https://api.kakaowork.com/v1/departments.list`

Request Header

Request Header에 대한 상세는 다음과 같습니다.

표departments.list Request Header

파라미터	타입	필수 여부	설명
Authorization	String	`필수`	`Bearer {YOUR_APP_KEY}` - `{YOUR_APP_KEY}`: Bot 등록 요청 후에 획득한 인증키(App Key)
Content-Type	String	`선택`	`application/json` 또는 `application/x-www-form-urlencoded`

Request Elements

Request Elements에 대한 상세는 다음과 같습니다.

표departments.list Request Elements

파라미터	타입	필수 여부	설명
limit	String	`선택`	한 번에 가져올 수 있는 데이터 개수 - 기본값: 10, 최대값: 100
cursor	String	`선택`	다음 API 호출 시에 사용할 페이징 커서(Cursor)

안내
Pagination의 자세한 규칙은 Pagination을 참고하시기 바랍니다.

Response

Response Syntax

코드예제departments.list Response Syntax

JSON

{
  "success": true,
  "departments": {
    /* ... departments entity ... */
  },
  "cursor": " /* ... 다음 호출 항목이 있으면 커서(Curosr) 키, 없으면 null */ "
}

Response Elements

Response Elements에 대한 상세는 다음과 같습니다.

표departments.list Response Elements

필드	타입	필수 여부	설명
success	Boolean	`필수`	API 호출 실행 결과
			`true`: 성공, `departments`와 `cursor` 필드 함께 반환
			`false`: 실패, `error` 필드와 함께 반환
	Object[]	`선택`	부서의 상세 정보 - API 호출 성공(`true`)일 경우 제공
id	String	`필수`	부서의 ID
space_id	String	`필수`	부서가 속한 워크스페이스의 ID
name	String	`필수`	부서명
code	String	`필수`	부서를 구분하는 고유 값
user_count	Integer	`필수`	팀원 수 - 하위 부서의 팀원 수는 포함하지 않음
has_child	Boolean	`선택`	하위 부서가 있는지 여부
depth	Integer	`선택`	부서 Depth 레벨
user_ids	Integer[]	`선택`	팀원 정보
leader_ids	Integer[]	`선택`	리더 정보
ancestry	String	`선택`	현재 부서의 상위 부서들 ID 경로(`/`로 구분)
cursor	String	`선택`	다음 API 호출 시에 쓰일 페이징 커서(Cursor) - API 호출 성공(`true`)일 경우 제공
	Object	`선택`	API 실행 오류 정보 - API 호출 실패(`false`)일 경우 제공
code	String	`필수`	오류 상황을 구분하는 코드
			`invalid_parameter`: 제공된 파라미터의 값이 올바르지 않음
			`invalid_authentication`: 제공된 인증키가 유효하지 않음
			`invalid_representation`: 유효하지 않은 포맷의 Body 데이터
			`api_not_found`: 요청 API의 URL 혹은 HTTP 메서드와 다름
			`unauthorized`: 인증키가 제공되지 않음
			`internal_server_error`: 정의되지 않은 서버 오류 발생
			`too_many_requests`: API 사용 한도가 초과됨
			`expired_authentication`: 제공된 인증키가 만료됨
			`invalid_content_type`: 요청이 API가 요구하는 Content Type과 다름
			`missing_parameter`: 필요한 파라미터 값이 제공되지 않았음
message	String	`필수`	오류 원인에 대한 설명

positions.list

워크스페이스에 속한 전체 직위 정보를 조회합니다.

Request

Request Syntax

코드예제positions.list Request Syntax

BASH

  curl -X GET https://api.kakaowork.com/v1/positions.list \
   -H "Authorization: Bearer {YOUR_APP_KEY}"

표API 호출 방식

메서드	요청 URL
GET	`https://api.kakaowork.com/v1/positions.list`

Request Header

Request Header에 대한 상세는 다음과 같습니다.

표positions.list Request Header

파라미터	타입	필수 여부	설명
Authorization	String	`필수`	`Bearer {YOUR_APP_KEY}` - `{YOUR_APP_KEY}`: Bot 등록 요청 후에 획득한 인증키(App Key)
Content-Type	String	`선택`	`application/json` 또는 `application/x-www-form-urlencoded`

Request Elements

Request Elements에 대한 상세는 다음과 같습니다.

표positions.list Request Elements

파라미터	타입	필수 여부	설명
limit	String	`선택`	한 번에 가져올 수 있는 데이터 개수 - 기본값: 10, 최대값: 100
cursor	String	`선택`	다음 API 호출 시에 사용할 페이징 커서(Cursor)

안내
Pagination의 자세한 규칙은 Pagination을 참고하시기 바랍니다.

Response

Response Syntax

코드예제positions.list Response Syntax

JSON

{
  "success": true,
  "positions": {
    /* ... positions entity ... */
  },
  "cursor": " /* ... 다음 호출 항목이 있으면 커서(Curosr) 키, 없으면 null */ "
}

Response Elements

Response Elements에 대한 상세는 다음과 같습니다.

표positions.list Response Elements

필드	타입	필수 여부	설명
success	Boolean	`필수`	API 호출 실행 결과
			`true`: 성공, `positions`와 `cursor` 필드 함께 반환
			`false`: 실패, `error` 필드와 함께 반환
	Object[]	`선택`	직위의 상세 정보 - API 호출 성공(`true`)일 경우 제공
name	String	`필수`	직위명
code	String	`필수`	직위를 구분하는 고유 값
level	Integer	`필수`	직위 레벨 - 값이 낮을수록 높은 직위
cursor	String	`선택`	다음 API 호출 시에 쓰일 페이징 커서(Cursor) - API 호출 성공(`true`)일 경우 제공
	Object	`선택`	API 실행 오류 정보 - API 호출 실패(`false`)일 경우 제공
code	String	`필수`	오류 상황을 구분하는 코드
			`invalid_parameter`: 제공된 파라미터의 값이 올바르지 않음
			`invalid_authentication`: 제공된 인증키가 유효하지 않음
			`invalid_representation`: 유효하지 않은 포맷의 Body 데이터
			`api_not_found`: 요청 API의 URL 혹은 HTTP 메서드와 다름
			`unauthorized`: 인증키가 제공되지 않음
			`internal_server_error`: 정의되지 않은 서버 오류 발생
			`too_many_requests`: API 사용 한도가 초과됨
			`expired_authentication`: 제공된 인증키가 만료됨
			`invalid_content_type`: 요청이 API가 요구하는 Content Type과 다름
			`missing_parameter`: 필요한 파라미터 값이 제공되지 않았음
message	String	`필수`	오류 원인에 대한 설명

responsibilities.list

워크스페이스에 속한 전체 직위 정보를 조회합니다.

Request

Request Syntax

코드예제responsibilities.list Request Syntax

BASH

  curl -X GET https://api.kakaowork.com/v1/responsibilities.list \
   -H "Authorization: Bearer {YOUR_APP_KEY}"

표API 호출 방식

메서드	요청 URL
GET	`https://api.kakaowork.com/v1/responsibilities.list`

Request Header

Request Header에 대한 상세는 다음과 같습니다.

표responsibilities.list Request Header

파라미터	타입	필수 여부	설명
Authorization	String	`필수`	`Bearer {YOUR_APP_KEY}` - `{YOUR_APP_KEY}`: Bot 등록 요청 후에 획득한 인증키(App Key)
Content-Type	String	`선택`	`application/json` 또는 `application/x-www-form-urlencoded`

Request Elements

Request Elements에 대한 상세는 다음과 같습니다.

표responsibilities.list Request Elements

파라미터	타입	필수 여부	설명
limit	String	`선택`	한 번에 가져올 수 있는 데이터 개수 - 기본값: 10, 최대값: 100
cursor	String	`선택`	다음 API 호출 시에 사용할 페이징 커서(Cursor)

안내
Pagination의 자세한 규칙은 Pagination을 참고하시기 바랍니다.

Response

Response Syntax

코드예제responsibilities.list Response Syntax

JSON

{
  "success": true,
  "responsibilities": {
    /* ... responsibilities entity ... */
  },
  "cursor": " /* ... 다음 호출 항목이 있으면 커서(Curosr) 키, 없으면 null */ "
}

Response Elements

Response Elements에 대한 상세는 다음과 같습니다.

표responsibilities.list Response Elements

필드	타입	필수 여부	설명
success	Boolean	`필수`	API 호출 실행 결과
			`true`: 성공, `responsibilities`와 `cursor` 필드 함께 반환
			`false`: 실패, `error` 필드와 함께 반환
	Object[]	`선택`	직책의 상세 정보 - API 호출 성공(`true`)일 경우 제공
name	String	`필수`	직책명
code	String	`필수`	직책을 구분하는 고유 값
level	Integer	`필수`	직책 레벨 - 값이 낮을수록 높은 직책
cursor	String	`선택`	다음 API 호출 시에 쓰일 페이징 커서(Cursor) - API 호출 성공(`true`)일 경우 제공
	Object	`선택`	API 실행 오류 정보 - API 호출 실패(`false`)일 경우 제공
code	String	`필수`	오류 상황을 구분하는 코드
			`invalid_parameter`: 제공된 파라미터의 값이 올바르지 않음
			`invalid_authentication`: 제공된 인증키가 유효하지 않음
			`invalid_representation`: 유효하지 않은 포맷의 Body 데이터
			`api_not_found`: 요청 API의 URL 혹은 HTTP 메서드와 다름
			`unauthorized`: 인증키가 제공되지 않음
			`internal_server_error`: 정의되지 않은 서버 오류 발생
			`too_many_requests`: API 사용 한도가 초과됨
			`expired_authentication`: 제공된 인증키가 만료됨
			`invalid_content_type`: 요청이 API가 요구하는 Content Type과 다름
			`missing_parameter`: 필요한 파라미터 값이 제공되지 않았음
message	String	`필수`	오류 원인에 대한 설명

kakaoIdocumentation

Kakao Work::Web API 레퍼런스::Organization

페이지 이동경로

Organization

departments.list

Request

Request Syntax

Request Header

Request Elements

Response

Response Syntax

Response Elements

positions.list

Request

Request Syntax

Request Header

Request Elements

Response

Response Syntax

Response Elements

responsibilities.list

Request

Request Syntax

Request Header

Request Elements

Response

Response Syntax

Response Elements