Sujetos e identificadores
Crear sujetos, añadir identificadores y fusionar anónimo → identificado.
Una persona a menudo empieza siendo anónima — un cookie_id antes de registrarse — y se identifica más tarde, al iniciar sesión con un email. Estos endpoints te permiten crear esa identidad desde el principio y reconciliar ambas una vez que son la misma persona, de forma que el consentimiento que ya dio se mantenga en lugar de reiniciarse.
Son solo `sk_`. En el navegador, POST /v1/consent ya crea el sujeto si le pasas identificadores.
Tipos de identificador
A un sujeto se llega por un identificador, escrito en una URL como <prefijo>:<valor> o en un cuerpo como { "type", "value" } (valor de hasta 320 caracteres).
| Tipo | Referencia | Uso habitual | Con una clave `pk_` |
|---|---|---|---|
EMAIL | email:ana@example.com | El correo electrónico de una persona | Requiere token de identidad |
PHONE | phone:+34600111222 | Un número de teléfono | Requiere token de identidad |
EXTERNAL_ID | external_id:u_9241 | El id de usuario de tu propio sistema (recomendado) | Requiere token de identidad |
CUSTOM | custom:… | Cualquier otro identificador de tu sistema | Requiere token de identidad |
DEVICE_ID | dev_… (o device_id:…) | Id anónimo de instalación o navegador que generan el CMP y los SDK | Anónimo: sin token |
COOKIE_ID | cookie_id:ck_a1b2 | Una cookie propia para visitantes anónimos | Anónimo: sin token |
Con una clave `pk_`, solo los dos tipos anónimos funcionan por sí solos. Cualquier tipo identificado (EMAIL, PHONE, EXTERNAL_ID, CUSTOM) debe coincidir con el token X-Tc-Identity que firma tu backend para el usuario con sesión iniciada; consulta Guía: identificar a usuarios con sesión iniciada. Esto cubre al sujeto entero: llegar a un sujeto que tenga uno de esos identificadores por su id interno, por un id de dispositivo vinculado o por una cadena de fusiones también exige el token. Las claves `sk_` nunca se comprueban contra identidad.
Las búsquedas no distinguen mayúsculas de minúsculas e ignoran los espacios al principio y al final, para todos los tipos (Ana@Example.com y ana@example.com son el mismo sujeto). No se normaliza nada más: +34 600 111 222 y +34600111222 son teléfonos distintos, así que envíalos siempre en un mismo formato (E.164 para teléfonos).
Todo sujeto necesita un identificador
Un sujeto no puede existir sin al menos un identificador: POST /v1/subjects y cualquier cuerpo { "identifiers": [...] } exigen uno. Los registros que no pertenecen a nadie en concreto —un lote «atestiguado por el responsable» sin persona asociada— no se admiten hoy. Si solo conoces a un contacto por el id de una fila de tu propio sistema, envíalo como external_id.
Sin listas ni segmentos, por diseño
Un sujeto guarda identificadores, estado de consentimiento y valores de preferencias, y nada más: no tiene pertenencia a listas, segmentos ni etiquetas. Mantén la pertenencia a audiencias en tu propio sistema (tu ESP, tu CRM o tu base de datos) y usa Croombit para el estado de consentimiento que decide si puedes contactar a la persona: modela «¿podemos escribirle sobre X?» como un propósito o una preferencia.
Crear
POST /v1/subjects
{ "identifiers": [{ "type": "EMAIL", "value": "user@example.com" }] }
→ { "subjectId": "cmtr…", "created": true }Fusión (anónimo → identificado)
Cuando un visitante anónimo (identificado por cookie_id o device_id) inicia sesión, fusiona su identidad con la identificada:
POST /v1/subjects/merge
{ "source": "cookie_id:ck_abc", "target": "email:user@example.com", "reason": "login" }
→ { "sourceSubjectId", "targetSubjectId", "movedRecords", "movedIdentifiers", "outcome" }Los identificadores y las filas de la bóveda del sujeto de origen se reasignan al de destino; el de origen queda con un puntero mergedIntoId. Las lecturas posteriores por cualquiera de sus identificadores resuelven al sujeto de destino. Se emite subject.merged solo cuando outcome es "merged" (no con device_relinked).
La misma regla de dispositivos compartidos se aplica cuando envías un id de dispositivo junto con un identificador de cuenta (POST /v1/subjects, o un cuerpo de consentimiento / preferencias con identifiers): se buscan primero los identificadores de cuenta, y un dispositivo que pertenece a otra cuenta con sesión iniciada nunca arrastra a la cuenta nueva a ese sujeto. Con clave sk_ el dispositivo pasa a la cuenta que inicia sesión; con pk_ se queda donde está, porque un navegador puede enviar cualquier id de dispositivo.