HubSpot API 회사

HubSpot API 회사

HubSpot CRM의 회사(companies) 객체는 비즈니스 · 조직에 대한 정보를 담아요. 회사 엔드포인트를 사용하면 회사 레코드를 만들고 관리하고, HubSpot과 다른 시스템 사이에서 회사 데이터를 동기화할 수 있어요. 이 문서에서는 회사 객체의 생성(Create)·조회(Retrieve)·수정(Update)·삭제(Delete)와 속성(properties)·연관(associations) 사용법을 다뤄요.

출처: 문서

본문

HubSpot에서 회사는 비즈니스와 상호작용하는 조직에 대한 정보를 저장해요. 회사 엔드포인트로 회사 레코드를 만들고 관리하며, HubSpot과 다른 시스템 사이의 회사 데이터 동기화도 처리해요.

객체, 레코드, 속성, 연관 API에 대한 자세한 내용은 Understanding the CRM 가이드를 참고해요. HubSpot의 객체와 레코드 일반에 대한 정보는 CRM 데이터베이스 관리 문서를 참고해요.

회사 생성 (Create companies)

새 회사를 만들려면 /crm/v3/objects/companies에 POST 요청을 보내요. 요청에는 회사 데이터를 properties 객체에 담고, 새 회사와 기존 레코드(예: 연락처, 거래), 또는 활동(예: 회의, 메모)을 연결하려면 associations 객체도 추가할 수 있어요.

속성 (Properties)

회사 세부 정보는 회사 속성에 저장돼요. 기본 HubSpot 회사 속성이 있지만, 커스텀 속성도 만들 수 있어요.

새 회사를 만들 때는 요청에 name 또는 domain 속성을 최소 하나는 포함해야 해요. 도메인 이름이 HubSpot에서 중복 회사를 방지하는 기본 고유 식별자이므로 항상 domain을 포함하는 것이 권장돼요. 회사가 여러 도메인을 가지면 hs_additional_domains 필드에 세미콜론으로 구분해 추가할 수 있어요. 예: "hs_additional_domains" : "domain.com; domain2.com; domain3.com".

사용 가능한 모든 속성을 보려면 /crm/v3/properties/companies에 GET 요청을 보내 계정의 회사 속성 목록을 가져올 수 있어요. properties API에 대해 자세히 알아보려면 해당 문서를 참고해요.

참고 사항:

  • 요청에 lifecyclestage를 포함한다면, 값은 라이프사이클 단계의 내부 이름(internal name)을 가리켜야 해요. 기본 단계의 내부 이름은 텍스트 값이며, 단계의 레이블을 편집해도 바뀌지 않아요(예: subscriber, marketingqualifiedlead). 커스텀 단계의 내부 이름은 숫자 값이에요. 단계의 내부 ID는 라이프사이클 단계 설정에서 찾거나, API로 라이프사이클 단계 속성을 조회해서 찾을 수 있어요.

예를 들어 새 회사를 만들 때 요청은 다음과 비슷할 수 있어요:

{
  "properties": {
    "name": "HubSpot",
    "domain": "hubspot.com",
    "city": "Cambridge",
    "industry": "Technology",
    "phone": "555-555-555",
    "state": "Massachusetts",
    "lifecyclestage": "51439524"
  }
}

연관 (Associations)

새 회사를 만들 때, 기존 레코드나 활동과의 연관을 associations 객체에 담을 수도 있어요. 예를 들어 새 회사를 기존 연락처와 이메일에 연결하려면 요청은 다음과 같아요:

{
  "properties": {
    "name": "HubSpot",
    "domain": "hubspot.com",
    "city": "Cambridge",
    "industry": "Technology",
    "phone": "555-555-555",
    "state": "Massachusetts",
    "lifecyclestage": "51439524"
  },
  "associations": [
    {
      "to": {
        "id": 101
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 280
        }
      ]
    },
    {
      "to": {
        "id": 556677
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 185
        }
      ]
    }
  ]
}

associations 객체에는 다음 내용을 포함해요:

파라미터 설명
to 회사와 연결할 레코드나 활동을 고유 id 값으로 지정해요.
types 회사와 레코드/활동 사이의 연관 유형이에요. associationCategory와 associationTypeId를 포함해요. 기본 연관 유형 ID는 여기 목록에 있고, 커스텀 연관 유형(레이블)의 값은 associations API로 조회할 수 있어요.

회사 조회 (Retrieve companies)

회사를 개별 또는 일괄로 조회할 수 있어요.

  • 개별 회사를 조회하려면 /crm/v3/objects/companies/{companyId}에 GET 요청을 보내요.
  • 모든 회사 목록을 요청하려면 /crm/v3/objects/companies에 GET 요청을 보내요.

이 엔드포인트에서는 요청 URL에 다음 쿼리 파라미터를 포함할 수 있어요:

파라미터 설명
properties 응답에 포함할 속성의 쉼표 구분 목록이에요. 요청한 속성이 정의되지 않았으면 응답에서 제외되고, 정의됐지만 회사에 값이 없으면 null로 반환돼요.
propertiesWithHistory 응답에 포함할 현재 및 이력 속성의 쉼표 구분 목록이에요. 요청한 속성이 정의되지 않았으면 응답에서 제외되고, 정의됐지만 회사에 값이 없으면 null로 반환돼요.
associations 연결된 ID를 조회할 객체의 쉼표 구분 목록이에요. 지정한 연관이 존재하지 않으면 응답에서 제외돼요. associations API에 대해 자세히 알아보려면 해당 문서를 참고해요.

레코드 ID 또는 커스텀 고유 식별자 속성으로 특정 회사를 일괄 조회하려면 crm/v3/objects/companies/batch/read에 POST 요청을 보내요. 일괄 엔드포인트는 연관을 조회할 수 없어요. 연관 일괄 조회 방법은 associations API 문서를 참고해요.

일괄 조회 엔드포인트에서는 선택적 idProperty 파라미터로 커스텀 고유 식별자 속성으로 회사를 조회할 수도 있어요. 기본적으로 요청의 id 값은 레코드 ID(hs_object_id)를 가리키므로, 레코드 ID로 조회할 때는 idProperty 파라미터가 필요 없어요. 커스텀 고유 값 속성으로 조회하려면 idProperty 파라미터를 반드시 포함해야 해요.

예를 들어 회사를 일괄 조회하려면 요청은 다음 중 하나와 같을 수 있어요:

{
  "properties": ["name", "domain"],
  "inputs": [
    {
      "id": "56789"
    },
    {
      "id": "23456"
    }
  ]
}

속성의 현재 값과 이력 값을 함께 조회하려면 요청은 다음과 같아요:

{
  "propertiesWithHistory": ["name"],
  "inputs": [
    {
      "id": "56789"
    },
    {
      "id": "23456"
    }
  ]
}

회사 수정 (Update companies)

회사를 개별 또는 일괄로 수정할 수 있어요. 기존 회사의 경우 회사의 레코드 ID가 유일한 값이라 API로 회사를 수정할 때 사용할 수 있어요.

개별 회사를 회사 ID로 수정하려면 /crm/v3/objects/companies/{companyId}에 PATCH 요청을 보내고, 수정할 데이터를 포함해요.

참고 사항:

  • lifecyclestage 속성을 수정할 때는 단계 순서에서 앞쪽 방향으로만 값을 설정할 수 있어요. 라이프사이클 단계를 뒤로 설정하려면 먼저 레코드의 기존 라이프사이클 단계 값을 비워야 해요. 이 값은 수동으로 지우거나, 워크플로우 또는 연락처 데이터를 동기화하는 통합에서 자동으로 지울 수 있어요.

기존 회사를 레코드·활동과 연결 (Associate existing companies with records and activities)

회사를 다른 CRM 레코드나 활동과 연결하려면 /crm/v3/objects/companies/{companyId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}에 PUT 요청을 보내요.

associationTypeId 값을 가져오려면 기본 값 목록을 참고하거나, /crm/v4/associations/{fromObjectType}/{toObjectType}/labels에 GET 요청을 보내요. 레코드 연결에 대해 자세히 알아보려면 associations API 문서를 참고해요.

연관 제거 (Remove an association)

회사와 레코드/활동 사이의 연관을 제거하려면 다음 URL에 DELETE 요청을 보내요: /crm/v3/objects/companies/{companyId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}.

회사 레코드에 활동 고정 (Pin an activity on a company record)

요청에 hs_pinned_engagement_id 필드를 포함하면 API로 회사 레코드에 활동을 고정할 수 있어요. 필드에는 고정할 활동의 id를 넣고, 이 값은 engagements API로 조회할 수 있어요. 레코드당 하나의 활동만 고정할 수 있으며, 고정하기 전에 활동이 이미 회사와 연결되어 있어야 해요.

회사의 고정 활동을 설정하거나 수정하는 요청은 다음과 같아요:

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

한 번의 요청으로 회사를 만들고, 기존 활동과 연결하고, 활동을 고정할 수도 있어요. 예:

{
  "properties": {
    "domain": "example.com",
    "name": "Example Company",
    "hs_pinned_engagement_id": 123456789
  },
  "associations": [
    {
      "to": {
        "id": 123456789
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 189
        }
      ]
    }
  ]
}

회사 삭제 (Delete companies)

회사를 개별 또는 일괄로 삭제할 수 있으며, 삭제하면 HubSpot의 휴지통(recycling bin)에 추가돼요. 이후 HubSpot 내에서 복원할 수 있어요.

개별 회사를 ID로 삭제하려면 /crm/v3/objects/companies/{companyId}에 DELETE 요청을 보내요. 회사 일괄 삭제에 대한 자세한 내용은 reference documentation을 참고해요.

더 알아보기 (Learn more)