> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Importar
> Importar o actualizar usuarios en OneSignal usando cargas CSV, REST API o entrada manual. Soporta correo electrónico, SMS, etiquetas y más para la incorporación o migración sin problemas de usuarios.
Importa o actualiza usuarios de forma masiva a través del panel de OneSignal usando un archivo CSV o entrada manual. Los casos de uso comunes incluyen migrar usuarios desde otra plataforma, actualizar detalles de usuarios y organizar usuarios con [Etiquetas](./add-user-data-tags) y [Segmentos](./segmentation).
También puedes actualizar o crear usuarios a través de la [REST API](/reference/create-user).
## Importación CSV
Usa un archivo CSV para importar o actualizar direcciones de correo electrónico, números de teléfono, IDs externos, [Etiquetas](./add-user-data-tags), idioma, zona horaria, país y más.
### Requisitos del CSV
Asegúrate de que tu archivo `.csv` cumpla con los siguientes requisitos:
* Codificación UTF-8 (sin BOM)
* Sin caracteres no imprimibles (sin caracteres especiales o no-ASCII)
* Encabezados de columna limpios y únicos
* Tamaño de archivo menor a 150MB (aproximadamente 2 millones de filas)
* Al menos un identificador de los siguientes:
* `external_id` — Recomendado. Identifica [Usuarios](./users) en todas las [Suscripciones](./subscriptions).
* `email` — Requerido para crear nuevas suscripciones de correo electrónico. Consulta [Validación de dirección de email](./email-address-validation) para más información.
* `phone_number` — Requerido para crear nuevas suscripciones de SMS.
* `subscription_id` — Solo recomendado para casos en los que ya rastreas [IDs de Suscripción](./subscriptions) de OneSignal en tu backend.
Solo se permite un identificador de cada tipo por fila. Para asociar múltiples correos electrónicos o números con el mismo usuario, usa filas separadas que compartan el mismo `external_id`.
* Incluye `external_id` para desduplicar usuarios. Asegúrate de que coincida con el ID usado en el método SDK `login` — de lo contrario, se restablecerá cuando el usuario abra la aplicación.
* Para cambiar el estado de suscripción, la fila debe incluir `email`, `phone_number` o `subscription_id`. Solo `external_id` no es suficiente.
* `subscription_id` no vincula ni fusiona Suscripciones. Usa `external_id` para agregar nuevos correos electrónicos o números de teléfono a un usuario existente.
### Columnas CSV disponibles
Ve [ID externo](./users#external-id) para más información.
Crea una [suscripción](./subscriptions) de Correo electrónico. Deduplicado si ya está presente.
Usa [formato E.164](https://en.wikipedia.org/wiki/E.164) como `+15555551234`. Crea una [suscripción](./subscriptions) de SMS.
Recomendado solo si ya rastreas [IDs de Suscripción](./subscriptions) de OneSignal en tu backend.
Establece el estado de suscripción. Requiere `email`, `phone_number` o `subscription_id` en la misma fila — no se puede usar solo con `external_id`.
`false` elimina el correo electrónico de las listas de supresión.
Ve [IANA TZ](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
Ve [ISO 3166-2](https://www.iso.org/obp/ui/).
Ve [ISO 639-1](./multi-language-messaging#supported-languages).
Hasta 1,000 etiquetas. Usa encabezados de columna como claves. Ve [Etiquetas](./add-user-data-tags).
#### Límites y restricciones de etiquetas
Los [límites de plan](https://onesignal.com/pricing) de etiquetas se aplican por usuario, no por aplicación. Por ejemplo, si tu plan permite 20 etiquetas por usuario y un usuario ya tiene 19, solo puedes agregar 1 más — aunque la aplicación pueda tener claves de etiqueta ilimitadas.
* Usa el flujo de trabajo de [Actualizaciones masivas de etiquetas](#bulk-tag-updates) para exportar usuarios, limpiar valores de etiquetas no deseados y volver a importar con la opción de eliminación habilitada.
* Evita los espacios en las claves de etiqueta — usa guiones bajos en su lugar.
**Claves de etiqueta reservadas y restringidas**
Las siguientes claves de etiqueta están reservadas y no deben usarse:
* "user"
* "subscription"
* "message"
* "template"
* "app"
* "org"
* "custom\_data"
* "dynamic\_content"
Si accidentalmente estableces una de estas como clave de etiqueta, elimínala a través de la [API de Actualización de Usuario](/reference/update-user).
**Sobrescrituras y eliminaciones de etiquetas**
Durante una importación de CSV:
* Las etiquetas incluidas en tu CSV se sobrescriben con el valor proporcionado.
* Las etiquetas no incluidas en tu CSV permanecen sin cambios en el registro del usuario.
Si una etiqueta sigue presente después de la importación, verifica que:
* La columna de encabezado contiene la clave de etiqueta.
* La fila no contiene ningún valor.
* Seleccionaste la opción "Eliminar etiquetas con valores en blanco" en la [pantalla de Revisión](#review-and-confirm).
**Otras fuentes de etiquetas que se agregan**
Si las etiquetas eliminadas reaparecen después de la importación, puede que una integración las esté escribiendo automáticamente. Las fuentes comunes incluyen:
* Segment
* HubSpot
* Journeys
* Métodos de etiquetado del SDK
* APIs personalizadas o pipelines ETL
Revisa los mapeos de integración y los desencadenadores de eventos para asegurarte de que no estén sobrescribiendo tus cambios de CSV.
#### Importar etiquetas desde una sola columna
En lugar de usar encabezados de columna separados para cada clave de etiqueta, puedes configurar un solo encabezado `tags`, con cada fila de usuario conteniendo un mapa JSON de todos los pares clave-valor entre comillas. Esto es especialmente útil si exportaste previamente un CSV con etiquetas y deseas reimportarlo sin reformatear.
Ejemplo de encabezado:
```csv theme={null}
external_id,email,tags
```
Ejemplo de filas:
Las etiquetas deben estar formateadas como un objeto JSON encerrado entre comillas.
```csv theme={null}
userA,example@email.com,"{""level"":""30"",""Color"":""teal""}"
```
Cuando se importa, OneSignal convierte automáticamente cada par clave-valor en etiquetas distintas para el registro de suscripción.
**Ejemplo: Eliminación masiva de etiquetas**
Para eliminar etiquetas de forma masiva, exporta tus datos actuales, borra los valores de etiqueta y vuelve a importar el CSV con la opción de eliminación habilitada.
* Navega a **Audiencia > Suscripciones** en el panel de OneSignal. Habilita solo las columnas **ID Externo**, **ID de Suscripción** y **Etiquetas** (y opcionalmente **Correo electrónico** o **Número de teléfono**).
* Haz clic en **Exportar** para exportar el CSV.
Abre el CSV exportado en un editor de texto y establece los valores de cada etiqueta que deseas eliminar como una cadena vacía.
Por ejemplo, una fila con valores de etiqueta antes de editar:
```text Fila antes de editar theme={null}
userA,example@email.com,"{""level"":""30"",""color"":""teal""}"
```
La misma fila después de borrar los valores de etiqueta:
```text Fila después de borrar los valores de etiqueta theme={null}
userA,example@email.com,"{""level"":"""",""color"":""""}"
```
Esto resultará en la eliminación de las etiquetas `level` y `color` del usuario.
* Toma el CSV editado e impórtalo.
* En la pantalla de [Revisión](#revisar-y-confirmar), selecciona **Sí** para **Eliminar etiquetas con valores en blanco**. OneSignal elimina las etiquetas con valores en blanco durante la importación.
Para eliminar solo etiquetas específicas, borra los valores de esas etiquetas y deja los demás sin cambios. Solo los valores en blanco se eliminan cuando la opción de eliminación está habilitada.
¿Necesitas ayuda?
* Prueba la sección [Usa IA para revisar tu CSV antes de importar](#use-ai-to-check-your-csv-before-import) anterior.
* Contacta a `support@onesignal.com` y comparte el archivo CSV que cargaste junto con una captura de pantalla del correo electrónico de confirmación. ¡Estamos felices de ayudarte!
#### Validación de dirección de email
La validación de dirección de email detecta problemas comunes en las direcciones de email antes de que lleguen a tu audiencia. Marca errores tipográficos, dominios no válidos, direcciones basadas en roles y servicios de email desechables que podrían aumentar tu tasa de rebote o dañar tu reputación como remitente.
Valida las direcciones de email durante la importación de CSV y en masa para reducir rebotes y proteger tu reputación como remitente.
#### Usa IA para revisar tu CSV antes de importar
Si tienes errores o preguntas sobre el formato de tu CSV, puedes describir tu problema de CSV a una herramienta de IA (como Claude, ChatGPT o similar) para limpiar o reconstruir automáticamente tu archivo antes de importar nuevamente.
Siempre prueba con una muestra pequeña (5-10 filas) antes de importar miles de registros.
```text Ejemplo de solicitud de IA para eliminar etiquetas no deseadas theme={null}
Quiero eliminar todas las etiquetas excepto "user_name" de este CSV.
Por favor:
1. Mantén solo la columna de etiqueta "user_name".
2. Elimina todas las demás columnas de etiquetas.
3. Formatea el CSV para que coincida con los requisitos de importación de OneSignal en este documento:
https://documentation.onesignal.com/docs/en/import
Aquí está mi CSV:
[PEGAR CSV]
```
```text Ejemplo de solicitud de IA para corregir el formato de múltiples columnas de etiquetas theme={null}
Tengo múltiples columnas de etiquetas como tag_first_name, tag_last_name y tag_city.
Según la documentación de importación de OneSignal, cada etiqueta debe:
- Usar el prefijo tag_
- Contener solo caracteres alfanuméricos y guiones bajos
- Seguir los tipos de datos admitidos
¿Podrías revisar mi CSV, identificar qué está formateado incorrectamente y devolver una versión corregida que cumpla con estos requisitos?
Enlace a la documentación:
https://documentation.onesignal.com/docs/en/import
```
```text Ejemplo de solicitud de IA para identificar formato faltante o inválido theme={null}
OneSignal rechazó mi CSV durante la importación.
Por favor:
1. Valida mi estructura CSV.
2. Identifica cualquier problema de formato (encabezados, columnas de ID, formatos de etiquetas, comillas).
3. Devuelve una versión corregida que siga los requisitos en este documento:
https://documentation.onesignal.com/docs/en/import#prepare-your-csv
Aquí está el archivo:
[PEGAR CSV]
```
```text Ejemplo de solicitud de IA para corregir formatos de número de teléfono inválidos (E.164) theme={null}
Mi importación está fallando porque los números de teléfono no están en formato E.164.
Por favor:
1. Convierte todos los números de teléfono al formato E.164.
2. Mantén todos los demás campos sin cambios.
3. Asegúrate de que el CSV coincida con la estructura requerida de OneSignal:
https://documentation.onesignal.com/docs/en/import
Ejemplo de formato actual: (555) 555-1234
Aquí está mi CSV:
[PEGAR CSV]
```
```text Ejemplo de solicitud de IA para migrar desde otra plataforma theme={null}
Estoy migrando de [Nombre de la Plataforma] a OneSignal.
¿Podrías transformar este CSV para que coincida con el formato de importación de OneSignal?
Incluye:
- `external_id`
- Cualquier etiqueta convertida con el prefijo `tag_` (si se desea)
- Números de teléfono en formato E.164 (si es aplicable)
Documento de referencia:
https://documentation.onesignal.com/docs/en/import
Aquí está mi CSV:
[PEGAR CSV]
```
### Pasos de importación
Navega a **Audiencia > Importar** y haz clic en **Lanzar Importador CSV**.
Selecciona tu archivo CSV preparado.
OneSignal mapea automáticamente los encabezados de tu CSV a las propiedades conocidas. Revisa los mapeos antes de confirmar — usa `external_id`, `email`, `phone_number` y/o `subscription_id` como **identificadores**, no como etiquetas.
Para agregar un nuevo correo electrónico o número de teléfono a un usuario existente, **debes usar** `external_id`. **No** uses `subscription_id` — no vinculará ni fusionará suscripciones.
Si OneSignal detecta problemas de formato, corrige el CSV y vuelve a subir (recomendado) o desmarca la columna afectada para omitir su importación.
La pantalla de Revisión te permite:
* **Crear automáticamente un segmento** — Agrega una etiqueta a cada usuario importado y crea un [segmento](./segmentation) coincidente. Ten en cuenta los [límites de tu plan](https://onesignal.com/pricing).
* **Eliminar etiquetas con valores en blanco** — Elimina cualquier etiqueta con valor en blanco en el CSV. Útil para limpiar etiquetas no deseadas y mantenerse dentro de los límites del plan.
* **Configurar validación de dirección de email** — Configura los ajustes de [validación de dirección de email](./email-address-validation) para reducir rebotes y proteger tu reputación como remitente.
Por ejemplo, con este CSV:
```csv theme={null}
external_id,tag1,tag2
UserA,,"tag2value"
UserB,"tag1value",
```
Con "Eliminar etiquetas con valores en blanco" habilitado, `tag1` se elimina de UserA y `tag2` se elimina de UserB.
Haz clic en **Confirmar e Importar**. Una pantalla de estado muestra el progreso.
La importación ha comenzado. Recibirás un correo electrónico de confirmación de `contact@onesignal.com` cuando finalice.
### Confirmación por correo electrónico
Una vez que el import termine, recibirás un correo electrónico de confirmación de `contact@onesignal.com` con los siguientes datos. Un único [Usuario](./users) puede tener múltiples [Suscripciones](./subscriptions) (ej. email + push), por lo que los conteos de suscripción pueden ser mayores que el número de filas.
**Registro(s) de suscripción agregados** — Nuevas [Suscripciones](./subscriptions) de correo electrónico o SMS creadas. `0` significa que no se encontraron identificadores únicos de `email` o `phone_number`.
**Registro(s) de suscripción modificados** — [Suscripciones](./subscriptions) con datos modificados (etiquetas, propiedades, etc.). Ejemplo: 10 IDs Externos vinculados a 20 suscripciones cada uno = `200` registros modificados.
**Actualizaciones de suscripción omitidas** — [Suscripciones](./subscriptions) omitidas por la razón indicada. Si la razón es "sobre el límite de etiquetas de tu aplicación", elimina etiquetas y vuelve a importar o actualiza tu plan.
**No importado** — Filas que no fueron actualizadas o importadas. Causas comunes: el `external_id` no coincide con ninguna suscripción existente, o el `email`/`phone_number` ya existe sin nuevos datos para configurar.
**Nuevo segmento creado** — El nombre del segmento si seleccionaste esa opción.
En el ejemplo anterior:
* Se crearon `100` suscripciones a partir de direcciones de correo electrónico o números de teléfono únicos que no existían en la app.
* Se actualizaron `37,814` suscripciones (no es el conteo de [Usuarios](./users) — cada usuario puede tener múltiples suscripciones).
* `621,852` filas no fueron importadas porque sus IDs Externos no correspondían a usuarios existentes, o los correos/números de teléfono ya existían sin datos nuevos.
[Segmentos](./segmentation) solo cuentan [Suscripciones](./subscriptions) **suscritas**. Las suscripciones no suscritas son actualizadas por el import pero no se reflejan en los conteos de segmentos. Las mejoras en la segmentación están en progreso.
## Entrada manual
Puedes agregar manualmente las suscripciones de correo electrónico y número de teléfono del usuario a través del panel de OneSignal navegando a **Audiencia > Usuarios > Actualizar/Importar usuarios > Agregar usuarios manualmente**.
En la pantalla **Nuevo usuario**, incluye los datos que desees y selecciona **Crear usuario**.
***
## Preguntas frecuentes
### ¿Cuánto tiempo tarda una importación CSV?
La duración depende del tamaño del archivo. La mayoría de las importaciones se completan en unos minutos. Recibirás un correo electrónico de `contact@onesignal.com` cuando finalice la importación — agrega esa dirección a tus contactos para asegurarte de recibirlo.
### ¿Puedo deshacer una importación CSV?
No. No hay función de deshacer integrada para las importaciones CSV. Si necesitas revertir cambios, prepara un nuevo CSV con los valores correctos y vuelve a importarlo. Para eliminaciones de etiquetas, usa el flujo de trabajo de [Eliminación masiva de etiquetas](#ejemplo-eliminación-masiva-de-etiquetas).
### ¿Por qué los conteos de mi segmento no coinciden con las filas de mi CSV?
Los [Segmentos](./segmentation) solo cuentan las [Suscripciones](./subscriptions) **suscritas**. Las suscripciones no suscritas son actualizadas por la importación pero no se reflejan en los conteos de segmentos.
### ¿Por qué mi importación mostró "no importado" para algunas filas?
Las filas se omiten cuando el `external_id` no coincide con ninguna suscripción existente en la aplicación, o cuando el `email` o `phone_number` ya existe sin nuevos datos para configurar. Consulta la sección de [Confirmación por correo electrónico](#confirmación-por-correo-electrónico-y-solución-de-problemas) para obtener detalles sobre cada estado.
### ¿Por qué las etiquetas eliminadas siguen volviendo?
Una integración o llamada del SDK puede estar re-agregando las etiquetas después de tu importación. Las fuentes comunes incluyen Segment, HubSpot, Journeys, métodos de etiquetado del SDK y APIs personalizadas. Revisa tus [mapeos de integración](#otras-fuentes-de-etiquetas-que-se-agregan) y los activadores de eventos.
***