HubSpot API 연락처

HubSpot의 CRM 연락처(Contacts) API에 대해 다뤄볼게요. 연락처 레코드는 회사와 상호작용하는 개인(고객, 리드 등)의 정보를 저장하고 있어요. 이 API로 HubSpot 계정에서 연락처 레코드를 생성하고 관리하며, HubSpot과 다른 시스템 간의 데이터를 동기화할 수 있답니다. 연락처를 한 번에 하나씩 또는 일괄(batch)로 생성·조회·업데이트·삭제할 수 있고, 회사나 거래 같은 다른 레코드와 연결(associate)하는 것도 가능해요.

출처: 문서

본문

연락처 생성 (Create contacts)

연락처를 만들려면 다음과 같이 요청해요.

하나의 연락처를 만들 때는 POST /crm/v3/objects/contacts 요청을 보내요.
여러 연락처를 만들 때는 POST /crm/v3/objects/contacts/batch/create 요청을 보내요.

요청에 연락처 데이터를 properties 객체에 넣으면 돼요. 새 연락처를 기존 레코드(회사, 거래 등)나 활동(미팅, 노트 등)과 연결하려면 associations 객체도 추가할 수 있어요. 배치 생성 시에는 멀티-스테이터스 오류를 활성화해서 어떤 레코드가 성공적으로 생성됐고 어떤 것이 실패했는지 알 수 있답니다.

속성 값으로 연락처 생성 (Create contacts with property values)

연락처를 만들 때는 연락처의 상세 정보를 저장할 연락처 속성을 포함해야 해요. 기본 HubSpot 연락처 속성이 있고, 커스텀 연락처 속성도 만들 수 있어요. 예를 들어 새 연락처를 만들 때 요청은 다음과 같이 생겼어요.

{
  "properties": {
    "email": "[email protected]",
    "firstname": "Jane",
    "lastname": "Doe"
  }
}

새 연락처를 생성할 때는 다음 속성 중 하나 이상을 반드시 포함해야 해요.

속성	타입	설명
`email`	string	연락처의 이메일 주소예요. 이메일 주소는 중복 연락처를 피하기 위한 기본 고유 식별자이므로 항상 포함하는 게 좋아요.
`firstname`	string	연락처의 이름이에요.
`lastname`	string	연락처의 성이에요.

필요에 따라 다른 속성도 추가할 수 있어요. 자주 쓰이는 속성 목록은 다음과 같아요.

lifecyclestage (enumeration) — 연락처의 라이프사이클 단계예요. 기본 옵션으로 subscriber, lead, marketingqualifiedlead, evangelist, salesqualifiedlead, opportunity, customer 등이 있어요. 커스텀 단계 값을 가져오려면 GET crm/v3/properties/0-1/lifecyclestage 요청을 보내요.
phone (string) — 연락처의 전화번호예요.
mobilephone (string) — 연락처의 휴대폰 번호예요.
fax (string) — 연락처의 팩스 번호예요.
jobtitle (string) — 연락처의 직함이에요.
address (string) — 연락처의 도로명 주소예요.
city (string) — 연락처가 있는 도시예요.
state (string) — 연락처가 있는 주(州)예요.
country (string) — 연락처가 있는 국가예요.
zip (string) — 연락처가 있는 우편번호예요.
hs_timezone (enumeration) — 연락처가 있는 시간대예요. 수동으로 설정하거나 연락처의 IP 주소에 따라 자동으로 결정될 수 있어요. 모든 시간대 값을 가져오려면 GET crm/v3/properties/0-1/hs_timezone 요청을 보내요.

계정의 모든 연락처 속성을 보려면 GET /crm/v3/properties/0-1 요청을 보내면 돼요. enumeration 속성을 포함할 때는 값을 설정하기 위해 내부 이름(internal name) 을 사용해야 해요. 내부 이름은 기본 값의 라벨을 변경해도 그대로 유지돼요.

연락처를 연관과 함께 생성 (Create contacts with associations)

새 연락처를 만들 때 associations 객체를 포함하면 기존 레코드나 활동과 연결할 수 있어요. associations 객체에는 다음 매개변수를 포함해야 해요.

매개변수	설명
`to`	연락처와 연결하려는 레코드 또는 활동으로, 고유 `id` 값으로 지정해요.
`types`	연락처와 레코드/활동 사이의 연결 유형이에요. `associationCategory`와 `associationTypeId`를 포함해요. 기본 연결 유형 ID는 associations API 가이드에 나와 있고, 커스텀 연결 유형(라벨)의 값은 associations API로 가져올 수 있어요.

예를 들어 새 연락처를 기존 회사와 이메일에 연결하는 요청은 다음과 같아요.

{
  "properties": {
    "email": "[email protected]",
    "firstname": "Jane",
    "lastname": "Doe",
    "phone": "+188****7768",
    "company": "HubSpot",
    "website": "hubspot.com",
    "lifecyclestage": "marketingqualifiedlead"
  },
  "associations": [
    {
      "to": { "id": 123456 },
      "types": [
        { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 279 }
      ]
    },
    {
      "to": { "id": 556677 },
      "types": [
        { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 197 }
      ]
    }
  ]
}

연락처 조회 (Retrieve contacts)

연락처는 개별 또는 일괄로 조회할 수 있어요. 요청 URL에 다음 쿼리 매개변수를 포함해서 특정 데이터를 가져올 수 있어요.

매개변수	설명
`properties`	응답에 반환할 속성 목록(쉼표로 구분)이에요. 요청한 속성이 정의되지 않으면 응답에 포함되지 않고, 정의됐지만 값이 없으면 `null`로 반환돼요.
`propertiesWithHistory`	응답에 반환할 현재 값과 이력 값의 속성 목록(쉼표로 구분)이에요. 요청한 속성이 정의되지 않으면 응답에 포함되지 않고, 정의됐지만 값이 없으면 `null`로 반환돼요.
`associations`	개별 연락처 또는 전체 연락처 조회 시 지원되는 매개변수로, 연결된 ID를 가져올 객체 목록(쉼표로 구분)이에요. 존재하지 않는 연결은 응답에 포함되지 않아요.

개별 연락처 조회 (Retrieve an individual contact)

연락처의 Record ID 값이나 이메일 주소로 개별 연락처를 조회할 수 있어요.

Record ID로 조회할 때는 GET /crm/v3/objects/contacts/{recordId} 요청을 보내요.
이메일 주소로 조회할 때는 GET /crm/v3/objects/contacts/{email}?idProperty=email 요청을 보내요.

다른 속성 값을 기준으로 연락처를 조회하려면 search API를 사용하면 돼요.

전체 연락처 조회 (Retrieve all contacts)

모든 연락처 목록을 요청하려면 GET /crm/v3/objects/contacts 요청을 보내요. 한 번의 요청으로 최대 100개의 연락처를 가져올 수 있어요. 100개 미만의 특정 개수를 가져오려면 limit 매개변수에 값을 추가해요. 예: ?limit=50. 이후 요청에서 추가 연락처를 가져오려면(즉, 요청에서 limit에 도달한 이후의 연락처), 이전 요청에서 반환된 after 값을 after 매개변수에 포함해요. 이 값은 다음 연락처의 Record ID예요. 예: ?after=123456.

예를 들어 50개의 연락처를 조회하려면 요청 URL이 GET /crm/v3/objects/contacts?limit=50이에요. 응답의 paging 객체 아래 after 값은 반환됐을 다음 연락처의 id예요. 다음 반환 값부터 50개를 더 요청하려면 GET /crm/v3/objects/contacts?limit=50&after={id} 요청을 보내요. after 필드는 아래 예시 응답에서 강조돼 있어요.

{
  "results": [
    {
      "id": "33451",
      "properties": {
        "createdate": "2022-06-01T14:31:48.469Z",
        "email": "[email protected]",
        "firstname": "Lorelai",
        "hs_object_id": "33451",
        "lastmodifieddate": "2025-07-07T20:27:17.947Z",
        "lastname": "Gilmore"
      },
      "createdAt": "2022-06-01T14:31:48.469Z",
      "updatedAt": "2025-07-07T20:27:17.947Z",
      "archived": false
    }
  ],
  "paging": {
    "next": {
      "after": "33452",
      "link": "https://api.hubspot.com/crm/objects/v3/contacts?limit=1"
    }
  }
}

연락처 일괄 조회 (Retrieve a batch of contacts)

연락처를 일괄 조회할 때는 Record ID(id), 이메일 주소(email), 또는 커스텀 고유 식별자 속성으로 요청할 수 있어요. 일괄 조회를 요청하려면 POST crm/v3/objects/contacts/batch/read 요청을 보내요. 배치 읽기 엔드포인트에서 이메일이나 커스텀 고유 식별자 속성으로 조회하려면 반드시 idProperty를 사용해야 해요. 기본적으로 요청의 id 값은 Record ID를 가리키므로 Record ID로 조회할 때는 idProperty가 필요 없지만, 이메일이나 커스텀 고유 ID 속성으로 조회할 때는 항상 필요해요.

배치 엔드포인트는 연결(association)을 조회할 수 없어요. 특정 배치의 연락처 연결을 보려면 먼저 연락처의 id 값을 가져온 다음, 배치 읽기 associations API 엔드포인트에 GET 요청으로 포함해야 해요.

예를 들어 Record ID 값으로 연락처 배치를 조회하려면 요청은 다음과 같아요 (현재 값만, 또는 현재 값과 이력 값을 조회).

{
  "properties": ["email", "lifecyclestage", "jobtitle"],
  "inputs": [
    { "id": "1234567" },
    { "id": "987456" }
  ]
}

{
  "propertiesWithHistory": ["lifecyclestage", "hs_lead_status"],
  "inputs": [
    { "id": "1234567" },
    { "id": "987456" }
  ]
}

이메일 주소나 커스텀 고유 식별자 속성 값(예: 회사에서 고유한 고객 ID 번호)으로 연락처를 조회하려면 요청은 다음과 같아요.

{
  "properties": ["email", "lifecyclestage", "jobtitle"],
  "idProperty": "email",
  "inputs": [
    { "id": "[email protected]" },
    { "id": "[email protected]" }
  ]
}

{
  "properties": ["email", "lifecyclestage", "jobtitle"],
  "idProperty": "internalcustid",
  "inputs": [
    { "id": "1234567" },
    { "id": "987456" }
  ]
}

연락처 업데이트 (Update contacts)

연락처는 개별 또는 일괄로 업데이트할 수 있어요. lifecyclestage 속성을 업데이트할 때는 단계 순서상 앞으로만 값을 설정할 수 있어요. 라이프사이클 단계를 뒤로 설정하려면 먼저 레코드의 기존 라이프사이클 단계 값을 비워야 해요. 값은 수동으로 비우거나, 워크플로나 연락처 데이터를 동기화하는 통합 기능을 통해 자동으로 비워질 수 있어요.

개별 연락처 업데이트 (Update an individual contact)

개별 연락처를 업데이트할 때는 Record ID(id) 또는 이메일 주소(email)를 사용할 수 있어요.

Record ID로 업데이트하려면 PATCH /crm/v3/objects/contacts/{contactId} 요청을 보내고 업데이트할 데이터를 포함해요.
이메일로 업데이트하려면 PATCH /crm/v3/objects/contacts/{email}?idProperty=email 요청을 보내고 업데이트할 데이터를 포함해요.

예시:

{
  "properties": {
    "favorite_food": "burger",
    "jobtitle": "Manager",
    "lifecyclestage": "customer"
  }
}

연락처 일괄 업데이트 (Update a batch of contacts)

연락처를 일괄 업데이트할 때는 반드시 Record ID 값(id)을 사용해야 해요. 여러 연락처를 업데이트하려면 POST /crm/v3/objects/contacts/batch/update 요청을 보내요. 요청 본문에 각 연락처의 Record ID를 id로 포함하고 업데이트할 속성을 포함해요.

예시:

{
  "inputs": [
    {
      "id": "123456789",
      "properties": { "favorite_food": "burger" }
    },
    {
      "id": "56789123",
      "properties": { "favorite_food": "Donut" }
    }
  ]
}

연락처 Upsert (Upsert contacts)

upsert 엔드포인트로 연락처를 배치 생성·업데이트를 동시에 할 수 있어요. 이 엔드포인트에서는 이메일이나 커스텀 고유 식별자 속성을 사용할 수 있어요. 요청 후 연락처가 이미 존재하면 업데이트되고, 존재하지 않으면 생성돼요.

연락처를 upsert하려면 POST /crm/v3/objects/contacts/batch/upsert 요청을 보내요. 요청 본문에 idProperty 매개변수를 포함해서 이메일을 쓰는지 커스텀 고유 식별자 속성을 쓰는지 지정해요. 해당 속성의 값을 id로 포함하고 설정하거나 업데이트할 다른 속성들을 추가해요.

연락처에 email을 idProperty로 사용할 때는 부분 upsert(partial upsert)를 지원하지 않아요. 부분 upsert를 하려면 커스텀 고유 식별자 속성을 idProperty로 사용해야 해요.

예를 들어 요청은 다음과 같이 생겼어요.

{
  "inputs": [
    {
      "properties": { "phone": "+188****7768" },
      "id": "[email protected]",
      "idProperty": "email"
    },
    {
      "properties": { "phone": "+188****8888" },
      "id": "[email protected]",
      "idProperty": "email"
    }
  ]
}

연관 관리 (Associations)

기존 연락처를 레코드나 활동에 연결 (Associate existing contacts with records or activities)

연락처를 다른 CRM 레코드나 활동에 연결하려면 PUT /crm/v3/objects/contacts/{contactId}/associations/{toObjectType}/{toObjectId}/{associationTypeId} 요청을 보내요. associationTypeId 값을 가져오려면 이 기본 값 목록을 참조하거나, GET /crm/v4/associations/{fromObjectType}/{toObjectType}/labels 요청을 보내면 돼요.

연관 제거 (Remove an association)

연락처와 레코드/활동 사이의 연결을 제거하려면 다음 URL에 DELETE 요청을 보내요.

/crm/v3/objects/contacts/{contactID}/associations/{toObjectType}/{toObjectId}/{associationTypeId}

연락처 레코드에 활동 고정 (Pin an activity on a contact record)

요청에 hs_pinned_engagement_id 필드를 포함하면 연락처 레코드에 활동을 고정(pin)할 수 있어요. 이 필드에 고정할 활동의 id를 넣는데, engagements API로 가져올 수 있어요. 레코드당 하나의 활동만 고정할 수 있고, 고정하기 전에 해당 활동이 이미 연락처와 연결돼 있어야 해요.

연락처의 고정 활동을 설정하거나 업데이트하려면 요청은 다음과 같아요.

{
  "properties": {
    "hs_pinned_engagement_id": 123456789
  }
}

연락처를 생성하면서 기존 활동과 연결하고 같은 요청에서 활동을 고정할 수도 있어요.

{
  "properties": {
    "email": "[email protected]",
    "firstname": "Jane",
    "lastname": "Doe",
    "phone": "+188****7768",
    "hs_pinned_engagement_id": 123456789
  },
  "associations": [
    {
      "to": { "id": 123456789 },
      "types": [
        { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 201 }
      ]
    }
  ]
}

연락처 삭제 (Delete contacts)

연락처는 개별 또는 일괄로 삭제할 수 있고, 삭제하면 HubSpot의 휴지통(recycling bin)으로 들어가요. 나중에 HubSpot 내에서 복원할 수 있어요.

ID로 개별 연락처를 삭제하려면 DELETE /crm/v3/objects/contacts/{contactId} 요청을 보내요.
연락처 일괄 삭제에 대해 더 알아보려면 참조 문서를 확인해요.

추가 이메일 (Additional emails)

추가 이메일 주소는 연락처가 이메일을 두 개 이상 가질 때 사용돼요. HubSpot 연락처 레코드에서 수동으로 추가하거나, 연락처 병합(merge) 후 자동으로 추가될 수 있어요. 추가 이메일은 여전히 연락처의 고유 식별자이므로, 여러 연락처가 같은 추가 이메일 주소를 가질 수 없어요.

추가 이메일을 보려면 전체 또는 개별 연락처를 조회할 때 properties 매개변수에 email과 hs_additional_emails 속성을 포함해요. 연락처의 기본 이메일 주소는 email 필드에 표시되고, 추가 이메일은 hs_additional_emails 필드에 표시돼요.

제한 (Limits)

배치 작업은 한 번에 100개 레코드로 제한돼요. 예를 들어 한 요청에서 100개가 넘는 연락처를 일괄 업데이트할 수 없어요. 연락처와 폼 제출에 대한 제한도 있어요.

더 알아보기 (Learn more)

공식 문서