Pipedrive API 조직

Pipedrive에서 **조직(Organization)**은 거래를 진행하고 있는 회사나 그 밖의 단체를 뜻해요. 영업 CRM에서 고객사가 바로 이 조직으로 표현되는데, 조직 안에는 한 명 또는 여러 명의 연락처(Person)가 소속될 수 있어서 '회사 = 조직, 회사 안의 사람 = 연락처'라고 이해하면 됩니다. 사람 한 명이 여러 조직에 걸쳐 있을 수도 있고, 반대로 조직이 비어 있을 수도 있죠. API를 다룰 때 이 관계가 가장 먼저 잡혀야 헷갈리지 않아요.

이 문서에서는 조직을 생성하고, 목록을 조회하고, 검색하고, 연락처·거래와 어떻게 이어지는지, 그리고 응답이 어떤 형태로 돌아오는지를 차례로 살펴볼게요. 참고로 현재 공식 문서 페이지에서는 조직의 핵심 CRUD 엔드포인트가 API v2(경로 앞에 /v1이 붙지 않는 형태)로 서비스되고 있어요. 같은 동작을 주고받는 방식 자체는 v1과 동일한 패턴이니, 아래 경로 기준으로 흐름을 익혀두면 됩니다.

출처: 문서

본문

조직이란 무엇인가

조직은 거래를 맺고 있는 회사 및 기타 단체를 의미합니다. 조직은 연락처(Person)와 연결되어 "하나의 조직은 한 명 이상의 연락처를 포함할 수 있다"는 구조를 갖습니다. 덕분에 같은 회사에서 여러 사람과 대화해도 데이터는 한 조직 아래로 모이고, 그 조직에 걸린 거래(Deal)도 함께 관리되는 식이에요.

조직 생성

조직을 새로 만들 때는 POST /organizations를 호출합니다. 요청 본문에서 필수 필드는 name 하나뿐이고, 나머지는 선택적으로 채울 수 있어요. 대표적인 필드는 다음과 같습니다.

{
  "name": "The name of the organization",
  "owner_id": 1,
  "add_time": "2025-01-01T10:00:00Z",
  "visible_to": 3,
  "label_ids": [1, 2],
  "address": {
    "value": "The full address of the organization",
    "country": "Country of the organization",
    "admin_area_level_1": "Admin area level 1 (e.g. state) of the organization",
    "admin_area_level_2": "Admin area level 2 (e.g. county) of the organization",
    "locality": "Locality (e.g. city) of the organization",
    "sublocality": "Sublocality (e.g. neighborhood) of the organization",
    "route": "Route (e.g. street) of the organization",
    "street_number": "Street number of the organization",
    "subpremise": "Subpremise (e.g. apartment/suite number) of the organization",
    "postal_code": "Postal code of the organization"
  },
  "website": "https://example.com",
  "industry": 1,
  "annual_revenue": 1000000,
  "employee_count": 50
}

owner_id: 조직을 소유한 사용자의 ID
visible_to: 조직의 공개 범위(visibility)
label_ids: 조직에 할당된 라벨 ID 배열
address: 주소를 세분화된 객체로 관리(국가, 시·도, 도시, 거리, 우편번호 등)
website, linkedin, industry, annual_revenue, employee_count 등은 선택 입력
custom_fields: 각 키가 커스텀 필드를 나타내는 객체. 커스텀 필드는 무작위 생성된 40자 해시로 참조됩니다. 값을 지우려면 null로 설정하고, 여러 값 선택(set) 필드도 null로 비워야 해요. 빈 배열 []을 보내면 검증 오류가 나므로 주의하세요.

권한은 API 키 또는 OAuth2(contacts:full)가 필요합니다.

조직 조회

전체 조직 목록은 GET /organizations로 가져옵니다. 상세 조회는 GET /organizations/{id}로 특정 조직 하나를 가져오죠. 목록 조회에서 쓸 수 있는 대표 쿼리 파라미터는 다음과 같아요.

파라미터	설명
`filter_id`	지정하면 해당 필터에 일치하는 조직만 반환
`ids`	최대 100개까지 조직 ID를 콤마로 나열해 조회(`filter_id`가 있으면 무시)
`owner_id`	지정한 사용자가 소유한 조직만 반환(`filter_id`가 있으면 무시)
`updated_since` / `updated_until`	`update_time` 기준 시간 범위 필터(RFC3339 형식, 예: `2025-01-01T10:20:00Z`)
`sort_by`	정렬 필드. `id`, `update_time`, `add_time` 지원(기본 `id`)
`sort_direction`	`asc` / `desc`(기본 `asc`)
`include_fields`	응답에 추가로 포함할 필드. `open_deals_count`, `people_count`, `email_messages_count` 등
`custom_fields`	관심 있는 커스텀 필드 키만 지정(최대 15개) — 응답을 빠르고 작게 만들 때 유용
`include_labels`	`true`면 라벨을 `{ id, label }` 객체 배열로 포함
`limit` / `cursor`	페이지네이션. 기본 100개, 최대 500개

다음과 같이 호출할 수 있어요.

curl -G 'https://api.pipedrive.com/v1/organizations' \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>' \
  -d 'filter_id=12' \
  -d 'sort_by=add_time' \
  -d 'sort_direction=desc' \
  -d 'limit=100'

단일 조직의 응답(data)에는 id, name, owner_id, add_time, update_time, is_deleted, visible_to, address 등이 포함됩니다.

조직 검색

조직을 키워드로 찾을 때는 GET /organizations/search를 씁니다.

파라미터	설명
`term`	검색어(필수). 최소 2자(`exact_match`면 1자), URL 인코딩 필요
`fields`	콤마로 구분한 검색 대상 필드. 지정하지 않으면 전체
`exact_match`	`true`면 정확히 일치하는 결과만 반환(대소문자 구분 없음)
`limit` / `cursor`	페이지네이션. 기본 100개, 최대 500개

curl -G 'https://api.pipedrive.com/v1/organizations/search' \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>' \
  --data-urlencode 'term=Acme' \
  -d 'exact_match=false'

권한은 API 키 또는 OAuth2(contacts:read, contacts:full, search:read)가 필요합니다.

연락처·거래와의 관계

조직은 연락처(Person)와 한 조직이 여러 연락처를 포함하는 관계로 묶이고, 거래(Deal)는 조직에 연결되어 관리됩니다. 각 하위 엔드포인트로 조직에 속한 데이터를 조회할 수 있어요.

GET /organizations/{id}/followers — 조직의 팔로워 목록
GET /organizations/{id}/mailMessages — 조직과 연결된 메일 메시지
GET /organizations/{id}/files — 조직에 첨부된 파일
GET /organizations/{id}/flow — 조직에 대한 업데이트 내역
GET /organizations/{id}/changelog — 조직 필드 값의 변경 이력
GET /organizations/{id}/permittedUsers — 조직에 접근 가능한 사용자 목록

두 조직을 하나로 합칠 때는 PUT /organizations/{id}/merge를 사용합니다.

응답 구조

API 응답은 대체로 success와 data를 담는 기본 구조를 따릅니다. success는 요청 성공 여부를 나타내는 불리언이고, data에 실제 데이터가 들어오죠.

{
  "success": true,
  "data": {
    "id": 1,
    "name": "The name of the organization",
    "owner_id": 1,
    "add_time": "2025-01-01T10:00:00Z",
    "update_time": "2025-01-02T09:30:00Z",
    "is_deleted": false,
    "visible_to": 3,
    "address": {
      "value": "The full address of the organization"
    }
  }
}

더 알아보기

공식 문서 — Organizations API