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:
- Contatos
- Empresas
- Negócios
- Tickets
- Atividades (Chamadas, E-mails, Reuniões, Observações, Tarefas)
- Leads(Sales Hub Professional e Enterprise)
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.
type | Descrição | Valores fieldType válidos |
---|---|---|
bool | Um campo que contém opções binárias (por exemplo, Yes ou No , True ou False ). | booleancheckbox , calculation_equation |
enumeration | Uma string que representa um conjunto de opções separadas por ponto e vírgula. | booleancheckbox , checkbox , radio , select , calculation_equation |
date | Um 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 |
dateTime | Um 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 |
string | Uma string de texto simples, com no máximo 65.536 caracteres. | file , text , textarea , calculation_equation , html , phonenumber |
number | Valor numérico que contém dígitos numéricos e, na maioria das vezes, um número decimal. | number , calculation_equation |
object_coordinates | Um 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 |
json | Um 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 campo | Descrição |
---|---|
booleancheckbox | Uma 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_equation | Uma 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. |
checkbox | Uma 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. |
date | Um valor de data, que é exibido como um seletor de data. |
file | Permite que um arquivo seja carregado em um registro ou por meio de um formulário. Armazena um ID de arquivo. |
html | Uma string, renderizada como html corrigido, que permite o uso de um editor de rich text para a propriedade |
number | Uma string de numerais ou números escritos em formato decimal ou em notação científica. |
phonenumber | Uma string de texto simples, exibida como um número de telefone formatado. |
radio | Uma 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. |
select | Uma entrada suspensa que permite que os usuários selecionem um conjunto de opções válidas para a propriedade. |
text | Uma string de texto simples, que é exibida em uma entrada de texto com uma única linha. |
textarea | Uma 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:
/// Example request body POST crm/v3/properties/contacts
{
"groupName": "contactinformation",
"name": "favorite_food",
"label": "Favorite Food",
"type": "string",
"fieldType": "text"
}
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 comotrue
.
xxxxxxxxxx
/// Example request body
{
"groupName": "dealinformation",
"name": "system_a_unique",
"label": "Unique ID for System A",
"hasUniqueValue": true,
"type": "string",
"fieldType": "text"
}
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
.
Observação: as propriedades de cálculo criadas por meio da API não podem ser editadas no HubSpot. Elas somente podem ser editadas por meio da API de propriedades.
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
e1.5589
são números de constante válidos. - Literal de booleano: booleanos de constantes podem ser
true
oufalse
.
- 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 identificadorbool(var1)
será interpretado como o valor var1 da propriedade booleana.
Observação: o texto usado diferencia maiúsculas de minúsculas para todos os tipos, exceto para strings. Por exemplo, If A ThEn B
é exatamente o mesmo que if a then b
mas 'a'
não é o mesmo que 'A'
. Espaços, tabulações e novas linhas serão usados para tokenização, mas serão ignorados.
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.
Operador | Descrição | Exemplos |
---|---|---|
+ | 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 |
equals | Verifica 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' |
or | Verifica se dois valores são verdadeiros. | a > b or b <= c |
and | Verifica se os valores são verdadeiros. | bool(a) and bool(c) |
not | Verifica se nenhum dos valores é verdadeiro. | not (bool(a) and bool(c)) |
As funções a seguir são compatíveis:
Função | Descrição | Exemplos |
---|---|---|
max | Terá 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) |
min | Terá 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_present | Avalia 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. |
contains | Tem duas strings como entradas e retornará true se a primeira entrada contiver a segunda. | contains('hello', 'ello') = true enquanto contains('ello', 'hello') = false. |
concatenate | Ingressa 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:
xxxxxxxxxx
//Example formula
"calculationFormula": "closed - started"
Um exemplo mais avançado com condicionais:
xxxxxxxxxx
//Example formula
"calculationFormula": "if is_present(hs_latest_sequence_enrolled_date) then
if is_present(hs_sequences_actively_enrolled_count) an hs_sequences_actively_enrolled_count >= 1 then
true
else
false
else
''"
É 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
paracrm/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}
.
Observação: ao recuperar todas as propriedades, por padrão, somente propriedades não confidenciais são retornadas. Para recuperar propriedades de dados confidenciais, inclua o parâmetro de consulta dataSensitivity
com o valor sensitive
. Saiba mais sobre como gerenciar dados confidenciais via API (BETA, somente Enterprise).
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."
- Para valores que representam uma data específica, o formato de data completo será usado: YYYY-MM-DD (por exemplo,
- 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 propriedadesdate
exibem a data em que foram definidas, independentemente da configuração de fuso horário da conta ou do usuário. Para valores de propriedadedate
, 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 propriedadesdatetime
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 serfalse
. - 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 propriedadehs_buying_role
. Para adicionar valores sem substituir o valor existente, sua solicitação seria assim:
xxxxxxxxxx
///Example body for PATCH request to /crm/v3/objects/contacts/{contactId}
{
"properties": {
"hs_buying_role": ";BUDGET_HOLDER;END_USER"
}
}
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": ""}}
.