Pipedrive API 리드

Pipedrive API 리드

리드(Lead)는 Pipedrive에서 잠재 거래를 다루는 가장 처음 단계예요. 아직 거래(Deal)로 확정되기 전에 리드 인박스에 쌓여 있다가, 보관(archive)되거나 거래로 전환(convert)되는 중간 상태라고 생각하면 돼요. 리드가 거래와 다른 점은, 각 리드가 반드시 **이름(title)**을 가져야 하고 어떤 사람(person)이나 조직(organization)에 연결되어야 한다는 거예요. 그 외에는 거래가 가질 수 있는 대부분의 필드(value라든가 expected_close_date 같은 것들)를 그대로 가질 수 있어요.

이 문서에서는 리드 API의 핵심을 하나씩 짚어볼게요. 리드를 새로 만드는 POST /v1/leads, 조회하는 GET /v1/leads, 그리고 리드의 잠재 가치를 표현하는 value 필드 규칙과 응답 구조까지, 실제 요청/응답 예시를 보면서 정리해요. 코드와 JSON은 원문 그대로 가져왔으니 그대로 따라 하면 됩니다.

출처: 문서

본문

리드는 어떤 존재인가

원문 정의 그대로 말하면, 리드는 "Leads Inbox에 보관된 잠재 거래"예요. 거래로 전환되거나 아카이브되기 전까지 그 인박스에 머물러 있죠. 앞서 말했듯이 리드는 title 필드로 이름을 붙이고, person_id나 organization_id 중 적어도 하나에 연결되어야 해요. 둘 다 연결해도 되고요.

리드의 잠재 가치는 value 필드로 표현하는데, 이게 좀 특별해요. { "amount": 200, "currency": "EUR" }처럼 금액(amount)과 통화(currency)를 함께 담는 JSON 객체 구조인데, 두 값 모두 필수예요. 뒤에서 실제 예시로 다시 볼게요.

리드 생성: POST /v1/leads

리드를 만들 때는 title이 필수고, 리드는 항상 사람이나 조직(또는 둘 다)에 연결되어야 해요. API로 만든 모든 리드는 source와 origin이 API로 설정됩니다. 요청 본문은 아래처럼 생겼어요.

{
  "title": "Jane Doe Lead",
  "owner_id": 1,
  "label_ids": ["f08b42a0-4e75-11ea-9643-03698ef1cfd6"],
  "person_id": 1092,
  "organization_id": 1,
  "value": {
    "amount": 999,
    "currency": "USD"
  },
  "expected_close_date": "2020-10-14",
  "visible_to": "3"
}

여기서 person_id와 organization_id는 둘 중 하나는 꼭 줘야 해요. 둘 중 하나만 지정해도 되고, 물론 둘 다 지정해도 됩니다. value는 위에서 본 { amount, currency } 구조고, visible_to는 리드의 공개 범위를 의미해요. 값 1은 소유자와 팔로워(비공개), 3은 회사 전체(공유) 정도로 이해하면 되고요. (Premium/Ultimate 요금제에서는 5(그룹과 하위 그룹), 7(회사 전체)까지 쓸 수 있어요.)

생성이 성공하면 201 응답으로 생성된 리드 전체가 돌아와요.

{
  "success": true,
  "data": {
    "id": "adf21080-0e10-11eb-879b-05d71fb426ec",
    "title": "Jane Doe Lead",
    "owner_id": 1,
    "creator_id": 1,
    "label_ids": ["f08b42a0-4e75-11ea-9643-03698ef1cfd6", "f08b42a1-4e75-11ea-9643-03698ef1cfd6"],
    "person_id": 1092,
    "organization_id": null,
    "source_name": "API",
    "origin": "API",
    "origin_id": null,
    "channel": 52,
    "channel_id": "Jun23 Billboards",
    "is_archived": false,
    "was_seen": false,
    "value": {
      "amount": 999,
      "currency": "USD"
    },
    "expected_close_date": null,
    "next_activity_id": 1,
    "add_time": "2020-10-14T11:30:36.551Z",
    "update_time": "2020-10-14T11:30:36.551Z",
    "visible_to": "3",
    "cc_email": "[email protected]"
  }
}

리드 조회: GET /v1/leads

생성된 리드들을 한 번에 조회하고 싶다면 GET /v1/leads를 호출해요. 아카이브되지 않은 리드들을 반환하고, 생성 시간 기준으로 오래된 것부터 최신순으로 정렬돼요. 페이징은 limit와 start 쿼리 파라미터로 제어하고요.

curl "https://api.pipedrive.com/v1/leads?limit=100&start=0" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

주로 쓰는 쿼리 파라미터를 정리하면 이래요.

  • limit, start — 페이징. limit을 주지 않으면 100개씩 반환돼요.
  • owner_id, person_id, organization_id — 각각 소유자/사람/조직으로 필터링. 단 filter_id가 주어지면 이 필터들보다 우선해요.
  • filter_id — 저장된 필터의 ID로 조회.
  • updated_since — 주어진 시각(ISO 8601, 예: 2025-01-01T10:20:00Z) 이후로 업데이트된 리드만.
  • sort — 정렬 기준 필드와 방향. 예: title ASC, add_time DESC.

sort에 쓸 수 있는 필드는 id, title, owner_id, creator_id, was_seen, expected_close_date, next_activity_id, add_time, update_time이에요. 다만 첫 번째 레벨 필드 키만 지원하고 중첩 키는 안 된다는 점 기억하세요.

조회 응답은 success와 data(리드 배열)로 구성되고, 배열 뒤에는 additional_data가 함께 와요.

{
  "success": true,
  "data": [
    {
      "id": "adf21080-0e10-11eb-879b-05d71fb426ec",
      "title": "Jane Doe Lead",
      "owner_id": 1,
      "creator_id": 1,
      "label_ids": [
        "f08b42a0-4e75-11ea-9643-03698ef1cfd6",
        "f08b42a1-4e75-11ea-9643-03698ef1cfd6"
      ],
      "person_id": 1092,
      "organization_id": null,
      "source_name": "API",
      "origin": "API",
      "origin_id": null,
      "channel": 52,
      "channel_id": "Jun23 Billboards",
      "is_archived": false,
      "was_seen": false,
      "value": {
        "amount": 999,
        "currency": "USD"
      },
      "expected_close_date": null,
      "next_activity_id": 1,
      "add_time": "2020-10-14T11:30:36.551Z",
      "update_time": "2020-10-14T11:30:36.551Z",
      "visible_to": "3",
      "cc_email": "[email protected]"
    }
  ],
  "additional_data": {
    "start": 0,
    "limit": 100,
    "more_items_in_collection": false
  }
}

단일 리드 하나만 보고 싶다면 GET /v1/leads/{id}를 쓰면 되고, 그 {id}는 위에서 본 UUID 형식이에요. 리드를 찾지 못하면 404 응답이 오는데, "error": "requested lead not found"처럼 오류 내용을 돌려줍니다.

응답 구조와 필드 살펴보기

리드 응답에서 자주 쓰이는 필드들을 한 번 훑어볼게요.

  • id — 리드의 고유 ID(UUID 형식).
  • title — 리드 이름.
  • owner_id / creator_id — 리드를 소유한/만든 사용자 ID.
  • person_id / organization_id — 리드가 연결된 사람/조직의 ID. 없으면 null이에요.
  • value — 잠재 가치. { "amount", "currency" } 구조이며 둘 다 필수.
  • expected_close_date — 거래로 전환됐을 때 거래가 닫힐 것으로 예상되는 날짜(ISO 8601 YYYY-MM-DD).
  • add_time / update_time — 리드 생성/수정 시각(ISO 8601 YYYY-MM-DDTHH:MM:SSZ).
  • visible_to — 공개 범위(1, 3, 5, 7).
  • cc_email — 리드의 BCC 이메일 주소.

여기서 꼭 알아둘 게 하나 있어요. 리드는 별도의 커스텀 필드 집합을 가지지 않고, 거래(Deals)의 커스텀 필드 구조를 그대로 상속받아요. 리드에 커스텀 필드 값이 설정되지 않았다면 응답에 그 필드가 아예 나타나지 않고, 값이 있다면 Deals 엔드포인트와 같은 형식으로 포함됩니다.

그 외 리드 관련 엔드포인트

리드를 다루는 API가 생성/조회만 있는 건 아니에요. 주요한 것들만 짚어보면:

  • PATCH /v1/leads/{id} — 리드의 일부 속성 수정. 요청에 포함된 속성만 업데이트되고, null을 보내면 속성을 해제할 수 있어요(예: value, person_id, organization_id).
  • DELETE /v1/leads/{id} — 특정 리드 삭제.
  • GET /v1/leads/{id}/permittedUsers — 리드에 접근이 허용된 사용자 ID 목록.
  • GET /v1/leads/search — 제목, 메모, 커스텀 필드로 리드 검색.
  • POST /v1/leads/{id}/convert/deal — 리드를 거래로 전환. 리드를 전환하면 원래 있던 노트, 파일, 이메일, 활동 등 관련 엔티티가 대상 엔티티로 함께 옮겨지고, 성공하면 리드는 삭제된 것으로 표시돼요.

더 알아보기

  • 공식 문서 — Pipedrive API v1 리드 레퍼런스에서 전체 파라미터와 응답 스키마를 직접 확인할 수 있어요.