Última modificación: 22 de agosto de 2025

Run in Postman

 En HubSpot, los registros de contacto almacenan información sobre las personas que interactúan con tu empresa. Los endpoints de los contactos te permiten crear y administrar contactos, así como sincronizar los datos de los contactos entre HubSpot y otros sistemas. Obtén más información sobre las API de objetos, registros, propiedades y asociaciones en la guía informativa sobre el CRM. También, para obtener más información general sobre objetos y registros de HubSpot, consulta cómo Administrar la base de datos del CRM.

​
Crear contactos

Para crear nuevos contactos, haz una solicitud POST a /crm/v3/objects/contacts. En tu solicitud, incluye los datos del contacto en el objeto propiedades. También puedes agregar un objeto asociaciones para asociar el nuevo registro de contacto con los registros existentes (por ejemplo, empresas o negocios) o actividades (por ejemplo, reuniones o notas).

​
Propiedades

Los detalles del contacto se almacenan en las propiedades de contactos. Hay propiedades de contacto predeterminadas de HubSpot, pero también puedes crear propiedades personalizadas. Al crear un nuevo contacto, debes incluir al menos una de las siguientes propiedades en tu solicitud: email, firstname o lastname. Se recomienda siempre incluir email, ya que la dirección de correo electrónico es el identificador único principal para evitar la duplicación de registros de contactos en HubSpot. Para ver todas las propiedades disponibles, puedes obtener una lista de las propiedades de contacto de tu cuenta haciendo una solicitud GET a /crm/v3/properties/contacts. Encuentra más información sobre la API de propiedades.

​
Nota:

Si has incluido lifecyclestage en la solicitud, los valores deben referirse al nombre interno de la etapa del ciclo de vida. Los nombres internos de las etapas predeterminadas son valores de texto y no cambian aunque edites la etiqueta de la etapa (por ejemplo, subscriber o marketingqualifiedlead). Los nombres internos de las etapas personalizadas son valores numéricos. Puedes encontrar el ID interno de una etapa en la configuración de la etapa del ciclo de vida u obteniendo la propiedad de la etapa del ciclo de vida a través de la API.
Por ejemplo, para crear un nuevo contacto, la solicitud puede ser similar a la siguiente: 
///Example request body
{
"properties": {
"email": "example@hubspot.com",
"firstname": "Jane",
"lastname": "Doe",
"phone": "+18884827768",
"company": "HubSpot",
"website": "hubspot.com",
"lifecyclestage": "marketingqualifiedlead"
}
}

​
Asociaciones

Al crear un nuevo contacto, también puedes asociarlo con registros o actividades existentes en un objeto de asociaciones. Por ejemplo, para asociar un nuevo contacto con una empresa y correo electrónico existentes, tu solicitud se vería de la siguiente manera: 
///Example request body
{
"properties": {
"email": "example@hubspot.com",
"firstname": "Jane",
"lastname": "Doe",
"phone": "+18884827768",
"company": "HubSpot",
"website": "hubspot.com",
"lifecyclestage": "marketingqualifiedlead"
},
"associations": [
{
"to": {
"id": 123456
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 279
}
]
},
{
"to": {
"id": 556677
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 197
}
]
}
]
}
En el objeto asociaciones, debes incluir lo siguiente:
ParámetroDescripción
toEl registro o actividad que quieres asociar con el contacto, especificado por su valor id único.
typesEl tipo de asociación entre el contacto y el registro o actividad. Incluye associationCategoryy associationTypeId. Los ID de los tipos de asociación predeterminados se enumeran en este recurso, y también puedes obtener el valor de los tipos de asociación personalizados (es decir, etiquetas) a través de la API de asociaciones.

​
Buscar contactos por el ID de registro, correo electrónico o propiedad de valor único personalizada

Puedes buscar contactos individualmente o en lotes.
  • Para buscar un contacto individual, haz una solicitud GET a /crm/v3/objects/contacts/{contactId} or /crm/v3/objects/contacts/{email}?idProperty=email.
  • Para obtener una lista de todos los contactos, haz una solicitud GET a /crm/v3/objects/contacts.
En estos endpoints, 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 contacto solicitado no tiene un valor para una propiedad, este 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 contacto solicitado no tiene un valor para una propiedad, este 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 un lote de contactos específicos por el ID de registro, dirección de correo electrónico o una propiedad de identificador único personalizado, haz una solicitud POST a crm/v3/objects/contacts/batch/read. El endpoint por lotes no puede obtener asociaciones. Encuentra más información sobre cómo leer asociaciones por lotes con la API de asociaciones.
Para el endpoint de lectura por lotes, también puedes utilizar el parámetro opcional idProperty para buscar contactos por email o por una propiedad de identificador único personalizado. De forma predeterminada, los valores id de la solicitud se refieren al ID del registro (hs_object_id), por lo que no se requiere el parámetro idProperty al buscar por el ID del registro. Si estás utilizando email o una propiedad de valor único personalizado para buscar contactos, debes incluir el parámetro idProperty. Por ejemplo, para buscar un lote de contactos en función de los valores de ID del registro, tu solicitud podría verse así (solo valores actuales o valores actuales y antiguos): Para buscar contactos en función del correo electrónico o una propiedad de identificador único personalizado (por ejemplo, un número de identificación de cliente único para tu empresa), tu solicitud sería la siguiente:

​
Actualizar registros de contacto

Puedes actualizar registros de contacto individualmente o en lotes. Para actualizar registros de contactos individualmente, puedes usar el ID del registro (id) o la dirección de correo electrónico del contacto (email).
  • Para actualizar un solo contacto por su ID de registro, haz una solicitud PATCH a /crm/v3/objects/contacts/{contactId} e incluye los datos que quieres actualizar.
  • Para actualizar un solo contacto por su ID de registro, haz una solicitud PATCH a /crm/v3/objects/contacts/{email}?idProperty=email e incluye los datos que quieres actualizar.
Por ejemplo: 
{
  "properties": {
    "favorite_food": "burger",
    "jobtitle": "Manager",
    "lifecyclestage": "Customer"
  }
}

​
Nota:

Si actualizas la propiedad lifecyclestage, solo puedes elegir una etapa posterior en el orden de las etapas. Para retroceder la etapa del ciclo de vida a un valor anterior, primero deberás eliminar el valor actual de la etapa del ciclo de vida del registro. El valor se puede borrar manualmente, o se puede eliminar automáticamente mediante un workflow o una integración que sincronice los datos de los contactos.
Para actualizar los contactos por lotes, puedes utilizar los valores de ID de registro de los contactos (id). Para actualizar varios registros de contactos, haz una solicitud POST a /crm/v3/objects/contacts/batch/update En el cuerpo de la solicitud, incluye el ID de registro de cada contacto como el id e incluye las propiedades que quieres actualizar. Por ejemplo: 
{
  "inputs": [
    {
      "id": "123456789",
      "properties": {
        "favorite_food": "burger"
      }
    },
    {
      "id": "56789123",
      "properties": {
        "favorite_food": "Donut"
      }
    }
  ]
}

​
Actualizar y crear registros de contacto

También puedes crear y actualizar contactos por lotes al mismo tiempo utilizando el endpoint upsert. Para este endpoint, puedes utilizar email o una propiedad de identificador único personalizado. Tras la solicitud, si los contactos ya existen, se actualizarán y si no existen, se crearán. Para crear y actualizar contactos, envía una solicitud POST a /crm/v3/objects/contacts/batch/upsert. En el cuerpo de la solicitud, incluye el parámetro idProperty para identificar si estás utilizando email o una propiedad de identificador único personalizado. Incluye el valor de esa propiedad como id y añade las demás propiedades que quieres establecer o actualizar.

​
Nota:

Los upsert parciales no son compatibles cuando se utiliza email como idProperty para los contactos. Para completar un upsert parcial, utiliza en su lugar una propiedad de identificador único personalizado como idProperty.
Por ejemplo, tu solicitud podría tener el siguiente aspecto: 
{
  "inputs": [
    {
      "properties": {
        "phone": "+18884827768"
      },
      "id": "test@test.com",
      "idProperty": "email"
    },
    {
      "properties": {
        "phone": "+18888888888"
      },
      "id": "example@hubspot.com",
      "idProperty": "email"
    }
  ]
}

​
Asociar contactos existentes con registros o actividades

Para asociar contactos con otros registros del CRM o con una actividad, haz una solicitud PUT a /crm/v3/objects/contacts/{contactId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}.
Para obtener el valor associationTypeId, consulta esta lista de valores predeterminados o haz una solicitud GET a /crm/v4/associations/{fromObjectType}/{toObjectType}/labels.
Encuentra más información sobre la API de asociaciones.

​
Eliminar una asociación

Para eliminar una asociación entre un contacto y un registro o actividad, haz una solicitud DELETE a la siguiente URL: /crm/v3/objects/contacts/{contactID}/associations/{toObjectType}/{toObjectId}/{associationTypeId}.

​
Anclar una actividad en el registro de un contacto

Puedes anclar una actividad en un registro de contacto a través de la API incluyendo el campo hs_pinned_engagement_id en tu solicitud. En el campo, incluye el id de la actividad que quieres anclar, que se puede obtener a través de las API de interacciones. Puedes anclar una actividad por registro, y la actividad ya debe estar asociada con el contacto antes de anclarla. Para establecer o actualizar la actividad anclada de un contacto, la solicitud podría hacerse de la siguiente manera: 
{
  "properties": {
    "hs_pinned_engagement_id": 123456789
  }
}
También puedes crear un contacto, asociarlo a una actividad existente y anclar la actividad en la misma solicitud. Por ejemplo: 
{
  "properties": {
    "email": "example@hubspot.com",
    "firstname": "Jane",
    "lastname": "Doe",
    "phone": "+18884827768",
    "hs_pinned_engagement_id": 123456789
  },
  "associations": [
    {
      "to": {
        "id": 123456789
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 201
        }
      ]
    }
  ]
}

​
Eliminar contactos

Puedes eliminar contactos individualmente o por lotes, lo que agregará el contacto a la papelera de reciclaje en HubSpot. Más adelante puedes restaurar el registro de contacto dentro de HubSpot. Para eliminar un solo contacto usando su ID, haz una solicitud DELETE a /crm/v3/objects/contacts/{contactId}. Consulta más información sobre la eliminación por lotes de contactos en esta documentación de referencia.

​
Correos adicionales

Las direcciones de correo electrónico secundarias se utilizan cuando un contacto tiene más de un correo electrónico. Se pueden añadir manualmente en un registro de contacto en HubSpot o se pueden añadir automáticamente tras una combinación de contactos. Los correos electrónicos adicionales siguen siendo identificadores únicos para los contactos, por lo que varios contactos no pueden tener la misma dirección de correo electrónico adicional. Para ver los correos electrónicos adicionales de los contactos, incluye el parámetro properties con las propiedades email y hs_additional_emails. La dirección de correo electrónico principal de un contacto se mostrará en el campo email y los correos electrónicos adicionales se mostrarán en el campo hs_additional_emails.

​
Límites

Las operaciones por lotes están limitadas a 100 registros a la vez. Por ejemplo, no puedes actualizar por lotes más de 100 registros de contactos en una solicitud. También hay límites para contactos y envíos de formularios.