> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.es/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# API del CRM | Contactos
export const postmanIcon = ;
export const ScopesList = ({scopes = [], description = "Esta API requiere uno de los siguientes ámbitos:"}) => {
if (!scopes || scopes.length === 0) {
return null;
}
const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
return
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
;
};
# Contactos
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](/guides/crm/understanding-the-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](http://knowledge.hubspot.com/contacts-user-guide).
## 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](https://knowledge.hubspot.com/es/properties/hubspots-default-contact-properties), pero también puedes [crear propiedades personalizadas](https://knowledge.hubspot.com/es/properties/create-and-edit-properties).
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](https://knowledge.hubspot.com/es/records/deduplication-of-records#automatic-deduplication-in-hubspot) 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](/api-reference/crm-properties-v3/guide).
### 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](https://knowledge.hubspot.com/es/properties/create-and-edit-properties) de la etapa (por ejemplo, `subscriber` o `marketingqualifiedlead`). Los nombres internos de las [etapas personalizadas](https://knowledge.hubspot.com/es/object-settings/create-and-customize-lifecycle-stages) son valores numéricos. Puedes encontrar el ID interno de una etapa en la [configuración de la etapa del ciclo de vida](https://knowledge.hubspot.com/es/object-settings/create-and-customize-lifecycle-stages) 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:
```json theme={null}
///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](https://knowledge.hubspot.com/es/records/associate-records) o [actividades existentes](https://knowledge.hubspot.com/es/records/associate-activities-with-records) 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:
```json theme={null}
///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ámetro | Descripción |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `to` | El registro o actividad que quieres asociar con el contacto, especificado por su valor `id` único. |
| `types` | El tipo de asociación entre el contacto y el registro o actividad. Incluye `associationCategory`y `associationTypeId`. Los ID de los tipos de asociación predeterminados se enumeran en [este recurso](/api-reference/crm-associations-v4/guide#association-type-id-values), 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](/api-reference/crm-associations-v4/guide#retrieve-association-types). |
## 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ámetro | Descripción |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `properties` | Una 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. |
| `propertiesWithHistory` | Una 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. |
| `associations` | Una 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.](/api-reference/crm-associations-v4/guide) |
* 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](/api-reference/crm-properties-v3/guide#create-unique-identifier-properties), 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](/api-reference/crm-associations-v4/guide).
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](/api-reference/crm-properties-v3/guide#create-unique-identifier-properties) 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):
```json theme={null}
{
"properties": ["email", "lifecyclestage", "jobtitle"],
"inputs": [
{
"id": "1234567"
},
{
"id": "987456"
}
]
}
```
```json theme={null}
{
"propertiesWithHistory": ["lifecyclestage", "hs_lead_status"],
"inputs": [
{
"id": "1234567"
},
{
"id": "987456"
}
]
}
```
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:
```json theme={null}
{
"properties": ["email", "lifecyclestage", "jobtitle"],
"idProperty": "email",
"inputs": [
{
"id": "lgilmore@thedragonfly.com"
},
{
"id": "sstjames@thedragonfly.com"
}
]
}
```
```json theme={null}
{
"properties": ["email", "lifecyclestage", "jobtitle"],
"idProperty": "internalcustomerid",
"inputs": [
{
"id": "12345"
},
{
"id": "67891"
}
]
}
```
## 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:
```json theme={null}
{
"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](https://knowledge.hubspot.com/es/records/update-a-property-value-for-a-record), o se puede eliminar automáticamente mediante un [workflow](https://knowledge.hubspot.com/es/records/change-record-lifecycle-stages-in-bulk) 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:
```json theme={null}
{
"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](/api-reference/crm-properties-v3/guide#create-unique-identifier-properties). 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:
```json theme={null}
{
"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](/api-reference/crm-associations-v4/guide#association-type-id-values) 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.](/api-reference/crm-associations-v4/guide)
### 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](https://knowledge.hubspot.com/es/records/pin-an-activity-on-a-record) 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](/api-reference/overview). 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:
```json theme={null}
{
"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:
```json theme={null}
{
"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](https://knowledge.hubspot.com/es/records/restore-deleted-records).
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](/api-reference/crm-contacts-v3/guide).
## 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](https://knowledge.hubspot.com/es/records/add-multiple-email-addresses-to-a-contact) o se pueden añadir automáticamente tras una [combinación de contactos](https://knowledge.hubspot.com/es/records/merge-records#contact-merge-exceptions). 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](https://developers.hubspot.es/docs#limits_contacts).