Enterprise API로 조직 관리하기

인사·조직 시스템에서 회사, 그룹, 멤버를 API로 관리하는 방법을 안내해요.

업데이트: 2026년 9월

Enterprise API는 기업 조직의 마스터 관리자가 회사, 그룹(부서), 멤버를 외부 시스템에서 직접 관리할 수 있는 REST API예요. 인사 시스템과 연동해 입사·이동·퇴사를 자동으로 반영할 수 있어요.

개요

회사와 그룹(부서) 트리를 추가하고 수정하고 비활성화할 수 있어요.
멤버를 추가하면 계정이 자동으로 만들어지고, 사번·직급코드·직책코드·휴대폰번호 같은 속성도 함께 관리돼요.
모든 변경은 조직 감사 로그에 기록되고, 삭제는 이력이 보존되는 비활성화 방식으로 동작해요.

사용 조건과 토큰 발급

기업모드(조직도)가 활성화된 조직의 마스터 계정으로 로그인해요.
기업 관리 → Enterprise API 탭에서 토큰 이름, 권한 범위, IP 허용 목록을 입력하고 토큰을 발급해요.
발급 직후 한 번만 표시되는 토큰 값을 안전한 곳에 보관해요. 서버에는 원문이 저장되지 않아요.

인증

모든 요청은 아래 형식의 Bearer 인증 헤더를 사용해요.

Base URL: https://monogpt.kr/api/enterprise/v1
Authorization: Bearer entapi_...

토큰마다 IP 허용 목록이 필수예요. 허용되지 않은 IP의 요청은 403으로 거부되고 감사 로그에 남아요.
권한 범위는 read(조회)와 write(추가·변경·비활성화) 두 가지예요.
회수한 토큰은 다시 활성화할 수 없고, 필요하면 새 토큰을 발급해요.
요청 한도는 토큰당 조회 분당 120회, 변경 분당 30회이고 초과하면 429와 Retry-After 헤더를 받아요.

선택 요청 헤더

헤더	설명
Idempotency-Key	8~128자. 같은 키와 같은 본문으로 재요청하면 저장된 결과를 그대로 재응답해요(replayed: true). 같은 키에 다른 본문을 보내면 409예요. 네트워크 재시도 안전을 위해 권장해요.
If-Match	조직 구조 revision 값. 현재 revision과 다르면 409와 함께 currentRevision을 돌려줘요.

조직 스냅샷 조회

GET /organization은 별도 파라미터 없이도 활성·비활성 사업장(companies), 부서(groups), 임직원(members)을 모두 반환해요. DELETE로 비활성화한 항목도 포함되므로 재등록 전에 기존 항목인지 확인할 수 있어요.

요청	반환 범위
GET /organization	활성·비활성 모두 (기본값)
GET /organization?includeInactive=true 또는 ?status=all	활성·비활성 모두
GET /organization?includeInactive=false 또는 ?status=active	활성만

각 항목의 status는 active 또는 inactive예요. 응답 data.includeInactive는 비활성 포함 여부를 나타내며 기본값은 true예요.
회사는 code, 부서는 companyId와 code, 임직원은 email로 기존 항목을 대조해요. 수정할 때는 조회된 companyId 또는 groupId를 사용해요.
includeInactive는 true/false와 1/0을 지원해요. 두 필터를 함께 지정하면 전체 조회를 요청하는 값이 우선해요. 허용되지 않은 값은 400 ENTERPRISE_API_INVALID_REQUEST를 반환해요.
비활성 임직원의 phone은 null이에요. 종료된 부서 배정은 현재 소속이 아니므로 groupId와 HR 코드도 null일 수 있어요.
임직원은 최대 5만 명까지 포함해요. membersTruncated가 true이면 /members?status=active와 /members?status=inactive를 각각 페이지 조회해요. 응답의 nextCursor를 다음 요청의 afterId로 보내면 돼요.

아래는 응답의 일부 필드와 비활성 항목을 보여주는 예시예요. ID와 이메일은 설명용 값이에요.

{
  "success": true,
  "revision": "7",
  "data": {
    "includeInactive": true,
    "companies": [{"companyId": "100", "code": "COMPANY_A", "status": "inactive"}],
    "groups": [{"groupId": "200", "companyId": "100", "code": "TEAM_A", "status": "inactive"}],
    "members": [{"email": "[email protected]", "status": "inactive", "groupId": null, "phone": null}],
    "membersTruncated": false
  }
}

회사·부서는 기존 ID에 PATCH {"status":"active"}를 보내 재활성화해요. 비활성 임직원은 POST /members에 같은 이메일과 이름, 활성 부서의 groupId를 보내 재활성화해요. 임직원 PATCH는 현재 활성 임직원의 정보 수정용이에요. 재활성화에는 기존 상위 조직·계정 상태와 권한 조건이 적용돼요.

회사 API

메서드	경로	본문
POST	/companies	{ code, name, parentCompanyId?, sortOrder? }
PATCH	/companies/{companyId}	{ name?, parentCompanyId?, sortOrder?, status? }
DELETE	/companies/{companyId}	없음 — 비활성화

code는 조직 전체에서 유일해야 해요.
활성 하위 회사나 그룹이 남아 있으면 비활성화할 수 없고, 재활성화는 PATCH에 status를 active로 보내면 돼요.

그룹 API

메서드	경로	본문
POST	/groups	{ companyId, code, name, parentGroupId?, sortOrder? }
PATCH	/groups/{groupId}	{ name?, parentGroupId?, sortOrder?, status? }
DELETE	/groups/{groupId}	없음 — 비활성화

그룹을 만들면 크레딧 그룹이 자동으로 연결되고, 크레딧 배정은 기업 관리 콘솔에서 진행해요.
하위 그룹이나 배정된 멤버가 남아 있으면 비활성화할 수 없어요.

멤버 API

메서드	경로	본문
GET	/members	email, groupId, status, limit, afterId 쿼리 지원
POST	/members	{ email, name, groupId, employeeCode?, gradeCode?, titleCode?, phone?, sendInviteEmail? }
PATCH	/members/{email}	{ name?, phone?, groupId?, employeeCode?, gradeCode?, titleCode? }
DELETE	/members/{email}	없음 — 비활성화

GET /members는 기본적으로 활성 임직원만 반환해요. 비활성 임직원은 status=inactive로 조회해요. 기본적으로 양쪽을 모두 포함하는 GET /organization과 조회 범위가 달라요.
계정이 없는 이메일이면 자동으로 만들어지고, 임시 비밀번호가 응답에 한 번만 담겨요. 첫 로그인에서 비밀번호 변경이 요구돼요.
groupId를 바꾸면 부서 이동으로 처리되고 크레딧 소속도 함께 정리돼요.
이메일 변경은 지원하지 않아요. 비활성화 후 새 이메일로 다시 추가해 주세요.
마스터 계정과 그룹 관리자 권한이 있는 멤버는 이 API로 조작할 수 없어요.

직급·직책 코드 라벨 API

코드에 표시용 명칭을 연결해요. 보낸 코드만 반영되고 빈 문자열을 보내면 그 코드의 라벨이 삭제돼요.

GET /code-labels
PUT /code-labels    {"grade": {"SM2": "부장"}, "title": {"17": "팀장"}}

조직 전체 동기화 API

기업 관리 콘솔의 조직도 양식(XLSX)을 통으로 업로드해 워크북에 등장한 회사 범위를 한 번에 재정비해요.

POST /organization/sync    {"workbookBase64": "<xlsx base64>", "dryRun": true}

워크북은 조직정보 시트(회사코드/부서코드/부서명/상위부서코드)와 인원정보 시트(회사코드/사번/이름/메일주소/부서코드/직급코드/직책코드)로 구성돼요. 콘솔의 양식 다운로드와 같은 형식이에요.
워크북에 등장한 회사코드의 하위 트리만 변경 범위예요. 워크북에 없는 다른 회사·그룹·멤버는 건드리지 않아요.
범위 안에서 워크북에 없는 그룹과 멤버는 비활성화되고, 계정이 없는 이메일은 자동으로 만들어져 임시 비밀번호가 응답에 한 번만 담겨요. 마스터 같은 보호 계정 행은 건너뛰고 skippedProtected로 알려줘요.
dryRun을 true로 보내면 아무것도 바꾸지 않고 변경 계획 요약만 받아요. 실제 반영 전에 dryRun으로 먼저 확인해 주세요.
한 번에 그룹 500개, 멤버 1,000명, 신규 계정 300개까지 처리할 수 있고, 이 요청만 본문 10MB까지 허용돼요.

오류 코드

코드	상태	의미
ENTERPRISE_API_UNAUTHORIZED	401	토큰이 없거나 유효하지 않아요.
ENTERPRISE_API_IP_DENIED	403	허용 목록에 없는 IP예요.
ENTERPRISE_API_SCOPE_FORBIDDEN	403	토큰에 필요한 권한 범위가 없어요.
ENTERPRISE_API_DUPLICATE_CODE	409	이미 존재하는 회사·그룹 코드예요.
ENTERPRISE_API_HAS_ACTIVE_CHILDREN	409	활성 하위 항목이나 배정 멤버가 남아 있어요.
ENTERPRISE_API_ORG_EDIT_IN_PROGRESS	409	콘솔에서 조직도를 편집하는 중이에요.
ENTERPRISE_API_REVISION_MISMATCH	409	If-Match revision이 현재 값과 달라요.
ENTERPRISE_API_RATE_LIMITED	429	요청 한도를 초과했어요.

호출 예시

멤버를 추가하면서 사번과 직급·직책 코드를 함께 등록하는 예시예요.

curl -X POST https://monogpt.kr/api/enterprise/v1/members \
  -H "Authorization: Bearer entapi_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hr-sync-0001" \
  -d '{"email":"[email protected]","name":"홍길동","groupId":"1234",
       "employeeCode":"10001","gradeCode":"SM2","titleCode":"17","phone":"010-1234-5678"}'

부서 이동과 직책 변경은 PATCH 한 번으로 처리돼요.

curl -X PATCH https://monogpt.kr/api/enterprise/v1/members/hong%40example.com \
  -H "Authorization: Bearer entapi_..." \
  -H "Content-Type: application/json" \
  -d '{"groupId":"1300","titleCode":"10"}'

활성·비활성 항목을 포함한 조직 전체 현황은 별도 파라미터 없이 스냅샷 한 번으로 받아요.

curl https://monogpt.kr/api/enterprise/v1/organization \
  -H "Authorization: Bearer entapi_..."

주의 사항

모든 변경은 조직 정합성 검증을 통과해야 반영되고, 실패하면 전체가 되돌려져요.
조직도 양식 업로드 같은 다른 동기화 방식과 병행하면 서로 덮어쓸 수 있으니 한 가지 방식을 기준으로 운영해 주세요.
요청 본문은 256KB 이하 JSON이어야 해요.

임시 비밀번호를 받지 못했거나 잃어버렸다면 기업 관리 콘솔의 비밀번호 초기화 기능을 이용해 주세요.

화면으로 따라 하기

실제 앱의 한국어 화면이며 계정·자료는 안내용 샘플이에요. 표시 항목은 권한과 선택에 따라 달라질 수 있어요.

일반 계정의 메뉴 예시예요. Enterprise API는 해당 관리 권한이 있는 계정에서만 표시돼요.

조직 관리자 계정으로 로그인하고 조직 관리의 Enterprise API 탭을 열어요.
대상 조직과 기능별 사용 조건을 확인해요.
앞의 API 예시에서 요청 필드와 응답을 확인하고 실제 작업 대상이 맞는지 검토해요.

연동 키 전체를 캡처나 문의에 포함하지 마세요. 일반 직원이 업무 자료를 찾는 목적이면 GPTs 지식 검색을 먼저 확인해요.

이 답변이 도움이 되었나요?

Enterprise API로 조직 관리하기

인사·조직 시스템에서 회사, 그룹, 멤버를 API로 관리하는 방법을 안내해요.

업데이트: 2026년 9월

개요

회사와 그룹(부서) 트리를 추가하고 수정하고 비활성화할 수 있어요.
멤버를 추가하면 계정이 자동으로 만들어지고, 사번·직급코드·직책코드·휴대폰번호 같은 속성도 함께 관리돼요.
모든 변경은 조직 감사 로그에 기록되고, 삭제는 이력이 보존되는 비활성화 방식으로 동작해요.

사용 조건과 토큰 발급

기업모드(조직도)가 활성화된 조직의 마스터 계정으로 로그인해요.
기업 관리 → Enterprise API 탭에서 토큰 이름, 권한 범위, IP 허용 목록을 입력하고 토큰을 발급해요.
발급 직후 한 번만 표시되는 토큰 값을 안전한 곳에 보관해요. 서버에는 원문이 저장되지 않아요.

인증

모든 요청은 아래 형식의 Bearer 인증 헤더를 사용해요.

Base URL: https://monogpt.kr/api/enterprise/v1
Authorization: Bearer entapi_...

토큰마다 IP 허용 목록이 필수예요. 허용되지 않은 IP의 요청은 403으로 거부되고 감사 로그에 남아요.
권한 범위는 read(조회)와 write(추가·변경·비활성화) 두 가지예요.
회수한 토큰은 다시 활성화할 수 없고, 필요하면 새 토큰을 발급해요.
요청 한도는 토큰당 조회 분당 120회, 변경 분당 30회이고 초과하면 429와 Retry-After 헤더를 받아요.

선택 요청 헤더

헤더	설명
Idempotency-Key	8~128자. 같은 키와 같은 본문으로 재요청하면 저장된 결과를 그대로 재응답해요(replayed: true). 같은 키에 다른 본문을 보내면 409예요. 네트워크 재시도 안전을 위해 권장해요.
If-Match	조직 구조 revision 값. 현재 revision과 다르면 409와 함께 currentRevision을 돌려줘요.

조직 스냅샷 조회

요청	반환 범위
GET /organization	활성·비활성 모두 (기본값)
GET /organization?includeInactive=true 또는 ?status=all	활성·비활성 모두
GET /organization?includeInactive=false 또는 ?status=active	활성만

각 항목의 status는 active 또는 inactive예요. 응답 data.includeInactive는 비활성 포함 여부를 나타내며 기본값은 true예요.
회사는 code, 부서는 companyId와 code, 임직원은 email로 기존 항목을 대조해요. 수정할 때는 조회된 companyId 또는 groupId를 사용해요.
includeInactive는 true/false와 1/0을 지원해요. 두 필터를 함께 지정하면 전체 조회를 요청하는 값이 우선해요. 허용되지 않은 값은 400 ENTERPRISE_API_INVALID_REQUEST를 반환해요.
비활성 임직원의 phone은 null이에요. 종료된 부서 배정은 현재 소속이 아니므로 groupId와 HR 코드도 null일 수 있어요.
임직원은 최대 5만 명까지 포함해요. membersTruncated가 true이면 /members?status=active와 /members?status=inactive를 각각 페이지 조회해요. 응답의 nextCursor를 다음 요청의 afterId로 보내면 돼요.

아래는 응답의 일부 필드와 비활성 항목을 보여주는 예시예요. ID와 이메일은 설명용 값이에요.

{
  "success": true,
  "revision": "7",
  "data": {
    "includeInactive": true,
    "companies": [{"companyId": "100", "code": "COMPANY_A", "status": "inactive"}],
    "groups": [{"groupId": "200", "companyId": "100", "code": "TEAM_A", "status": "inactive"}],
    "members": [{"email": "[email protected]", "status": "inactive", "groupId": null, "phone": null}],
    "membersTruncated": false
  }
}

회사 API

메서드	경로	본문
POST	/companies	{ code, name, parentCompanyId?, sortOrder? }
PATCH	/companies/{companyId}	{ name?, parentCompanyId?, sortOrder?, status? }
DELETE	/companies/{companyId}	없음 — 비활성화

code는 조직 전체에서 유일해야 해요.
활성 하위 회사나 그룹이 남아 있으면 비활성화할 수 없고, 재활성화는 PATCH에 status를 active로 보내면 돼요.

그룹 API

메서드	경로	본문
POST	/groups	{ companyId, code, name, parentGroupId?, sortOrder? }
PATCH	/groups/{groupId}	{ name?, parentGroupId?, sortOrder?, status? }
DELETE	/groups/{groupId}	없음 — 비활성화

그룹을 만들면 크레딧 그룹이 자동으로 연결되고, 크레딧 배정은 기업 관리 콘솔에서 진행해요.
하위 그룹이나 배정된 멤버가 남아 있으면 비활성화할 수 없어요.

멤버 API

메서드	경로	본문
GET	/members	email, groupId, status, limit, afterId 쿼리 지원
POST	/members	{ email, name, groupId, employeeCode?, gradeCode?, titleCode?, phone?, sendInviteEmail? }
PATCH	/members/{email}	{ name?, phone?, groupId?, employeeCode?, gradeCode?, titleCode? }
DELETE	/members/{email}	없음 — 비활성화

GET /members는 기본적으로 활성 임직원만 반환해요. 비활성 임직원은 status=inactive로 조회해요. 기본적으로 양쪽을 모두 포함하는 GET /organization과 조회 범위가 달라요.
계정이 없는 이메일이면 자동으로 만들어지고, 임시 비밀번호가 응답에 한 번만 담겨요. 첫 로그인에서 비밀번호 변경이 요구돼요.
groupId를 바꾸면 부서 이동으로 처리되고 크레딧 소속도 함께 정리돼요.
이메일 변경은 지원하지 않아요. 비활성화 후 새 이메일로 다시 추가해 주세요.
마스터 계정과 그룹 관리자 권한이 있는 멤버는 이 API로 조작할 수 없어요.

직급·직책 코드 라벨 API

코드에 표시용 명칭을 연결해요. 보낸 코드만 반영되고 빈 문자열을 보내면 그 코드의 라벨이 삭제돼요.

GET /code-labels
PUT /code-labels    {"grade": {"SM2": "부장"}, "title": {"17": "팀장"}}

조직 전체 동기화 API

기업 관리 콘솔의 조직도 양식(XLSX)을 통으로 업로드해 워크북에 등장한 회사 범위를 한 번에 재정비해요.

POST /organization/sync    {"workbookBase64": "<xlsx base64>", "dryRun": true}

워크북은 조직정보 시트(회사코드/부서코드/부서명/상위부서코드)와 인원정보 시트(회사코드/사번/이름/메일주소/부서코드/직급코드/직책코드)로 구성돼요. 콘솔의 양식 다운로드와 같은 형식이에요.
워크북에 등장한 회사코드의 하위 트리만 변경 범위예요. 워크북에 없는 다른 회사·그룹·멤버는 건드리지 않아요.
범위 안에서 워크북에 없는 그룹과 멤버는 비활성화되고, 계정이 없는 이메일은 자동으로 만들어져 임시 비밀번호가 응답에 한 번만 담겨요. 마스터 같은 보호 계정 행은 건너뛰고 skippedProtected로 알려줘요.
dryRun을 true로 보내면 아무것도 바꾸지 않고 변경 계획 요약만 받아요. 실제 반영 전에 dryRun으로 먼저 확인해 주세요.
한 번에 그룹 500개, 멤버 1,000명, 신규 계정 300개까지 처리할 수 있고, 이 요청만 본문 10MB까지 허용돼요.

오류 코드

코드	상태	의미
ENTERPRISE_API_UNAUTHORIZED	401	토큰이 없거나 유효하지 않아요.
ENTERPRISE_API_IP_DENIED	403	허용 목록에 없는 IP예요.
ENTERPRISE_API_SCOPE_FORBIDDEN	403	토큰에 필요한 권한 범위가 없어요.
ENTERPRISE_API_DUPLICATE_CODE	409	이미 존재하는 회사·그룹 코드예요.
ENTERPRISE_API_HAS_ACTIVE_CHILDREN	409	활성 하위 항목이나 배정 멤버가 남아 있어요.
ENTERPRISE_API_ORG_EDIT_IN_PROGRESS	409	콘솔에서 조직도를 편집하는 중이에요.
ENTERPRISE_API_REVISION_MISMATCH	409	If-Match revision이 현재 값과 달라요.
ENTERPRISE_API_RATE_LIMITED	429	요청 한도를 초과했어요.

호출 예시

멤버를 추가하면서 사번과 직급·직책 코드를 함께 등록하는 예시예요.

curl -X POST https://monogpt.kr/api/enterprise/v1/members \
  -H "Authorization: Bearer entapi_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hr-sync-0001" \
  -d '{"email":"[email protected]","name":"홍길동","groupId":"1234",
       "employeeCode":"10001","gradeCode":"SM2","titleCode":"17","phone":"010-1234-5678"}'

부서 이동과 직책 변경은 PATCH 한 번으로 처리돼요.

curl -X PATCH https://monogpt.kr/api/enterprise/v1/members/hong%40example.com \
  -H "Authorization: Bearer entapi_..." \
  -H "Content-Type: application/json" \
  -d '{"groupId":"1300","titleCode":"10"}'

활성·비활성 항목을 포함한 조직 전체 현황은 별도 파라미터 없이 스냅샷 한 번으로 받아요.

curl https://monogpt.kr/api/enterprise/v1/organization \
  -H "Authorization: Bearer entapi_..."

주의 사항

모든 변경은 조직 정합성 검증을 통과해야 반영되고, 실패하면 전체가 되돌려져요.
조직도 양식 업로드 같은 다른 동기화 방식과 병행하면 서로 덮어쓸 수 있으니 한 가지 방식을 기준으로 운영해 주세요.
요청 본문은 256KB 이하 JSON이어야 해요.

임시 비밀번호를 받지 못했거나 잃어버렸다면 기업 관리 콘솔의 비밀번호 초기화 기능을 이용해 주세요.

화면으로 따라 하기

실제 앱의 한국어 화면이며 계정·자료는 안내용 샘플이에요. 표시 항목은 권한과 선택에 따라 달라질 수 있어요.

일반 계정의 메뉴 예시예요. Enterprise API는 해당 관리 권한이 있는 계정에서만 표시돼요.

조직 관리자 계정으로 로그인하고 조직 관리의 Enterprise API 탭을 열어요.
대상 조직과 기능별 사용 조건을 확인해요.
앞의 API 예시에서 요청 필드와 응답을 확인하고 실제 작업 대상이 맞는지 검토해요.

연동 키 전체를 캡처나 문의에 포함하지 마세요. 일반 직원이 업무 자료를 찾는 목적이면 GPTs 지식 검색을 먼저 확인해요.

이 답변이 도움이 되었나요?

Enterprise API로 조직 관리하기

개요

사용 조건과 토큰 발급

인증

선택 요청 헤더

조직 스냅샷 조회

회사 API

그룹 API

멤버 API

직급·직책 코드 라벨 API

조직 전체 동기화 API

오류 코드

호출 예시

주의 사항

화면으로 따라 하기

관련 아티클

Enterprise API로 조직 관리하기

개요

사용 조건과 토큰 발급

인증

선택 요청 헤더

조직 스냅샷 조회

회사 API

그룹 API

멤버 API

직급·직책 코드 라벨 API

조직 전체 동기화 API

오류 코드

호출 예시

주의 사항

화면으로 따라 하기

관련 아티클