API del CRM | Propiedades

Última modificación: 22 de agosto de 2025

Run in Postman

Usa las propiedades para almacenar información en los registros del CRM. HubSpot proporciona un conjunto de propiedades predeterminadas para cada objeto del CRM y también puedes crear y administrar tus propias propiedades personalizadas en HubSpot o mediante la API de propiedades. Al crear propiedades, es importante tener en cuenta cómo organizar los datos. En muchos casos, la creación de propiedades personalizadas para los objetos estándar de HubSpot es el procedimiento correcto. Sin embargo, puede haber ocasiones en las que debas crear un objeto personalizado independiente con su propio conjunto de propiedades.

Propiedades predeterminadas

Los objetos del CRM están definidos por un tipo principal type y un conjunto de propiedades properties. Cada tipo tiene un conjunto único de propiedades estándar, representado por un mapa de pares nombre-valor. Encuentra más información sobre las propiedades predeterminadas para diferentes objetos:

Contactos
Empresas
Negocios
Tickets
Actividades (llamadas, correos, reuniones, notas, tareas)
Leads(Sales Hub Pro y Enterprise)

Grupos de propiedades

Los grupos de propiedades se utilizan para agrupar propiedades relacionadas. Todas las propiedades agrupadas aparecerán una al lado de la otra en los registros de HubSpot. Si tu integración crea propiedades personalizadas de objetos, los grupos de propiedades personalizadas facilitarán la identificación de esos datos.

Valores type y fieldType de las propiedades

Cuando se crean o actualizan las propiedades, los valores type y fieldType son obligatorios. El valor type determina el tipo de propiedad, es decir, indica si es una cadena de texto o un número. La propiedad fieldType determina cómo aparecerá la propiedad en HubSpot o en un formulario, es decir, si aparecerá como un campo de texto sin formato, un menú desplegable o un selector de fechas. En la siguiente tabla encontrarás información sobre los valores type disponibles para las propiedades y los valores de fieldType correspondientes.

`type`	Descripción	Valores válidos de `fieldType`
`bool`	Un campo que contiene opciones binarias (por ejemplo, `Yes` o `No`, `True` o `False`).	`booleancheckbox`, `calculation_equation`
`enumeration`	Una cadena que representa un conjunto de opciones que están separadas por un punto y coma.	`booleancheckbox`, `checkbox`, `radio`, `select`, `calculation_equation`
`date`	Un valor que representa un día, mes y año específicos. Los valores deben estar en la zona horaria UTC y el formato puede ser una cadena en notación ISO 8601 o una marca de tiempo EPOCH en milisegundos (es decir, la media noche en la zona horaria UTC).	`date`
`datetime`	Un valor que representa un día, mes, año y hora específicos del día. Los valores deben estar en la zona horaria UTC y el formato puede ser una cadena en notación ISO 8601 o una marca de tiempo EPOCH en milisegundos.	`date`
`string`	Una cadena de texto sin formato, limitada a 65.536 caracteres.	`file`, `text`, `textarea`, `calculation_equation`, `html`, `phonenumber`
`number`	Un valor numérico que contiene dígitos y, como máximo, un decimal.	`number`, `calculation_equation`
`object_coordinates`	Un valor textual utilizado para hacer referencia a otros objetos de HubSpot y que se utiliza solo para propiedades internas. Las propiedades de este tipo no se pueden crear ni editar, y no son visibles en HubSpot.	`text`
`json`	Un valor textual almacenado en formato JSON que se utiliza solo para propiedades internas. Las propiedades de este tipo no se pueden crear ni editar, y no son visibles en HubSpot.	`text`

Los valores válidos para fieldType incluyen:

Fieldtype	Descripción
`booleancheckbox`	El input que permitirá a los usuarios seleccionar “sí” o “no”. Cuando se usa en un formulario, se mostrará como una única casilla de comprobación. Descubre cómo agregar un valor a las propiedades de casilla de comprobación única.
`calculation_equation`	Una ecuación personalizada que puede calcular valores basados en otros valores y asociaciones de las propiedades. Más información sobre cómo definir propiedades de cálculo.
`checkbox`	Una lista de casillas de verificación que permitirán al usuario seleccionar varias opciones de un conjunto de opciones permitidas para la propiedad. Descubre cómo dar formato a los valores al actualizar propiedades con múltiples casillas de comprobación.
`date`	Un valor de fecha, que se muestra como un selector de fechas.
`file`	Permite subir un archivo en un registro o a través de un formulario. Almacena un ID de archivo.
`html`	Una cadena, renderizada como HTML desinfectado, que permite el uso de un editor de texto enriquecido para la propiedad.
`number`	Una cadena de numerales o números escritos en notación decimal o científica.
`phonenumber`	Una cadena de texto sin formato que se muestra en forma de número de teléfono.
`radio`	Input que permitirá a los usuarios seleccionar una opción de un conjunto de opciones permitidas para la propiedad. Si se utiliza en un formulario, se mostrará como un conjunto de botones de selección.
`select`	Input en forma de desplegable que permiten a los usuarios seleccionar una opción de un conjunto de opciones permitidas para la propiedad.
`text`	Una cadena de texto sin formato que se muestra como un input de texto de una sola línea.
`textarea`	Una cadena de texto sin formato, que se muestra como un input de texto de varias líneas.

Crear una propiedad

Para crear una propiedad, envía una solicitud POST a /crm/v3/properties/{objectType}. Incluye los siguientes campos obligatorios en el cuerpo de la solicitud:

groupName: el grupo de propiedades en el que estará la propiedad.
name: el nombre interno de la propiedad (por ejemplo, favorite_food).
label: el nombre de la propiedad tal como aparece en HubSpot (por ejemplo, comida favorita).
type: el tipo de propiedad.
fieldType: el tipo de campo de la propiedad.

Por ejemplo, para crear una propiedad de contacto llamada Comida favorita, la solicitud debería verse así:

{
"groupName": "contactinformation",
"name": "favorite_food",
"label": "Favorite Food",
"type": "string",
"fieldType": "text"
}

Crear propiedades de identificador único

Cuando se crea un registro en HubSpot, se genera automáticamente un ID único (hs_object_id) que debe ser tratado como una cadena de texto. Estos ID solo son únicos dentro de ese tipo de objeto, por lo que puede haber un contacto y una empresa con el mismo ID. Para los contactos y las empresas, hay identificadores únicos adicionales, entre ellos, la dirección de correo electrónico de un contacto (email) y el nombre de dominio de una empresa (domain). En algunos casos, puede que quieras crear tu propia propiedad de identificador único, de forma que no haya la posibilidad de introducir el mismo valor para varios registros. Puedes tener hasta diez propiedades de ID único por objeto. Para crear una propiedad que requiera valores únicos a través de la API:

Haz una solicitud POST a /crm/v3/properties/{objectType}.
En el cuerpo de la solicitud, en el campo hasUniqueValue, establece el valor como true.

{
"groupName": "dealinformation",
"name": "system_a_unique",
"label": "Unique ID for System A",
"hasUniqueValue": true,
"type": "string",
"fieldType": "text"
}

Una vez que hayas creado tu propiedad de ID único, puedes usarla en una llamada a la API para acceder a registros específicos. Por ejemplo, para recuperar un negocio con un valor de abc para la propiedad system_a_unique, la URL de la solicitud sería: /crm/v3/objects/deals/abc?idProperty=system_a_unique. Luego puedes usar este valor de propiedad de identificador único para encontrar y actualizar registros específicos de la misma manera en que podrías usar hs_object_id, email (contactos) o domain (empresas).

Crear propiedades de cálculo

Las propiedades de cálculo definen un valor de propiedad basado en otras propiedades dentro del mismo registro de objeto. Se definen utilizando una fórmula que puede incluir operaciones como min, max, count, sum o average. Puedes usar la API de propiedades para leer o crear propiedades de cálculo en tu cuenta de HubSpot, usando un campo calculation_equation y un tipo de valor number, bool, string o enumeration. Puedes definir la fórmula para calcular la propiedad con el campo calculationFormula.

Nota:

Las propiedades de cálculo creadas mediante la API no se pueden editar en HubSpot. Solo puedes editar estas propiedades a través de la API de propiedades.

Sintaxis de la propiedad de cálculo

Usando calculationFormula, puedes escribir una fórmula usando operadores aritméticos, operadores de comparación, operadores lógicos, sentencias condicionales y otras funciones.

Sintaxis de los literales

Literal de cadena: Las cadenas constantes se pueden representar con comillas simples ('constant') o comillas dobles ("constant").
Literal numérico: Los números constantes pueden ser cualquier número real y pueden incluir notación de punto, 1005 y 1.5589 son números constantes válidos.
Literal de booleano: Los booleanos constantes pueden ser true o false.

Sintaxis de las propiedades

Variables de la propiedad de cadena: para que una cadena de identificador se interprete como una propiedad de cadena, debe estar en la función string. Por ejemplo, string(var1)se interpretará como el valor de la propiedad de cadena var1.
Variables de propiedad numérica: todos los identificadores se interpretarán como variables de la propiedad numérica. Por ejemplo, var1 se interpretará como el valor de la propiedad numérica var1.
Variables de propiedad booleana: para que un identificador se interprete como una propiedad booleana, debe estar en la función bool. Por ejemplo, el identificador bool(var1) se interpretará como el valor de la propiedad booleana var1.

Nota:

El lenguaje utilizado distingue entre mayúsculas y minúsculas en todos los tipos, excepto las cadenas. Por ejemplo, If A ThEn B es exactamente igual que if a then b pero 'a' no es lo mismo que 'A'. Los espacios, las tabulaciones y las nuevas líneas se utilizan para la tokenización, pero se ignoran.

Operadores

Los operadores se pueden usar con valores literales y de propiedad. Para los operadores aritméticos, puedes usar la notación de prefijo para multiplicar, y paréntesis para especificar el orden de las operaciones.

Operador	Descripción	Ejemplos
`+`	Agrega números o cadenas.	`property1 + 100`
`-`	Resta números.	`property1 + 100 - property2`
`*`	Multiplica números.	`10property1` = `10 * property1`
`/`	Dividir números.	`property1 * (100 - property2/(50 - property3))`
`<`	Comprueba si un valor es menor que otro, Y funciona con propiedades numéricas o constantes.	`a < 100`
`>`	Comprueba si un valor es mayor que otro, Y funciona con propiedades numéricas o constantes.	`a > 50`
`<=`	Comprueba si un valor es menor o igual que otro, Y funciona con propiedades numéricas o constantes.	`a <= b`
`>=`	Comprueba si un valor es mayor o igual que otro, Y funciona con propiedades numéricas o constantes.	`b>= c`
`=`	Comprueba si un valor es igual a otro, Y funciona tanto con números como con cadenas.	`(a + b - 100c * 150.652) = 150-230b`
`equals`	Comprueba si un valor es igual a otro, Y funciona tanto con números como con cadenas.	`a + b - 100.2c * 150 equals 150 - 230`
`!=`	Comprueba si un valor no es igual a otro, Y funciona tanto con números como con cadenas.	`string(property1) != 'test_string'`
`or`	Comprueba si cualquiera o los dos valores es verdadero.	`a > b or b <= c`
`and`	Comprueba si ambos valores son verdaderos.	`bool(a) and bool(c)`
`not`	Comprueba si ninguno de los valores es verdadero.	`not (bool(a) and bool(c))`

Funciones

Las siguientes son las funciones que se pueden aplicar:

Función	Descripción	Ejemplos
`max`	Tendrá entre 2 y 100 números, y la respuesta será el número máximo de todas las entradas.	`max(a, b, c, 100)` o `max(a, b)`
`min`	Tendrá entre 2 y 100 números, y la respuesta será el número mínimo de todas las entradas.	`min(a, b, c, 100)` o `min(a, b)`
`is_present`	Evalúa si se puede evaluar una expresión	`is_present(bool(a))`= true si la propiedad es booleana, pero `is_present(bool(a))` = false si la propiedad está vacía o no es booleana.
`contains`	Tiene dos cadenas y la respuesta será “true” si la primera entrada contiene la segunda.	`contains('hello', 'ello')` = `true` y `contains('ello', 'hello')` = false.
`concatenate`	Se une a una lista de cadenas. La lista de entradas puede ir de 2 a 100.	`concatenate('a', 'b', string(a), string(b))`

También hay dos funciones de análisis:

number_to_string: intenta convertir la expresión del número de entrada en una cadena.
string_to_number: intenta convertir la expresión de la cadena de entrada en un número.

Por ejemplo, "Number of cars: " + num_cars no es una propiedad válida porque no puedes agregar una cadena con un número, pero "Number of cars: " + number_to_string(num_cars) lo es.

Declaraciones condicionales

También puedes escribir la fórmula con sentencias condicionales usando if, elseif, endif y else. Por ejemplo, una sentencia condicional podría parecerse a lo siguiente: if boolean_expression then statement [elseif expression then statement]* [else statement | endif] donde los corchetes [a] indican que “a” es opcional, a|b indica que pueden ser “a” o “b”, y * significa 0 o más. endif se puede usar para terminar una sentencia condicional de manera anticipada para garantizar que el analizador sintáctico (parser) pueda identificar a qué if pertenece el siguiente elseif.

Fórmulas de ejemplo

A continuación encontrarás ejemplos que puedes usar para definir tus propias fórmulas de cálculo:

"calculationFormula": "closed - started"

Un ejemplo más avanzado con condicionales:

"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
  ''"

Encontrar propiedades

Puedes buscar la información de propiedades individuales o de todas las propiedades dentro de un objeto.

Para encontrar una propiedad individual, haz una solicitud GET a crm/v3/properties/{object}/{propertyName}. Por ejemplo, para encontrar la propiedad favorite_food, la URL de la solicitud sería /crm/v3/properties/contacts/favorite_food
Para encontrar todas las propiedades de un objeto, haz una solicitud GET a /crm/v3/properties/{objectType}.

Nota:

De manera predeterminada, al buscar todas las propiedades, la respuesta solo incluye las propiedades que no contienen datos sensibles. Para encontrar las propiedades de datos sensibles, incluye el parámetro de consulta dataSensitivity con el valor sensitive. Encuentra más información sobre la gestión de datos sensibles mediante API (BETA, Enterprise solamente).

Actualizar o borrar los valores de una propiedad

Para actualizar el valor de una propiedad para un registro, haz una solicitud PATCH a crm/v3/objects/{objectType}/{recordId}. En el cuerpo de tu solicitud, incluye las propiedades y sus valores en una matriz. Más información sobre la actualización de registros a través de las API de objetos.

Añadir valores a las propiedades date y datetime

Los valores de hora se muestran en formato ISO 8601 en las respuestas, pero las API aceptarán cualquiera de estos dos formatos para los valores de fecha y hora:

Cadenas con formato ISO 8601: según el tipo de datos, se utilizará uno de estos dos formatos:
- Para los valores que representan una fecha específica, se usará el formato de fecha completa: AAAA-MM-DD (por ejemplo, 2020-02-29)
- Para los valores que representan una fecha y hora específicos, se usará un formato de fecha completo además de las horas, minutos, segundos y una fracción decimal de un segundo: AAAA-MM-DDThh:mm:ss.sTZD (por ejemplo, 2020-02-29T03:30:17.000Z). La hora está en la zona horaria UTC, por lo que los valores siempre usarán el designador UTC “Z”.”
Marcas de tiempo en formato UNIX en milisegundos: valores de marca de tiempo en milisegundos, que están en la zona horaria UTC. Por ejemplo, el valor de la marca de tiempo 1427997766000 se traduce al 02 de abril de 2015 a las 18:02:46 UTC o al 2 de abril de 2015 a las 2:02:46 p. m. EDT (horario de verano del este).

Existen dos tipos de propiedades para almacenar fechas (date y datetime) que también afectan el formato de los valores:

La propiedad date almacena la fecha, no la hora. La propiedad date muestra la fecha en la que están configuradas, independientemente de la configuración de zona horaria de la cuenta o del usuario. Para los valores de la propiedad date, se recomienda utilizar el formato de fecha completa ISO 8601. Si utilizas el formato de marca de tiempo UNIX, debes utilizar una marca de tiempo EPOCH en milisegundos (es decir, el valor debe establecido en la medianoche de la zona UTC para la fecha). Por ejemplo, el 1 de mayo de 2015 se puede representar así en cualquiera de los dos formatos:
- ISO 8601: 2015-05-01
- Marca de tiempo EPOCH en milisegundos: 1430438400000
La propiedad datetime almacena tanto la fecha como la hora. Se aceptará cualquiera de estos formatos de marca de tiempo. En HubSpot, las propiedades datetime se muestran con base en la zona horaria del usuario que ve el registro, por lo que el valor se convertirá a la zona horaria local del usuario.

Agregar valores a las propiedades de tipo casilla de verificación

Al actualizar los valores para las propiedades de tipo casilla de verificación de un registro, los valores pueden tener los siguientes formatos:

Propiedad de casilla de verificación booleana: para que se muestre como Sí, o como marcada en HubSpot, el valor debe ser true. Para que aparezca como No o sin marcar en HubSpot, el valor debe ser false.
Propiedad de casillas de verificación de selección múltiple: para añadir o adjuntar valores a una propiedad de casillas de verificación múltiples, incluye un punto y coma antes del primer valor y separa los valores con punto y coma sin espacio entre ellos. Si la propiedad tiene un valor existente, el punto y coma inicial adjuntará los valores en lugar de sobrescribirlos. Por ejemplo, un contacto tiene el valor DECISION_MAKER para la propiedad hs_buying_role. Para agregar más valores sin sustituir el valor existente, la solicitud debería ser así:

{
"properties": {
"hs_buying_role": ";BUDGET_HOLDER;END_USER"
}
}

Asignar propietarios de registros con propiedades de usuario

Al asignar usuarios a los registros del CRM a través de la API, el valor debe ser el id del propietario del usuario, que puedes encontrar en la configuración de propiedades o a través de la API de propietarios. Por ejemplo, para asignar un usuario como propietario de un contacto, envía una solicitud PATCH a crm/v3/objects/contacts/{contactId}, con el cuerpo { "properties":{ "hubspot_owner_id": "41629779"}}.

Borrar un valor de propiedad

Puedes borrar un valor de las propiedades de objeto a través de la API configurando el valor de la propiedad como una cadena vacía. Por ejemplo, para borrar firstname de un objeto de contacto, envía una solicitud PATCH a /crm/v3/objects/contacts/{contactId} con el cuerpo { "properties": { "firstname": ""}}.

Citas

Asociaciones v3

Esquema de Asociaciones v3

Asociaciones v4

Esquema de Asociaciones v4

Carritos

Pagos de Commerce

Suscripciones de Commerce

Empresas

Contactos

Cursos

Objetos personalizados

Negocios

Descuentos

Exportaciones

Tarifas

Metas

Importaciones

Facturas

Leads

Elementos de pedido

Listas

Fichas

Objetos

Pedidos

Propietarios

Clientes de partners

Servicios de partners

Pipelines

Productos

Propiedades

Validación de propiedades

Cotizaciones

Servicios

Impuestos

Tickets

Comunicaciones

Contratos

Divisiones de negocios

Envíos de comentarios

Seguimiento de límites

Biblioteca de objetos

Esquemas

Run in Postman

​Propiedades predeterminadas

​Grupos de propiedades

​Valores type y fieldType de las propiedades

​Crear una propiedad

​Crear propiedades de identificador único

​Crear propiedades de cálculo

​Nota:

​Sintaxis de la propiedad de cálculo

​Sintaxis de los literales

​Sintaxis de las propiedades

​Nota:

​Operadores

​Funciones

​Declaraciones condicionales

​Fórmulas de ejemplo

​Encontrar propiedades

​Nota:

​Actualizar o borrar los valores de una propiedad

​Añadir valores a las propiedades date y datetime

​Agregar valores a las propiedades de tipo casilla de verificación

​Asignar propietarios de registros con propiedades de usuario

​Borrar un valor de propiedad

Propiedades predeterminadas

Grupos de propiedades

Valores type y fieldType de las propiedades

Crear una propiedad

Crear propiedades de identificador único

Crear propiedades de cálculo

Nota:

Sintaxis de la propiedad de cálculo

Sintaxis de los literales

Sintaxis de las propiedades

Nota:

Operadores

Funciones

Declaraciones condicionales

Fórmulas de ejemplo

Encontrar propiedades

Nota:

Actualizar o borrar los valores de una propiedad

Añadir valores a las propiedades date y datetime

Agregar valores a las propiedades de tipo casilla de verificación

Asignar propietarios de registros con propiedades de usuario

Borrar un valor de propiedad