Ignorar e ir ao conteúdo principal

Use propriedades para armazenar informações em registros do CRM. A HubSpot fornece um conjunto de propriedades padrão para cada objeto do CRM e você também pode criar e gerenciar suas próprias propriedades personalizadas no HubSpot ou usando a API de propriedades.

Ao criar propriedades, é importante considerar como organizar seus dados. Em muitos casos, a estratégia correta é a criação de propriedades personalizadas para os objetos padrão da HubSpot. No entanto, em alguns casos, talvez você precise criar um objeto personalizado separado com seu próprio conjunto de propriedades.

Os objetos de CRM são definidos por um tipo principal e um conjunto de propriedades. Cada tipo tem um conjunto exclusivo de propriedades padrão, representado por um mapeamento de pares nome-valor.

Saiba mais sobre propriedades padrão para diferentes objetos:

Os grupos de propriedades são usados para agrupar propriedades relacionadas. Todas as propriedades agrupadas aparecerão lado a lado nos registros do HubSpot. Se sua integração criar quaisquer propriedades de objeto personalizadas, um grupo de propriedades personalizadas facilitará a identificação desses dados.

Ao criar ou atualizar propriedades, os valores type e fieldType são obrigatórios. O valor type determina o tipo da propriedade, ou seja, uma string ou um número. A propriedade fieldType determina como a propriedade aparecerá no HubSpot ou em um formulário, ou seja, como um campo de texto simples, um menu suspenso ou um seletor de data.

Na tabela abaixo, saiba mais sobre o type de propriedade disponível e os valores fieldType correspondentes.

typeDescriçãoValores fieldType válidos
boolUm campo que contém opções binárias (por exemplo, Yes ou No, True ou False).booleancheckbox, calculation_equation
enumerationUma string que representa um conjunto de opções separadas por ponto e vírgula.booleancheckbox, checkbox, radio, select, calculation_equation
dateUm valor que representa um dia, mês e ano específicos. Os valores devem ser representados em hora UTC e podem ser formatados como strings de ISO 8601 ou registros de data e hora EPOCH em milissegundos (ou seja, meia-noite UTC).date
dateTimeUm valor que representa um dia, mês, ano e horário do dia específicos. Os valores devem ser representados em hora UTC e podem ser formatados como strings de ISO 8601 ou registros de data e hora UNIX em milissegundos.date
stringUma string de texto simples, com no máximo 65.536 caracteres.file, text, textarea, calculation_equation, html, phonenumber
numberValor numérico que contém dígitos numéricos e, na maioria das vezes, um número decimal.number, calculation_equation
object_coordinatesUm valor de texto usado para referenciar outros objetos do HubSpot, usado apenas para Propriedades internas. As propriedades deste tipo não podem ser criadas ou editadas e não são visíveis no HubSpot.text
jsonUm valor de texto armazenado como JSON formatado, utilizado apenas para propriedades internas. As propriedades deste tipo não podem ser criadas ou editadas e não são visíveis no HubSpot.text

Os valores válidos para fieldType incluem:

Tipo de campoDescrição
booleancheckboxUma entrada que permite que os usuários selecionem Sim ou Não. Quando usada em um formulário, essa entrada aparecerá como uma única caixa de seleção. Saiba como adicionar um valor a propriedades de caixa de seleção única.
calculation_equationUma equação personalizada que pode calcular valores com base em outros valores de propriedades e/ou associações. Saiba como definir propriedades de cálculo.
checkboxUma lista de caixas de seleção que permite que um usuário selecione várias opções em um conjunto de opções válidas para a propriedade. Saiba como formatar valores ao atualizar propriedades de várias caixas de seleção.
dateUm valor de data, que é exibido como um seletor de data.
filePermite que um arquivo seja carregado em um registro ou por meio de um formulário. Armazena um ID de arquivo.
htmlUma string, renderizada como html corrigido, que permite o uso de um editor de rich text para a propriedade
numberUma string de numerais ou números escritos em formato decimal ou em notação científica.
phonenumberUma string de texto simples, exibida como um número de telefone formatado.
radioUma entrada que permite que os usuários selecionem um conjunto de opções válidas para a propriedade. Quando usada em um formulário, essa entrada é exibida como um conjunto de botões de opção.
selectUma entrada suspensa que permite que os usuários selecionem um conjunto de opções válidas para a propriedade.
textUma string de texto simples, que é exibida em uma entrada de texto com uma única linha.
textareaUma string de texto simples, que é exibida como uma entrada de texto com várias linhas.

Para criar uma propriedade, faça uma solicitação POST para /crm/v3/properties/{objectType}. No corpo da solicitação, inclua os seguintes campos obrigatórios:

  • groupName: o grupo de propriedades em que a propriedade estará inserida.
  • name: o nome interno da propriedade (por exemplo, favorite_food).
  • label: o nome da propriedade tal como aparece no HubSpot (por exemplo, Favorite Food).
  • type: o tipo de propriedade.
  • fieldType: o tipo de campo da propriedade.

Por exemplo, para criar uma propriedade de contato chamada Favorite Food, a solicitação seria semelhante à seguinte:

Quando um registro é criado no HubSpot, um ID de registro exclusivo (hs_object_id) é gerado automaticamente e deve ser tratado como uma string. Esses IDs são exclusivos apenas dentro do tipo de objeto; pode haver um contato e uma empresa com o mesmo ID. Para contatos e empresas, existem identificadores exclusivos adicionais, incluindo o endereço de e-mail (email) de um contato e o nome de domínio (domain) de uma empresa.

Em alguns casos, você deseja criar sua própria propriedade de identificador exclusivo para que não seja possível inserir o mesmo valor para vários registros. Você pode ter até dez propriedades de ID exclusivas por objeto. Para criar uma propriedade que requer valores exclusivos via API:

  • Faça uma solicitação POST para /crm/v3/properties/{objectType}.
  • No corpo da solicitação, para o campo hasUniqueValue, defina o valor como true.

Depois de criar sua propriedade de ID exclusivo, você poderá usá-la em uma chamada de API para recuperar registros específicos. O URL de solicitação pode ser semelhante ao seguinte: GET https://api.hubapi.com/crm/v3/objects/deals/abc?idProperty=system_a_unique. Essa chamada retornará o negócio com o valor abc no campo system_a_unique.

Você pode usar esse valor de propriedade de identificador exclusivo para identificar e atualizar registros específicos da mesma forma que usaria hs_object_id, email (contatos) ou domain (empresas).

As propriedades de cálculo definem um valor de propriedade com base em outras propriedades dentro do mesmo registro de objeto. Elas são definidas usando uma fórmula, que pode incluir operações como mín., máx., contagem, soma ou média. Você pode usar a API de propriedades para ler ou criar propriedades de cálculo na sua conta da HubSpot, usando um tipo de campo calculation_equation e um tipo number, bool, string ou enumeration.

Você pode definir a fórmula de cálculo da propriedade com o campo calculationFormula.

Com a calculationFormula, você pode escrever sua fórmula com operadores aritméticos, operadores de comparação, operadores lógicos, instruções condicionais e outras funções.

  • Literal de string: strings constantes podem ser representadas com aspas simples ('constant') ou aspas duplas ("constant").
  • Literal de número: os números constantes podem ser quaisquer números reais e podem incluir notação de pontos. 1005 e 1.5589 são números de constante válidos.
  • Literal de booleano: booleanos de constantes podem ser true ou false.
  • Variáveis de propriedade de string: para uma string de identificador ser interpretada como uma propriedade de string, ela deve ser vinculada à função string. Por exemplo, string(var1) será interpretada como o valor var1 da propriedade de string.
  • Variáveis de propriedade numérica: todos os identificadores serão interpretados como variáveis de propriedade numérica. Por exemplo, var1 será interpretado como o valor var1 da propriedade numérica.
  • Variáveis de propriedade booleana: para um identificador ser interpretado como uma propriedade bool, ele deve ser vinculado à função bool. Por exemplo, o identificador bool(var1) será interpretado como o valor var1 da propriedade booleana.

Os operadores podem ser usados com valores literais e de propriedade. Para operadores aritméticos, você pode usar a notação de prefixo para multiplicar; e parênteses podem ser usados para especificar a ordem das operações.

OperadorDescriçãoExemplos
+Some números ou strings.property1 + 100
-Subtraia números.property1 + 100 - property2
*Multiplique números.10property1 = 10 * property1
/Divida números.property1 * (100 - property2/(50 - property3))
<Verifica se um valor é menor que outro. Compatível com propriedades numéricas ou constantes.a < 100
>Verifica se um valor é maior que outro. Compatível com propriedades numéricas ou constantes.a > 50
<=Verifica se um valor é menor ou igual a outro. Compatível com propriedades numéricas ou constantes.a <= b
>=Verifica se um valor é maior ou igual a outro. Compatível com propriedades numéricas ou constantes.b>= c
=Verifica se um valor é igual a outro. Compatível com números e strings.(a + b - 100c * 150.652) = 150-230b
equalsVerifica se um valor é igual a outro. Compatível com números e strings.a + b - 100.2c * 150 equals 150 - 230
!=Verifica se um valor não é igual a outro. Compatível com números e strings.string(property1) != 'test_string'
orVerifica se dois valores são verdadeiros.a > b or b <= c
andVerifica se os valores são verdadeiros.bool(a) and bool(c)
notVerifica se nenhum dos valores é verdadeiro.not (bool(a) and bool(c))

As funções a seguir são compatíveis:

FunçãoDescriçãoExemplos
maxTerá entre 2 e 100 números de entrada e retornará o número máximo de todas as entradas.max(a, b, c, 100) ou max(a, b)
minTerá entre 2 e 100 números de entrada e retornará o número mínimo de todas as entradas.min(a, b, c, 100) ou min(a, b)
is_presentAvalia se uma expressão pode ser avaliada.is_present(bool(a))= true se a propriedade for booleana, mas is_present(bool(a)) = false se a propriedade estiver vazia ou não for booleana.
containsTem duas strings como entradas e retornará true se a primeira entrada contiver a segunda.contains('hello', 'ello') = true enquanto contains('ello', 'hello') = false.
concatenateIngressa em uma lista de strings. A lista de entradas pode ir de 2 a 100.concatenate('a', 'b', string(a), string(b))

Há também duas funções de análise:

  • number_to_string: tenta converter a expressão do número de entrada em uma string.
  • string_to_number: tenta converter a expressão da string de entrada em um número.

Por exemplo, "Number of cars: " + num_cars não é uma propriedade válida, pois você não pode adicionar uma string com um número. A string válida seria "Number of cars: " + number_to_string(num_cars).

Você também pode escrever sua fórmula com declarações condicionais, usando if, elseif, endif e else.

Por exemplo, uma declaração condicional pode ser semelhante a seguinte: if boolean_expression then statement [elseif expression then statement]* [else statement | endif], onde os colchetes [a] representam que a é opcional, a|b representa que a ou b funcionará e * significa 0 ou mais. endif pode ser usado para terminar uma declaração condicional prematuramente, garantindo que o analisador possa identificar de qual if o próximo elseif pertence.

Veja os seguintes exemplos que podem ser usados para ajudar a definir suas próprias fórmulas de cálculo:

Um exemplo mais avançado com condicionais:

É possível obter informações sobre propriedades individuais ou todas as propriedades de um objeto.

  • Para recuperar uma propriedade individual, faça uma solicitação GET para crm/v3/properties/{object}/{propertyName}. Por exemplo, para obter a propriedade Favorite Food, o URL da solicitação seria https://
    api.hubspot.com/crm/v3/properties/contacts/favorite_food.
  • Para obter todas as propriedades de um objeto, faça uma solicitação GET para /crm/v3/properties/{objectType}.

Para atualizar um valor de propriedade para um registro, faça uma solicitação PATCH para crm/v3/objects/{objectType}/{recordId}. No corpo da solicitação, inclua as propriedades e os respectivos valores em uma matriz. Saiba mais sobre como atualizar registros através das APIs de objeto.

Os valores de hora são representados no formato ISO 8601 nas respostas, mas as APIs da HubSpot aceitarão um dos dois formatos para valores de data e hora:

  • Strings com formatação ISO 8601: dependendo do tipo de dados, elas terão um destes dois formatos:
    • Para valores que representam uma data específica, o formato de data completo será usado: YYYY-MM-DD (por exemplo, 2020-02-29)
    • Para valores que representam uma data e hora específicas, será usado o formato de data completa mais horas, minutos, segundos e uma fração decimal de segundo: AAAA-MM-DDThh:mm:ss.sTZD (por exemplo 2020-02-29T03:30:17.000Z). Todos os horários serão representados em UTC, então os valores sempre usarão o designador de UTC "Z."
  • Data/hora em formato UNIX em milissegundos: valores de data/hora em milissegundos, que são representados em UTC. Por exemplo, o valor de data/hora 1427997766000 é traduzido como 2 de abril de 2015, 18:02:46UTC ou 2 Abr 2015, 2:02:46 PMEDT (Horário de Verão do Leste).

Existem dois tipos de propriedades para armazenar datas (date e datetime ) que também afetam como você formata valores:

  • date propriedades armazenam a data, não o tempo. As propriedades date exibem a data em que foram definidas, independentemente da configuração de fuso horário da conta ou do usuário. Para valores de propriedade date, recomenda-se usar o formato de data completo ISO 8601. Se você usar o formato de data/hora UNIX, deverá usar uma data/hora em milissegundos de Era (ou seja, o valor deve ser definido como meia-noite UTC para a data). Por exemplo, para representar 1° de maio de 2015 em qualquer formato:
    • IOS 8601: 2015-05-01
    • UNIX millisecond timestamp: 1430438400000 As propriedades - datetime armazenam a data e a hora. Qualquer formato de data/hora será aceito. No HubSpot, as propriedades datetime são exibidas com base no fuso horário do usuário que vê o registro; portanto, o valor será convertido para o fuso horário local do usuário.

Ao atualizar valores para propriedades de tipo de caixa de seleção de um registro, formate os valores da seguinte maneira:

  • Propriedade de caixa de seleção Booleano: para ser exibido como Sim ou aparecer como selecionado no HubSpot, seu valor deve ser true. Para ser exibido como Não ou aparecer como não marcado no HubSpot, seu valor deve ser false.
  • Propriedade de várias caixas de seleção: para adicionar ou anexar valores a uma propriedade de várias caixas de seleção, adicione um ponto e vírgula antes do primeiro valor e inclua um ponto e vírgula entre cada valor. Se a propriedade tiver um valor existente, o ponto e vírgula inicial adicionará os valores em vez de sobrescrevê-los. Por exemplo, um contato tem o valor existente DECISION_MAKER para a propriedade hs_buying_role. Para adicionar valores sem substituir o valor existente, sua solicitação seria assim:

Ao atribuir usuários a registros do CRM via API, o valor deve ser o id de proprietário do usuário, que você pode encontrar nas configurações da propriedade ou por meio da API de proprietários. Por exemplo, para atribuir um usuário como proprietário de um contato, envie uma solicitação PATCH para crm/v3/objects/contacts/{contactId}, com o corpo { "properties":{ "hubspot_owner_id": "41629779"}}.

Você pode apagar o valor da propriedade de um objeto por meio da API configurando o valor da propriedade como uma string vazia.

Por exemplo, para limpar o firstname de um objeto de contato, envie uma solicitação PATCH para https://api.hubapi.com/crm/v3/objects/contacts/{contactId}, com o corpo { "properties": { "firstname": ""}}.