Contactos
En HubSpot, los registros de contacto almacenan información sobre las personas que interactúan con tu empresa. Los puntos de terminación de los contactos te permiten crear y administrar registros de contacto en tu cuenta de HubSpot, 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 Comprender el CRM. Para obtener más información general sobre objetos y registros de HubSpot, aprende a administrar la base de datos del CRM.
Para crear nuevos registros de contacto, haz una solicitud POST
en /crm/v3/objects/contacts
.
En tu solicitud, incluye los datos del contacto en el objeto propiedades. También puedes agregar el objeto asociaciones para asociar el nuevo registro de empresa con registros existentes (por ejemplo, contactos, negocios) o actividades (por ejemplo, reuniones, notas).
Los detalles de los contactos se almacenan en las propiedades de los contactos. Hay propiedades de contacto de HubSpot predeterminadas, pero también puedes crear propiedades de contacto personalizadas.
Al crear un nuevo registro de contacto, debes incluir al menos una de las siguientes propiedades en tu solicitud: email
, firstname
o lastname
. Se recomienda incluir siempre email
, ya que la dirección de correo electrónico es el identificador único principal para evitar duplicación de registros de contacto en HubSpot.
Para ver todas las propiedades disponibles, puedes recuperar una lista de las propiedades de contacto de tu cuenta haciendo una solicitud GET
en /crm/v3/properties/contacts
. Más información sobre la API de propiedades.
lifecyclestage
en tu 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 incluso si editas la etiqueta de la etapa (por ejemplo, subscriber
o líder calificado de marketing
). 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 o recuperando la propiedad de la etapa del ciclo de vida a través de la API.
Por ejemplo, para crear un nuevo registro de contacto, tu solicitud puede ser similar a la siguiente:
Al crear un nuevo contacto, también puedes asociarlo con registros o actividades existentes. En el objeto asociaciones, incluye los siguientes campos:
Parameter | Description |
---|---|
toObjectId
| El ID del registro o actividad con los que deseas asociar el contacto. |
associationTypeId
| Un identificador único para indicar el tipo de asociación entre el contacto y el otro objeto o actividad. Los tipos de asociación predeterminados se muestran aquí, o puedes recuperar el valor haciendo una solicitud |
También puedes incluir el campo label
para asignar una etiqueta de asociación definida que describa la asociación. Más información sobre cómo asociar registros a través de la API 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:
Puedes recuperar contactos individualmente o en lotes.
- Para recuperar un registro de contacto individual, haz una solicitud
GET
en/crm/v3/objects/contacts/{contactId}
. - Para solicitar una lista de todos los registros de contacto, haz una solicitud
GET
en/crm/v3/objects/contacts
.
En estos puntos de terminación, puedes incluir los siguientes parámetros de consulta en la URL de la solicitud:
Parameter | Description |
---|---|
propiedades
| Una lista separada por 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. |
propertiesWithHistory
| Una lista separada por comas de las propiedades actuales e históricas 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. |
asociaciones
| Una lista separada por comas de los objetos de los cuales recuperar los ID asociados. No se devolverán en la respuesta las asociaciones especificadas que no existan. Más información sobre la API de asociaciones. |
- Para recuperar un lote de contactos específicos por ID de registro, dirección de correo electrónico o una propiedad de identificador único personalizada, haz una solicitud
POST
acrm/v3/objects/contacts/batch/read
. El punto de terminación por lote no puede recuperar asociaciones. Obtener más información sobre cómo leer asociaciones por lotes con la API de asociaciones.
idProperty
para recuperar contactos por correo electrónico
o una propiedad de identificador único personalizada. Por opción predeterminada, los valores de id
en la solicitud se refieren al ID de registro (hs_object_id
), por lo que no se requiere el parámetro idProperty
al recuperar por ID de registro. Si estás utilizando email
o una propiedad de valor único personalizada para recuperar contactos, debes incluir el parámetro idProperty
.Por ejemplo, para recuperar un lote de contactos en función de los valores de ID de registro, tu solicitud podría verse así (solo valores actuales o valores actuales e históricos):
Para recuperar contactos en función de la dirección de correo electrónico o una propiedad de identificador único personalizado (por ejemplo, un número de identificación de cliente único para tu negocio), tu solicitud sería la siguiente:
Puedes actualizar registros de contacto individualmente o en lotes. Para los contactos existentes, el correo electrónico y el ID de registro son valores únicos, por lo que puedes usar id
o email
para actualizar los contactos a través de la API.
Para actualizar un registro de contacto individual mediante el ID del contacto, realiza una solicitud PATCH
a /crm/v3/objects/contacts/{contactId}
e incluye los datos que deseas actualizar.
Para asociar un registro de contacto con otros registros del CRM o con una actividad, haz una solicitud PUT
en /crm/v3/objects/contacts/{contactId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}
.
associationTypeId
, consulta esta lista de valores predeterminados o haz una solicitud GET
a/crm/v4/associations/{fromObjectType}/{toObjectType}/labels
.
Más información sobre la API de asociaciones.
Para eliminar una asociación entre un registro de contacto y un registro o actividad, realiza una solicitud DELETE
en la siguiente URL: /crm/v3/objects/contacts/{contactID}/associations/{toObjectType}/{toObjectId}/{associationTypeId}
.
You can pin an activity on a contact record by including the hs_pinned_engagement_id
field in your request. In the field, include the id
of the activity to pin, which can be retrieved via the engagements APIs. You can pin one activity per record, and the activity must already be associated with the contact prior to pinning.
To set or update a contact's pinned activity, your request could look like:
You can also create a contact, associate it with an existing activity, and pin the activity in the same request. For example:
Puedes eliminar registros de contacto individualmente o por lotes, lo que agregará el registro de contacto a la papelera de reciclaje en HubSpot. Más adelante puedes restaurar el registro de contacto dentro de HubSpot.
Para eliminar un registro de contacto individual por su ID, haz una solicitud DELETE
en /crm/v3/objects/contacts/{contactId}
.
Obtén más información sobre la eliminación de registros de contacto por lotes en la pestaña Puntos de terminación en la parte superior de este artículo.
Batch operations for creating, updating, and archiving are limited to batches of 100. There are also limits for contacts and form submissions.
Gracias por tus comentarios, son muy importantes para nosotros.