No HubSpot, as empresas armazenam informações sobre as organizações que interagem com os seus negócios. Os pontos de extremidade de empresas permitem controlar a criação e o gerenciamento de registros de empresas, bem como sincronizar os dados de empresas entre o HubSpot e outros sistemas.
Saiba mais sobre objetos, registros, propriedades e APIs de associações no guia Noções básicas do CRM. Para obter informações mais gerais sobre objetos e registros no HubSpot, saiba como gerenciar seu banco de dados do CRM.
Para criar novas empresas, faça uma solicitação POST
para /crm/v3/objects/companies
.
Na solicitação, inclua os dados da empresa em um objeto de propriedades. Você também pode adicionar um objeto de associações para associar sua nova empresa a registros (por exemplo, contatos, negócios) ou atividades (por exemplo, reuniões, observações) existentes.
Os detalhes da empresa são armazenados nas propriedades da empresa. Existem propriedades de empresa padrão do HubSpot, mas você também pode criar propriedades personalizadas.
Ao criar uma nova empresa, você deve incluir pelo menos uma das seguintes propriedades na solicitação: name
ou domain
. É recomendável incluir sempre o domain
, pois os nomes de domínio são o principal identificador exclusivo para evitar empresas duplicadas no HubSpot. Se uma empresa tiver vários domínios, você pode adicioná-los por meio da API usando o campo hs_additional_domains
, separando cada domínio com ponto e vírgula. Por exemplo, "hs_additional_domains" : "domain.com; domain2.com; domain3.com"
.
Para exibir todas as propriedades disponíveis, você pode recuperar uma lista das propriedades da empresa da sua conta, fazendo uma solicitação GET
para /crm/v3/properties/companies
. Saiba mais sobre a API de propriedades.
Observação: se você incluiu lifecyclestage
em sua solicitação, os valores devem se referir ao nome interno da fase do ciclo de vida. Os nomes internos das fases padrão são valores de texto e não mudam, mesmo se você editar o rótulo da fase (por exemplo, subscriber
ou marketingqualifiedlead
). Os nomes internos das fases personalizadas são valores numéricos. Você pode encontrar o ID interno de uma fase nas configurações de fase do ciclo de vida ou recuperando a propriedade de fase do ciclo de vida por meio da API.
Por exemplo, para criar uma nova empresa, a solicitação pode ser semelhante à seguinte:
///Example request body
{
"properties": {
"name": "HubSpot",
"domain": "hubspot.com",
"city": "Cambridge",
"industry": "Technology",
"phone": "555-555-555",
"state": "Massachusetts",
"lifecyclestage": "51439524"
}
}
Ao criar uma nova empresa, você também pode associá-la a registros ou atividades existentes em um objeto de associações. Por exemplo, para associar uma nova empresa a um contato e um e-mail existentes, a solicitação seria parecida com a seguinte:
xxxxxxxxxx
///Example request body
{
"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
}
]
}
]
}
No objeto de associações, você deve incluir o seguinte:
Descrição | Parâmetro |
---|---|
to | O registro ou a atividade que você deseja associar à empresa especificado por seu valor de id exclusivo. |
types | O tipo de associação entre a empresa e o registro/atividade. Inclua associationCategory e associationTypeId . Os IDs de tipo de associação padrão são listados aqui, ou você pode recuperar o valor de tipos de associação personalizados (ou seja, rótulos) por meio da API de associações. |
Você pode recuperar empresas individualmente ou em lotes.
- Para recuperar uma empresa individual, faça uma solicitação
GET
para/crm/v3/objects/companies/{companyId}
. - Para solicitar uma lista de todas as empresas, faça uma solicitação
GET
para/crm/v3/objects/companies
.
Para ambos os pontos de extremidade, você pode incluir os seguintes parâmetros de consulta no URL da solicitação:
Descrição | Parâmetro |
---|---|
properties | Uma lista separada por vírgulas das propriedades a serem retornadas em resposta. Se a empresa solicitada não tiver um valor para uma propriedade, ela não será exibida na resposta. |
propertiesWithHistory | Uma lista separada por vírgulas das propriedades atuais e do histórico a serem retornadas em resposta. Se a empresa solicitada não tiver um valor para uma propriedade, ela não será exibida na resposta. |
associations | Uma lista separada por vírgulas de objetos para recuperar IDs associados. Todas as associações especificadas que não existem não serão retornadas na resposta. Saiba mais sobre a API de associações. |
- Para recuperar um lote de empresas específicas por ID de registro ou uma propriedade de identificador exclusivo personalizada, faça uma solicitação
POST
paracrm/v3/objects/companies/batch/read
. O ponto de extremidade em lote não pode recuperar associações. Saiba como fazer associações de leitura em lote com a API de associações.
Para o ponto de extremidade de leitura em lote, você também pode usar o parâmetro idProperty
opcional para recuperar empresas por uma propriedade de identificador exclusivo personalizada. Por padrão, os valores de id
na solicitação referem-se ao ID do registro (hs_object_id
); portanto, o parâmetro idProperty
não é necessário ao recuperar pelo ID do registro. Para usar uma propriedade de valor exclusivo personalizada para recuperar empresas, você deve incluir o parâmetro idProperty
.
Por exemplo, para recuperar um lote de empresas, sua solicitação pode ser parecida com o seguinte:
xxxxxxxxxx
///Example request body with record ID
{
"properties": ["name", "domain"],
"inputs": [
{
"id": "56789"
},
{
"id": "23456"
}
]
}
xxxxxxxxxx
///Example request body with a unique value property
{
"properties": ["name", "domain"],
"idProperty": "uniquepropertyexample",
"inputs": [
{
"id": "abc"
},
{
"id": "def"
}
]
}
Para recuperar empresas com valores atuais e do histórico de uma propriedade, sua solicitação pode ser parecida com o seguinte:
xxxxxxxxxx
///Example request body with record ID (current and historical values)
{
"propertiesWithHistory": ["name"],
"inputs": [
{
"id": "56789"
},
{
"id": "23456"
}
]
}
Você pode atualizar empresas individualmente ou em massa. Para empresas existentes, o ID de registro da empresa é um valor exclusivo que você pode usar para atualizar a empresa por meio da API.
Para atualizar uma empresa individual por seu ID da empresa, faça uma solicitação PATCH
para /crm/v3/objects/companies/{companyId}
e inclua os dados que deseja atualizar.
Observe: se atualizar a propriedade lifecyclestage
, você só pode definir o valor avançar na ordem do estágio. Para definir o estágio do ciclo de vida para trás, primeiro você precisa limpar o valor do estágio do ciclo de vida existente do registro. O valor pode ser apagado manualmente ou automaticamente por meio de um fluxo de trabalho ou de uma integração que sincroniza os dados do contato.
Para associar uma empresa a outros registros do CRM ou a uma atividade, faça uma solicitação PUT
para /crm/v3/objects/companies/{companyId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}
.
Para recuperar o valor associationTypeId
, consulte esta lista de valores padrão ou envie uma solicitação GET
para /crm/v4/associations/{fromObjectType}/{toObjectType}/labels
.
Saiba mais sobre como associar registros com a API de associações.
Para remover uma associação entre uma empresa e um registro ou uma atividade, faça uma solicitação DELETE
para o seguinte URL: /crm/v3/objects/companies/{companyId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}
Você pode fixar uma atividade em um registro de empresa por meio da API, incluindo o campo hs_pinned_engagement_id
na sua solicitação. No campo, inclua o id
da atividade a ser fixada, que pode ser recuperado por meio das APIs de engajamentos. Você pode fixar uma atividade por registro. No entanto, a atividade já deve estar associada à empresa antes da fixação.
Para definir ou atualizar a atividade fixada de uma empresa, sua solicitação pode ser parecida com o seguinte:
xxxxxxxxxx
///Example request body PATCH /crm/v3/objects/companies/{companyId}
{
"properties": {
"hs_pinned_engagement_id": 123456789
}
}
Você também pode criar uma empresa, associá-la a uma atividade existente e fixar a atividade na mesma solicitação. Por exemplo:
xxxxxxxxxx
///Example request body POST /crm/v3/objects/companies
{
"properties": {
"domain": "example.com",
"name": "Example Company",
"hs_pinned_engagement_id": 123456789
},
"associations": [
{
"to": {
"id": 123456789
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 189
}
]
}
]
}
Você pode excluir empresas individualmente ou em massa, o que adicionará a empresa à lixeira no HubSpot. Posteriormente, você pode restaurar a empresa no HubSpot.
Para excluir uma empresa individual pelo seu ID, faça uma solicitaçãoDELETE
para /crm/v3/objects/companies/{companyId}
.
Saiba mais sobre empresas de exclusão em lote na documentação de referência.