Pipedrive API 연락처

Pipedrive에서 연락처(Person)는 거래(deal)를 진행하는 손님, 즉 CRM에 담는 고객 정보를 말해요. 각 연락처는 하나의 조직(organization)에 속할 수 있고, 반드시 사용자(user)와 구분해서 생각해야 해요. Pipedrive API에서 이 연락처를 만들고, 조회하고, 검색하고, 수정하는 작업이 모두 Persons API를 통해 이루어져요.

이 문서를 작성할 때 참고한 공식 레퍼런스는 현재 v1과 v2를 하나로 합친 형태로 제공되고 있어요. 그래서 연락처의 핵심 CRUD(생성·조회·수정·삭제)와 검색은 v2 경로(/api/v2/persons)로, 그림·병합·파일·변경 내역 등 일부 하위 기능은 기존 v1 경로(/api/v1/persons/{id}/...)로 제공되고 있으니, 예제 코드를 볼 때 버전 경로를 함께 확인해 주세요.

출처: 문서

본문

연락처가 뭐예요?

공식 문서는 연락처를 이렇게 설명해요.

Persons are your contacts, the customers you are doing deals with. Each person can belong to an organization. Persons should not be confused with users.

즉 "연락처는 거래를 진행하는 손님이고, 조직에 소속될 수 있으며, 사용자(user)와 혼동하면 안 된다"는 뜻이에요. API 관점에서 연락처는 person 객체로 표현되고, 이 객체가 거래·조직·활동 등 다른 리소스와 연결되는 기준점이 돼요.

연락처 생성하기 (POST)

새 연락처를 만들 때는 /api/v2/persons로 POST 요청을 보내요. 현재 공식 레퍼런스에서는 다음 v2 엔드포인트로 제공되고 있어요.

POST /api/v2/persons

요청 본문(body)에서 가장 기본적인 필드는 이렇게 구성돼요. 이메일(emails)과 전화(phones)는 value(실제 주소·번호), primary(대표 여부), label(분류 라벨)을 가진 배열로 담아요.

{
  "name": "홍길동",
  "owner_id": 1234,
  "org_id": 5678,
  "emails": [
    { "value": "[email protected]", "primary": true, "label": "work" }
  ],
  "phones": [
    { "value": "+82 10 1234 5678", "primary": true, "label": "work" }
  ],
  "visible_to": 3,
  "label_ids": [1, 2],
  "custom_fields": {
    "custom_field_hash_key": "값"
  }
}

이때 name은 필수(required) 필드고, 나머지는 선택이에요. visible_to는 연락처의 공개 범위, custom_fields에는 커스텀 필드를 넣어요.

커스텀 필드와 contact sync 주의점

커스텀 필드는 객체 형태로 전달하며, 각 커스텀 필드는 무작위로 생성된 40자짜리 해시 키로 참조돼요. 값을 비우고 싶으면 null로 설정하면 되고, 다중 선택 필드(set 타입)는 null로 선택을 해제해요. 빈 배열 []을 보내면 검증 오류(validation error)가 나니 주의해야 해요.

또 하나 꼭 알아둘 점이 있어요. im, postal_address, notes, birthday, job_title 필드는 Pipedrive에 기본으로 존재하지 않아요. 이 필드들은 contact sync(연락처 동기화)를 설정할 때만 만들어지고, contact sync가 꺼진 상태에서 이 필드를 설정하려 하면 403 에러가 반환돼요.

연락처 조회하기 (GET)

모든 연락처 목록을 가져올 때는 /api/v2/persons로 GET 요청을, 특정 연락처 하나를 가져올 때는 /api/v2/persons/{id}로 GET 요청을 보내요. 여기서 {id}는 연락처의 고유 ID예요.

GET /api/v2/persons
GET /api/v2/persons/{id}

목록 조회에서는 다양한 쿼리 파라미터로 결과를 걸러낼 수 있어요.

filter_id: 지정한 필터에 맞는 연락처만 반환
owner_id: 특정 사용자가 소유한 연락처만 반환
org_id: 특정 조직에 연결된 연락처만 반환
deal_id: 특정 거래에 연결된 연락처만 반환
updated_since / updated_until: 수정 시각 범위로 필터링 (RFC3339 형식, 예: 2025-01-01T10:20:00Z)
sort_by / sort_direction: 정렬 기준(id, update_time, add_time)과 방향(asc, desc)
custom_fields: 결과에 포함할 커스텀 필드 키들을 콤마로 구분해 전달 (최대 15개, 빠른 응답을 위해 필요한 것만 넣어요)
limit / cursor: 페이지네이션. limit 기본값 100, 최대 500

페이지네이션 커서

목록이 길 때는 limit으로 한 페이지당 개수를 정하고, 다음 페이지를 가리키는 cursor(불투명한 문자열)를 받아서 이어서 요청해요. 이 커서 기반 페이지네이션이 연락처 목록 조회의 기본 방식이에요.

연락처 검색하기

이름·이메일·전화·메모·커스텀 필드로 연락처를 통틀어 검색하고 싶을 때는 전용 검색 엔드포인트를 써요. 이 엔드포인트는 내부적으로 /v1/itemSearch를 감싼 형태로, 더 좁은 OAuth 범위로 동작해요.

GET /api/v2/persons/search

주요 파라미터는 이렇게 돼요.

term (필수): 검색어. 최소 2자(정확 일치 exact_match를 쓰면 1자). URL 인코딩이 필요해요.
fields: 검색할 필드를 콤마로 나열. 기본값은 전체(custom_fields, email, notes, phone, name). 검색 가능한 커스텀 필드 타입은 address, varchar, text, varchar_auto, double, monetary, phone이에요.
exact_match: true로 켜면 주어진 검색어와 정확히 일치하는 결과만 반환 (대소문자 구분 없음)
organization_id: 특정 조직에 속한 연락처로 결과를 필터링 (해당 조직과 연결된 연락처는 최대 2000개)
limit / cursor: 페이지네이션

연락처 수정·삭제하기

수정은 /api/v2/persons/{id}로 PATCH, 삭제는 같은 경로로 DELETE 요청을 보내요. 삭제는 즉시 지우는 게 아니라 **삭제 표시(mark as deleted)**를 하고, 30일 후에 영구 삭제돼요.

PATCH  /api/v2/persons/{id}
DELETE /api/v2/persons/{id}

PATCH 본문은 생성(POST)과 같은 필드를 받아들이고, 마케팅 상태(marketing_status) 관련해서는 no_consent, unsubscribed, subscribed, archived 네 가지 값을 사용할 수 있어요. 마케팅 상태는 한 번에 한 단계씩만 바꿀 수 있고, 이메일 주소가 유효하지 않은 연락처는 기본값으로 no_consent가 반환된다는 점을 알아두면 좋아요.

응답 구조 (Response)

Pipedrive API 응답은 공통으로 이 구조를 따라요. success가 성공 여부, data가 실제 데이터, 그리고 목록·검색 응답에는 additional_data로 페이지네이션 등의 부가 정보가 담겨요.

{
  "success": true,
  "data": [
    ...
  ],
  "additional_data": {
    ...
  }
}

단일 연락처 조회(/api/v2/persons/{id})나 생성·수정·삭제 응답에서는 data가 배열이 아니라 단일 객체 형태로 오는 점도 참고해 두세요.

그 밖의 v1 하위 기능들

연락처와 연결된 세부 기능 중에는 아직 v1 경로로 제공되는 것도 있어요. 대표적으로 이렇게 구분할 수 있어요.

GET /api/v1/persons/{id}/changelog — 연락처 필드 값 변경 내역
GET /api/v1/persons/{id}/files — 연락처에 첨부된 파일 목록
GET /api/v1/persons/{id}/flow — 연락처에 대한 변경 내역(활동·거래·댓글 등)
GET /api/v1/persons/{id}/mailMessages — 연락처와 연결된 메일 목록
GET /api/v1/persons/{id}/products — 연락처와 연결된 제품 목록
PUT /api/v1/persons/{id}/merge — 두 연락처 병합 (merge_with_id로 우선 유지할 연락처 지정)
POST /api/v1/persons/{id}/picture / DELETE /api/v1/persons/{id}/picture — 연락처 사진 추가·삭제

이 중 일부는 v1/v2 양쪽을 모두 제공하는데, 페이지에서 /v1 to /v2 migration 가이드를 통해 차이를 확인할 수 있어요. v1 사용 중이라면 새로 만들 때는 v2 경로를 쓰는 걸 권장해요.

더 알아보기

공식 문서