Productos compatibles
Se requiere uno de los siguientes productos o productos de ediciones superiores.
Marketing HubMarketing HubEnterprise
Sales HubSales HubEnterprise
Service HubService HubEnterprise
Content HubContent HubEnterprise
Última modificación: 28 de agosto de 2025

Run in Postman

 Cada cuenta de HubSpot, tiene los objetos estándar del CRM: contactos, empresas, negocios y tickets. Para representar y organizar los datos del CRM en función de las necesidades de tu empresa, también puedes crear objetos personalizados. Puedes crear un objeto personalizado en HubSpot o usar la API de objetos personalizados para definir objetos personalizados, propiedades y asociaciones a otros objetos del CRM. A continuación, aprende a crear y administrar objetos personalizados a través de la API, y ve un tutorial de cómo crear un objeto personalizado de ejemplo. Para obtener más información sobre la creación de objetos personalizados, consulta las siguientes publicaciones en el blog para desarrolladores de HubSpot:

​
Nota:

Los objetos personalizados son específicos de cada cuenta y, dependiendo de tu suscripción, hay límites en el número de objetos personalizados que puedes crear. En el Catálogo de productos y servicios de HubSpot encontrarás más información sobre los límites.

​
Métodos de autenticación

Puedes crear, leer y modificar objetos personalizados utilizando uno de los siguientes métodos de autenticación:

​
Crear objetos personalizados

Para crear objetos personalizados, primero deberás definir el esquema del objeto. El esquema incluye el nombre del objeto, las propiedades y las asociaciones con otros objetos del CRM. Puedes encontrar los detalles completos de la solicitud del esquema en la pestaña Esquema del objeto en la parte superior de este artículo. También puedes ver un ejemplo de solicitud en el tutorial a continuación. Para crear el esquema de objeto personalizado, haz una solicitud POST a crm/v3/schemas. En el cuerpo de la solicitud, incluye las definiciones para el esquema del objeto, lo que incluye el nombre, las propiedades y las asociaciones. Al asignarle un nombre al objeto personalizado, ten en cuenta lo siguiente:
  • Una vez creado un objeto, no puedes cambiar el nombre y la etiqueta.
  • El nombre solo puede contener letras, números y guiones bajos.
  • El primer carácter del nombre debe ser una letra.
  • Las etiquetas largas pueden aparecer cortadas en ciertas partes del producto.
A continuación, lee acerca de las definiciones requeridas para las propiedades y asociaciones del objeto.

​
Propiedades

Las propiedades que definas en el cuerpo de la solicitud se utilizarán para almacenar información en los registros de cada objeto personalizado.

​
Nota:

Puedes tener hasta 10 propiedades con un único valor por cada objeto personalizado en tu cuenta de HubSpot.
Las propiedades definidas se usarán para rellenar los siguientes campos basados en propiedades:
  • requiredProperties: las propiedades que se requieren al crear un nuevo registro de un objeto personalizado.
  • searchableProperties: las propiedades que se indexan para las búsquedas en HubSpot.
  • primaryDisplayProperty: la propiedad utilizada para asignar un nombre a cada registro de un objeto personalizado.
  • secondaryDisplayProperties: las propiedades que aparecen en cada registro bajo el campo primaryDisplayProperty.
custom-object-secondary-display-properties0
  • La primera propiedad que se indica en el campo secondaryDisplayProperties también se agregará como un cuarto filtro en la página de índice del objeto si es uno de los siguientes tipos de propiedad:
    • string
    • number
    • enumeration
    • boolean
    • datetime
custom-object-dashboard-filter0
  • Para evitar que se muestre una propiedad en la interfaz de usuario, primero deberás eliminar la propiedad y luego volver a crearla.
Por defecto, cuando se crean propiedades a través de la solicitud de esquema, el atributo type (tipo) de la propiedad se establece en string (cadena) y el atributo fieldType se establece en text (texto). A continuación se muestran los valores que puedes usar para crear diferentes tipos de propiedades.
typeDescripciónValores válidos de fieldType
enumerationUna cadena que representa un conjunto de opciones separadas por un punto y coma.booleancheckbox, checkbox, radio, select
dateUn valor con formato ISO 8601 que representa un día, mes y año específicos.date
dateTimeUn valor con formato ISO 8601 que representa un día, mes y hora específicos. La aplicación de HubSpot no mostrará la hora del día.date
stringUna cadena de texto sin formato, limitada a 65.536 caracteres.file, text, textarea
numberUn valor numérico que contiene dígitos y, como máximo, un decimal.number
fieldTypeDescripción
booleancheckboxUna entrada que permitirá a los usuarios seleccionar “Sí” o “No”. Cuando se usa en un formulario, se mostrará como una única casilla de verificación.
checkboxUna lista de casillas de verificación que permitirán al usuario seleccionar varias opciones de un conjunto de opciones permitidas para la propiedad.
dateUn valor de fecha, que se muestra como un selector de fechas.
filePermite subir un archivo a un formulario. Se almacena y se muestra como una URL que enlaza al archivo.
numberUna cadena de numerales o números escritos en notación decimal o científica.
radioInput 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.
selectInput en forma de desplegable que permiten a los usuarios seleccionar una opción de un conjunto de opciones permitidas para la propiedad.
textUna cadena de texto sin formato que se muestra como un input de texto de una sola línea.
textareaUna cadena de texto sin formato, que se muestra como un input de texto de varias líneas.

​
Asociaciones

HubSpot asociará automáticamente un objeto personalizado con los correos electrónicos, reuniones, notas, tareas, llamadas y objetos de conversaciones. También puedes asociar el objeto personalizado con otros objetos estándar de HubSpot u otros objetos personalizados. Al crear asociaciones a través de la solicitud de creación de esquema, identifica los objetos estándar usando el nombre y los objetos personalizados usando el valor objectTypeId. Por ejemplo: 

"associatedObjects": [
  "CONTACT",
  "COMPANY",
  "TICKET",
  "DEAL",
  "2-3453932"
]

​
Recuperar objetos personalizados existentes

Para recuperar todos los objetos personalizados, haz una solicitud GET a /crm/v3/schemas. Para recuperar un objeto personalizado específico, realiza una solicitud GET a uno de los siguientes endpoints:
  • /crm/v3/schemas/{objectTypeId}
  • /crm/v3/schemas/p_{object_name}
  • /crm/v3/schemas/{fullyQualifiedName}. Puedes encontrar un objeto fullyQualifiedName en su esquema, que se deriva de p{portal_id}_{object_name}. Puedes encontrar el ID del portal de tu cuenta utilizando la API de información de la cuenta.
Por ejemplo, para una cuenta con el ID 1234 y un objeto llamado lender, la URL de solicitud podría parecerse a cualquiera de los siguientes elementos:

​
Recuperar los registros de los objetos personalizados

También puedes recuperar los registros de un objeto personalizado.
  • Para recuperar un registro específico usando el valor del ID del registro, haz una solicitud GET a crm/v3/objects/{objectType}/{recordId}.
En este endpoint, puedes incluir los siguientes parámetros de consulta en la URL de la solicitud:
ParámetroDescripción
propertiesUna lista separada con comas de las propiedades que se devolverán en la respuesta. Si el registro de objeto personalizado solicitado no tiene un valor para una propiedad, no aparecerá en la respuesta.
propertiesWithHistoryUna lista separada con comas de las propiedades actuales y anteriores que se devolverán en la respuesta. Si el registro de objeto personalizado solicitado no tiene un valor para una propiedad, no aparecerá en la respuesta.
associationsUna lista separada con comas de los objetos para los que se deben obtener los ID asociados. No se devolverán en la respuesta las asociaciones especificadas que no existan. Encuentra más información sobre la API de asociaciones.
  • Para obtener varios registros, haz una solicitud POST a crm/v3/objects/{objectType}/batch/read. El endpoint en bloques no puede obtener asociaciones. Encuentra más información sobre cómo leer asociaciones en bloques con la API de asociaciones.
En tu solicitud, puedes obtener registros por su ID de registro (hs_object_id) o por una propiedad de identificador único personalizada. Por defecto, los valores id de la solicitud se refieren al ID del registro, por lo que no se requiere el parámetro idProperty al obtener datos por el ID del registro. Para usar una propiedad de valor único personalizada, debes incluir el parámetro idProperty. Por ejemplo, para recuperar un grupo de registros de objetos personalizados, tu solicitud podría tener una de estas dos estructuras: 
{
  "properties": ["petname"],
  "inputs": [
    {
      "id": "12345"
    },
    {
      "id": "67891"
    }
  ]
}

{
  "properties": ["petname"],
  "idProperty": "uniquepropertyexample",
  "inputs": [
    {
      "id": "abc"
    },
    {
      "id": "def"
    }
  ]
}
Para obtener registros de objetos personalizados con valores actuales y anteriores para una propiedad, tu solicitud podría ser como la siguiente: 
{
  "propertiesWithHistory": ["pet_owner"],
  "inputs": [
    {
      "id": "12345"
    },
    {
      "id": "67891"
    }
  ]
}

​
Modificar objetos personalizados existentes

Para modificar el esquema de un objeto, haz una solicitud PATCH a https://api.hubapi.com/crm/v3/schemas/{objectTypeId}. Una vez que tu objeto personalizado esté definido:
  • El nombre y las etiquetas del objeto (singular y plural) no se pueden cambiar.
  • Los parámetros requiredProperties, searchableProperties, primaryDisplayProperty y secondaryDisplayProperties se pueden cambiar actualizando el esquema del objeto. Para establecer una nueva propiedad como obligatoria, de búsqueda o de visualización, debes crear la propiedad antes de modificar el esquema.
  • Puedes crear y editar propiedades de objetos personalizados en HubSpot o a través de la API de propiedades.

​
Actualizar asociaciones

Para agregar otras asociaciones de objetos a tu objeto personalizado, haz una solicitud POST a /crm/v3/schemas/_{objectTypeId}_/associations. Solo puedes asociar tu objeto personalizado con objetos de HubSpot estándar (por ejemplo, contacto, empresa, negocio, o ticket) u otros objetos personalizados. En el campo toObjectTypeId, identifica los objetos personalizados por el valor objectTypeId y los objetos estándar por su nombre. Por ejemplo: 
{
  "fromObjectTypeId": "2-3444025",
  "toObjectTypeId": "ticket",
  "name": "cat_to_ticket"
}

​
Eliminar un objeto personalizado

Solo puedes eliminar un objeto personalizado después de eliminar todas las instancias de objetos de ese tipo. Para eliminar un objeto personalizado, haz una solicitud DELETE a /crm/v3/schemas/{objectType}. Si necesitas crear un nuevo objeto personalizado con el mismo nombre que el objeto eliminado, debes eliminar el esquema haciendo una solicitud DELETE a /crm/v3/schemas/{objectType}?archived=true. Solo puedes eliminar un tipo de objeto personalizado después de eliminar todas las instancias de objeto de ese tipo, las asociaciones y las propiedades personalizadas.

​
Ejemplo de objeto personalizado

Lo siguiente es un tutorial para crear un objeto personalizado. Para obtener detalles completos de las solicitudes que se muestran, consulta la pestaña Definición de objeto en la parte superior del artículo. Esta explicación cubre:
  1. La creación de un esquema de objeto personalizado.
  2. La creación de un registro de objeto personalizado.
  3. La asociación de un registro de objeto personalizado con un contacto de HubSpot.
  4. La creación de una nueva definición de asociación entre el objeto personalizado y el ticket de HubSpot.
  5. La creación de una nueva definición de propiedad.
  6. La actualización del esquema de objetos (es decir, secondaryDisplayProperties) con la nueva propiedad.
Meta: Un concesionario de automóviles llamado CarSpot quiere almacenar su inventario en HubSpot usando un objeto personalizado. Para hacer seguimiento de la propiedad del vehículo y las compras, asociarán los autos con los registros de contacto. Posteriormente, también harán seguimiento del mantenimiento del vehículo utilizando tickets de HubSpot y propiedades personalizadas.

​
Creación del esquema de objeto

CarSpot necesita crear un esquema de objeto que pueda representar los siguientes atributos como propiedades:
  1. Condición (nueva o usada): enumeración
  2. Fecha de recepción en el concesionario: fecha
  3. Año: número
  4. Marca: cadena
  5. Modelo: cadena
  6. Número de chasis: cadena (valor único)
  7. Color: cadena
  8. Kilometraje: número
  9. Precio: número
  10. Notas: cadena
También agregarán una descripción para proporcionar contexto sobre cómo utilizar el objeto y definirán una asociación entre el objeto personalizado y el objeto de contactos estándar para que puedan conectar los autos a los compradores potenciales. Con el modelo de datos finalizado, crearán el esquema de objeto haciendo una solicitud POST a /crm/v3/schemas con la siguiente solicitud: 
{
  "name": "cars",
  "description": "Cars keeps track of cars currently or previously held in our inventory.",
  "labels": {
    "singular": "Car",
    "plural": "Cars"
  },
  "primaryDisplayProperty": "model",
  "secondaryDisplayProperties": ["make"],
  "searchableProperties": ["year", "make", "vin", "model"],
  "requiredProperties": ["year", "make", "vin", "model"],
  "properties": [
    {
      "name": "condition",
      "label": "Condition",
      "type": "enumeration",
      "fieldType": "select",
      "options": [
        {
          "label": "New",
          "value": "new"
        },
        {
          "label": "Used",
          "value": "used"
        }
      ]
    },
    {
      "name": "date_received",
      "label": "Date received",
      "type": "date",
      "fieldType": "date"
    },
    {
      "name": "year",
      "label": "Year",
      "type": "number",
      "fieldType": "number"
    },
    {
      "name": "make",
      "label": "Make",
      "type": "string",
      "fieldType": "text"
    },
    {
      "name": "model",
      "label": "Model",
      "type": "string",
      "fieldType": "text"
    },
    {
      "name": "vin",
      "label": "VIN",
      "type": "string",
      "hasUniqueValue": true,
      "fieldType": "text"
    },
    {
      "name": "color",
      "label": "Color",
      "type": "string",
      "fieldType": "text"
    },
    {
      "name": "mileage",
      "label": "Mileage",
      "type": "number",
      "fieldType": "number"
    },
    {
      "name": "price",
      "label": "Price",
      "type": "number",
      "fieldType": "number"
    },
    {
      "name": "notes",
      "label": "Notes",
      "type": "string",
      "fieldType": "text"
    }
  ],
  "associatedObjects": ["CONTACT"]
}
Después de crear el esquema del objeto, CarSpot se asegura de anotar el campo {objectTypeId} del nuevo objeto, ya que lo utilizarán para extraer y modificar el objeto más adelante. También pueden utilizar el valor {fullyQualifiedName} si lo prefieren.

​
Crear un registro de objeto personalizado

Con el objeto personalizado creado, CarSpot ahora puede crear registros en el objeto para cada auto en su inventario. Crearán el primer registro para un auto haciendo una solicitud POST a /crm/v3/objects/2-3465404 con la siguiente solicitud: 
{
  "properties": {
    "condition": "used",
    "date_received": "1582416000000",
    "year": "2014",
    "make": "Nissan",
    "model": "Frontier",
    "vin": "4Y1SL65848Z411439",
    "color": "White",
    "mileage": "80000",
    "price": "12000",
    "notes": "Excellent condition. No accidents."
  }
}
La respuesta para esta llamada a la API se vería similar a: 
{
  "id": "181308",
  "properties": {
    "color": "White",
    "condition": "used",
    "make": "Nissan",
    "mileage": "80000",
    "model": "Frontier",
    "vin": "4Y1SL65848Z411439",
    "notes": "Excellent condition. No accidents.",
    "price": "12000",
    "year": "2014",
    "date_received": "1582416000000"
  },
  "createdAt": "2020-02-23T01:44:11.035Z",
  "updatedAt": "2020-02-23T01:44:11.035Z",
  "archived": false
}
Con el registro creado, pueden utilizar el valor de id para asociar más tarde cada auto con un contacto existente.
Si luego quisieran recuperar este registro junto con propiedades específicas, podrían hacer una solicitud GET a https://api.hubapi.com/crm/v3/objects/2-3465404/181308?portalId=1234567&properties=year&properties=make&properties=model

​
Asociar el registro de objeto personalizado a otro registro

Puedes usar el ID del nuevo registro de automóvil (181308) y el ID de otro registro para asociar un registro de objeto personalizado con un registro de otro objeto. Para crear una asociación, haz una solicitud PUT a /crm/v3/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}/{associationType}. Si la relación del objeto ya está definida, para determinar el valor associationType, haz una solicitud GET a crm/v3/schemas/{objectType}. Por ejemplo, con el ID 51 del contacto y el tipo de asociación 75, CarSpot puede asociar el registro del automóvil con un contacto. Usando los ID anteriores, la URL de la solicitud se creará de la siguiente manera: https://api.hubspot.com/crm/v3/objects/2-3465404/181308/associations/contacts/51/75

​
Definir una nueva asociación

CarSpot ahora quiere comenzar a hacer seguimiento de los servicios postventa para sus automóviles. Para ello, usarán los tickets de HubSpot a fin de registrar todo mantenimiento realizado. Para permitir las asociaciones entre automóviles y tickets, crearán una nueva asociación haciendo una solicitud POST a /crm/v3/schemas/2-3465404/associations con la siguiente solicitud: 
{
  "fromObjectTypeId": "2-3465404",
  "toObjectTypeId": "ticket",
  "name": "car_to_ticket"
}
La respuesta para esta llamada a la API se vería similar a: 
{
  "id": "121",
  "createdAt": "2020-02-23T01:52:12.893826Z",
  "updatedAt": "2020-02-23T01:52:12.893826Z",
  "fromObjectTypeId": "2-3465404",
  "toObjectTypeId": "0-5",
  "name": "car_to_ticket"
}
Al crear una nueva asociación entre dos objetos personalizados, especifica los objetos personalizados por el valor objectTypeId en el campo toObjectTypeId. En el caso de los objetos estándar, puedes identificarlos por su nombre o utilizar los siguientes valores:
  • Contacto: 0-1
  • Empresa: 0-2
  • Negocio: 0-3
  • Ticket: 0-5

​
Definir una nueva propiedad

A medida que continúan haciendo seguimiento al mantenimiento, CarSpot ve una oportunidad para agrupar estos servicios en paquetes. Para hacer seguimiento de estos paquetes de mantenimiento en los registros de cada vehículo, crearán una nueva propiedad de enumeración que contenga los paquetes disponibles. Para definir una nueva propiedad, realizarán una solicitud POST a /crm/v3/properties/2-3465404 con la siguiente solicitud: 
{
  "groupName": "car_information",
  "name": "maintenance_package",
  "label": "Maintenance Package",
  "type": "enumeration",
  "fieldType": "select",
  "options": [
    {
      "label": "Basic",
      "value": "basic"
    },
    {
      "label": "Oil change only",
      "value": "oil_change_only"
    },
    {
      "label": "Scheduled",
      "value": "scheduled"
    }
  ]
}
La respuesta para esta llamada a la API se vería similar a: 
{
  "updatedAt": "2020-02-23T02:08:20.055Z",
  "createdAt": "2020-02-23T02:08:20.055Z",
  "name": "maintenance_package",
  "label": "Maintenance Package",
  "type": "enumeration",
  "fieldType": "select",
  "groupName": "car_information",
  "options": [
    {
      "label": "Basic",
      "value": "basic",
      "displayOrder": -1,
      "hidden": false
    },
    {
      "label": "Oil change only",
      "value": "oil_change_only",
      "displayOrder": -1,
      "hidden": false
    },
    {
      "label": "Scheduled",
      "value": "scheduled",
      "displayOrder": -1,
      "hidden": false
    }
  ],
  "displayOrder": -1,
  "calculated": false,
  "externalOptions": false,
  "archived": false,
  "hasUniqueValue": false,
  "hidden": false,
  "modificationMetadata": {
    "archivable": true,
    "readOnlyDefinition": false,
    "readOnlyValue": false
  },
  "formField": false
}
Ahora que se creó la propiedad, quieren que aparezca en la barra lateral de cada registro de automóvil para que la información esté fácilmente disponible para sus representantes de ventas y técnicos. Para ello, agregarán la propiedad a secondaryDisplayProperties haciendo una solicitud PATCH a /crm/v3/schemas/2-3465404 con la siguiente solicitud: 
{
  "secondaryDisplayProperties": ["maintenance_package"]
}
La respuesta para esta llamada a la API se vería similar a: 
{
  "id": "3465404",
  "createdAt": "2020-02-23T01:24:54.537Z",
  "updatedAt": "2020-02-23T02:12:24.175874Z",
  "labels": {
    "singular": "Car",
    "plural": "Cars"
  },
  "requiredProperties": ["year", "model", "vin", "make"],
  "searchableProperties": ["year", "model", "vin", "make"],
  "primaryDisplayProperty": "model",
  "secondaryDisplayProperties": ["maintenance_package"],
  "portalId": 1234567,
  "name": "car"
}
Ahora, cuando los técnicos abren un registro de contacto que tiene un automóvil asociado, la propiedad se mostrará en la tarjeta de objeto personalizada en la barra lateral:
Screen Shot 2020-03-06 at 11.08.41 AM
A medida que CarSpot continúa usando HubSpot, es probable que encuentren formas de mejorar y expandir este objeto personalizado, entre otras cosas, usando la API de HubSpot. Incluso podrían decidir crear páginas dinámicas usando los datos de los objetos personalizados.