API REST — referencia de objetos

Referencia de todos los objetos que expone la API REST de Personyze. Cada sección de abajo cubre un objeto: su finalidad, los métodos HTTP admitidos, las columnas (con notas de tipo e indexación) y ejemplos de curl listos para copiar y pegar.

Requisitos previos — léalos primero si aún no lo ha hecho:

• Descripción general e inicio rápido de la API REST — forma de las solicitudes, métodos HTTP, códigos de respuesta
• Autenticación — cómo obtener su clave de API, cómo enviarla, configuraciones con varias cuentas
• Parámetros de ruta — la sintaxis where/columns/order_by/limit que recorre todos los ejemplos de abajo

Índice de objetos

Haga clic en un objeto para ir a su sección. Cada sección tiene su propia URL de ancla — puede enlazar directamente a la referencia de cualquier objeto.

Contenido CRUD (lectura/escritura)

Contienen sus campañas, su audiencia, su catálogo y su configuración. CRUD completo para External API user y superiores.

Interacciones / eventos (sobre todo escritura)

Registros de solo inserción de las interacciones de los visitantes. Los usan sobre todo los SDK y las integraciones de back-end.

Informes / archivo (solo lectura)

Ayudas para el tracker / SDK

Los usan el tracker de JS, los SDK nativos y las integraciones para arrancar por sí mismos. Normalmente no los llaman directamente quienes consumen la API REST.

users

Perfiles de clientes. Cada fila es un visitante o cliente. Los nombres de columna son dinámicos — además de las columnas de gestión documentadas, puede guardar las claves y valores personalizados que necesite su cuenta.

Columnas de identificación / gestión

Campos de perfil comunes (personalizados)

first_name, middle_name, last_name, sex, birthday, timezone, current_city, current_state, current_country, religion, political, interests, relationship_status, education_year, más custom_t_1…custom_t_6 (texto), custom_i_1…custom_i_4 (entero), custom_f_1…custom_f_2 (decimal), custom_d_1, custom_d_2 (fecha) — y cualquier campo adicional que haya configurado en su cuenta.

Ejemplos

# Lookup by your external id
curl 'https://api:KEY@app.personyze.com/rest/users/where/internal_id=42'

# Recent active visitors (last 7 days)
curl 'https://api:KEY@app.personyze.com/rest/users
        /where/last_session_time>1730000000
        /columns/user_id,internal_id,email,first_name,last_session_time
        /order_by_desc/last_session_time
        /limit/1000'

# Create
curl -X POST 'https://api:KEY@app.personyze.com/rest/users' \
     -H 'Content-Type: application/json' \
     -d '{"internal_id":"acct-987","email":"alice@example.com","first_name":"Alice","custom_field_x":"vip"}'
# → 5712334  (new user_id)

# Update
curl -X PUT 'https://api:KEY@app.personyze.com/rest/users/where/internal_id=acct-987' \
     -H 'Content-Type: application/json' \
     -d '{"first_name":"Alicia"}'
# → 1  (rows affected)

Columnas indexadas / límites de recorrido

GET /rest/users sin una cláusula where requiere order_by sobre una columna indexada — user_id, last_session_time, data_last_modified, fb_id, email, o internal_id. De lo contrario: 400 Cannot do this operation on whole table.

Limitación de solicitudes

POST /rest/users se serializa por cuenta de Personyze: como máximo una inserción en curso a la vez. Las solicitudes que esperan más de 1 segundo se rechazan con 400 Too many simultaneous requests — reintente con espera exponencial.

user_lists

Listas de usuarios con nombre (p. ej. «VIPs», «Suscritos a la newsletter»). Una fila por lista. La pertenencia está en un objeto aparte — consulte user_list_users.

Columnas

Ejemplos

# All lists
curl 'https://api:KEY@app.personyze.com/rest/user_lists'

# Create
curl -X POST 'https://api:KEY@app.personyze.com/rest/user_lists' \
     -H 'Content-Type: application/json' \
     -d '{"name":"VIPs"}'
# → 17

# Rename
curl -X PUT 'https://api:KEY@app.personyze.com/rest/user_lists/17' \
     -H 'Content-Type: application/json' \
     -d '{"name":"VIP customers"}'
# → 1

# Delete (also clears all memberships in user_list_users via FK cascade)
curl -X DELETE 'https://api:KEY@app.personyze.com/rest/user_lists/17'
# → 1

user_list_users

Pertenencia: qué usuarios pertenecen a qué user_lists. Una fila por cada par (user_list_id, user_id) de valores.

POST acepta un user_idexistente, o una clave de búsqueda (user_internal_id, user_email) — la API la resuelve en un user_id, y crea una fila users provisional si hace falta.

Columnas

Campos adicionales del cuerpo POST (se resuelven en user_id en el servidor y después se descartan)

Ejemplos

# Members of list 17
curl 'https://api:KEY@app.personyze.com/rest/user_list_users/where/user_list_id=17/limit/1000'

# Add by user_id
curl -X POST 'https://api:KEY@app.personyze.com/rest/user_list_users' \
     -H 'Content-Type: application/json' \
     -d '{"user_list_id":17,"user_id":5712334}' 

# Add by external id (auto-creates a users row if needed)
curl -X POST 'https://api:KEY@app.personyze.com/rest/user_list_users' \
     -H 'Content-Type: application/json' \
     -d '{"user_list_id":17,"user_internal_id":"acct-987"}' 

# Add by email
curl -X POST 'https://api:KEY@app.personyze.com/rest/user_list_users' \
     -H 'Content-Type: application/json' \
     -d '{"user_list_id":17,"user_email":"alice@example.com"}' 

# Remove
curl -X DELETE 'https://api:KEY@app.personyze.com/rest/user_list_users
        /where/user_list_id=17&user_id=5712334'

actions

Acciones de personalización — lo que hacen sus campañas: mostrar HTML, mostrar un popup, enviar un email, enviar una notificación push, etc. Por ahora, solo lectura por REST (se crean y editan desde la GUI).

Columnas

Ejemplos

# All production actions
curl 'https://api:KEY@app.personyze.com/rest/actions
        /where/version_tag=production
        /columns/id,name,type_id,placeholders'

# One action's full content
curl 'https://api:KEY@app.personyze.com/rest/actions/where/id=42
        /columns/id,name,content_type,content_param,content_begin,content_end'

conditions

Condiciones de audiencia — el cuándo de las campañas. Solo lectura por REST.

Columnas

Ejemplos

# All tracker/offline conditions
curl 'https://api:KEY@app.personyze.com/rest/conditions/limit/1000'

placeholders

Contenedores de tipo placeholder — huecos del DOM donde las acciones muestran contenido. Gestione el catálogo de placeholders definidos para su sitio.

Columnas

Ejemplos

# All placeholders
curl 'https://api:KEY@app.personyze.com/rest/placeholders'

# One
curl 'https://api:KEY@app.personyze.com/rest/placeholders/14'

# Create
curl -X POST 'https://api:KEY@app.personyze.com/rest/placeholders' \
     -H 'Content-Type: application/json' \
     -d '{"name":"Hero banner","html_id":"#hero","units_count_max":1}'
# → 88

# Update
curl -X PUT 'https://api:KEY@app.personyze.com/rest/placeholders/88' \
     -H 'Content-Type: application/json' \
     -d '{"units_count_max":3}'
# → 1

# Delete
curl -X DELETE 'https://api:KEY@app.personyze.com/rest/placeholders/88'
# → 1

containers_grab_variable

Contenedores «grab variable» — llevan valores del DOM/JS de la página del visitante a su perfil. Cada contenedor dice «vigila esta variable / este elemento del DOM; cuando aparezca, guárdalo como campo del perfil.»

Columnas

Ejemplos

# All grab-variable containers
curl 'https://api:KEY@app.personyze.com/rest/containers_grab_variable'

# Create
curl -X POST 'https://api:KEY@app.personyze.com/rest/containers_grab_variable' \
     -H 'Content-Type: application/json' \
     -d '{"name":"Cart total",
          "variable_path":"window.dataLayer[0].cart.total",
          "mask":"^([0-9.]+)$",
          "watch_variable":1}'
# → 153

# Update
curl -X PUT 'https://api:KEY@app.personyze.com/rest/containers_grab_variable/153' \
     -H 'Content-Type: application/json' \
     -d '{"is_active":0}' 

# Delete
curl -X DELETE 'https://api:KEY@app.personyze.com/rest/containers_grab_variable/153'

products

Catálogo de productos. Cada fila es un SKU. Los nombres de columna son dinámicos — además de las columnas de gestión documentadas, puede guardar los campos personalizados que necesite su catálogo.

Columnas de identificación / gestión

Campos de producto comunes (personalizados)

title, description_short, description_long, price, sale_price, image_big_url, image_medium_url, image_small_url, cart_url, brand, manufacturer, category, inventory, expiration_date, size, color, rank, is_new, age_from, age_to, available_location, not_available_location, etc. El conjunto real de campos depende de la configuración de su cuenta.

Entradas renombradas (en POST / PUT)

Ejemplos

# In-stock products in a category
curl 'https://api:KEY@app.personyze.com/rest/products
        /where/category=tools&is_in_stock=yes
        /columns/id,internal_id,title,price,inventory
        /order_by/title
        /limit/100'

# Lookup by internal_id
curl 'https://api:KEY@app.personyze.com/rest/products/where/internal_id=SKU-1234'

# Insert (or "patch" — duplicate internal_id will UPDATE rather than fail)
curl -X POST 'https://api:KEY@app.personyze.com/rest/products' \
     -H 'Content-Type: application/json' \
     -d '{"internal_id":"SKU-1234",
          "title":"Cordless Drill",
          "price":129.99,
          "is_in_stock":"yes",
          "image_1":"https://cdn.example.com/big.jpg"}'
# → 51234

# Update by internal_id
curl -X PUT 'https://api:KEY@app.personyze.com/rest/products/where/internal_id=SKU-1234' \
     -H 'Content-Type: application/json' \
     -d '{"price":119.99,"is_in_stock":"no"}' 

# Delete
curl -X DELETE 'https://api:KEY@app.personyze.com/rest/products/where/internal_id=SKU-1234'

articles

Catálogo de artículos (entradas de blog, noticias, entradas de base de conocimiento). La misma forma que products pero para contenido editorial.

Columnas de identificación / gestión

Campos de artículo comunes (personalizados)

title, description_short, description_long, image_big_url, image_medium_url, image_small_url, author, publish_date, category, tags, rank, etc. La lista real depende de la configuración other_columns_info de su sitio.

Entradas renombradas

Ejemplos

# Recent published articles
curl 'https://api:KEY@app.personyze.com/rest/articles
        /where/is_published=yes
        /columns/id,internal_id,title,author,publish_date
        /order_by_desc/publish_date
        /limit/100'

# Lookup by internal_id
curl 'https://api:KEY@app.personyze.com/rest/articles/where/internal_id=how-to-personalize'

# Insert
curl -X POST 'https://api:KEY@app.personyze.com/rest/articles' \
     -H 'Content-Type: application/json' \
     -d '{"internal_id":"how-to-personalize",
          "title":"How to personalize your site",
          "author":"Alice",
          "is_published":"yes",
          "image_1":"https://cdn.example.com/big.jpg"}' 

# Update
curl -X PUT 'https://api:KEY@app.personyze.com/rest/articles/where/internal_id=how-to-personalize' \
     -H 'Content-Type: application/json' \
     -d '{"is_published":"no"}' 

# Delete
curl -X DELETE 'https://api:KEY@app.personyze.com/rest/articles/where/internal_id=how-to-personalize'

products_interactions

Registro de interacciones con productos: vistas, añadidos al carrito, compras, «favorito», «entregado». Sobre todo de inserción. Respaldado por una tabla de archivo.

Columnas

Inserción: identificar al usuario

POST acepta uno cualquiera de estos para identificar al usuario:

Ejemplos

# All purchases in a window, paged
curl 'https://api:KEY@app.personyze.com/rest/products_interactions
        /where/status=goal&time>1730000000
        /order_by_desc/time
        /limit/1000'

# A specific user's history with a product
curl 'https://api:KEY@app.personyze.com/rest/products_interactions
        /where/product_internal_id=SKU-1234
        /columns/user_id,status,quantity,amount,transaction_time'

# Log a purchase
curl -X POST 'https://api:KEY@app.personyze.com/rest/products_interactions' \
     -H 'Content-Type: application/json' \
     -d '{"user_internal_id":"acct-987",
          "product_internal_id":"SKU-1234",
          "quantity":2,
          "status":"goal",
          "transaction_time":1734000000,
          "amount":259.98}' 

# Delete by composite key
curl -X DELETE 'https://api:KEY@app.personyze.com/rest/products_interactions
        /where/user_id=5712334&product_internal_id=SKU-1234&status=viewed'

Columnas indexadas

user_id, [product_internal_id, user_id, transaction_time], status, time. Las consultas sin una cláusula where sobre una de ellas (o un order_by sobre ellas) se rechazan como recorridos de tabla completa.

events

Registro de eventos genérico — una fila por cada evento registrado por el tracker de JS, el SDK o el endpoint do . Por ahora, solo lectura por REST.

Columnas

Ejemplos

# Recent events for a user
curl 'https://api:KEY@app.personyze.com/rest/events
        /where/user_id=5712334
        /order_by_desc/time
        /limit/100'

# Events from a specific container in a window
curl 'https://api:KEY@app.personyze.com/rest/events
        /where/container_id=1234&time>1730000000&time<1731000000
        /columns/id,user_id,time,value
        /order_by_desc/time
        /limit/1000'

forms

Registro de envíos de formularios. Una fila por cada envío de formulario registrado por el tracker. Por ahora, solo lectura por REST.

Columnas

El identificador de cliente data El JSON se expande automáticamente en claves de primer nivel al leer — pida los campos personalizados concretos por su nombre.

Ejemplos

# Submissions for a user
curl 'https://api:KEY@app.personyze.com/rest/forms
        /where/user_id=5712334
        /order_by_desc/time
        /limit/100'

# Submissions tied to a specific action
curl 'https://api:KEY@app.personyze.com/rest/forms
        /where/action_id=42&time>1730000000
        /columns/user_id,time,email,name,message
        /limit/1000'

Las columnas indexadas incluyen user_id, action_id, y time. Las consultas deben filtrar por una de ellas.

do

Distribuidor de comandos sin respuesta: envíe una sola actualización del perfil de usuario o un evento de interacción sin hablar el protocolo del tracker. El cuerpo es un array de comandos; cada uno se procesa por separado.

Forma de la solicitud

[
    [<key-type>, <key-value>, <command>, <arg1>, <arg2>, ...],
    [<key-type>, <key-value>, <command>, <arg1>, <arg2>, ...],
    ...
]

• <key-type>: "user_id", "internal_id", o "email". Opcional — omítalo en los comandos que no se dirigen a un usuario.
• <key-value>: el identificador correspondiente.
• <command>: una cadena (sin distinguir mayúsculas de minúsculas). Consulte la lista de abajo.
• <arg…>: argumentos posicionales propios de cada comando.

Un POST correcto no devuelve nada; los fallos lanzan un error (todo el lote se interrumpe en el primer error).

Comandos

Perfil de usuario

["internal_id", "acct-987", "User profile", "first_name", "Alice", "custom_t_1", "VIP"]

Después del nombre del comando, los argumentos alternan field, value, field, value, …

Interacciones con productos

["internal_id", "acct-987", "Product viewed",          "SKU-1234"]
["internal_id", "acct-987", "Product added to cart",   "SKU-1234", "quantity", 2]
["internal_id", "acct-987", "Product liked",           "SKU-1234"]
["internal_id", "acct-987", "Product purchased",       "SKU-1234", "quantity", 2, "amount", 259.98]
["internal_id", "acct-987", "Product removed from cart","SKU-1234"]
["internal_id", "acct-987", "Product unliked",         "SKU-1234"]

Después del SKU, pares clave-valor opcionales: "quantity", "amount", "action_id", "transaction_time".

Interacciones con artículos

["email", "alice@example.com", "Article viewed",   "how-to-personalize"]
["email", "alice@example.com", "Article liked",    "how-to-personalize"]
["email", "alice@example.com", "Article commented","how-to-personalize"]
["email", "alice@example.com", "Article unliked", "how-to-personalize"]
["email", "alice@example.com", "Article goal",     "how-to-personalize"]

Ejemplos

# Tag a user as VIP
curl -X POST 'https://api:KEY@app.personyze.com/rest/do' \
     -H 'Content-Type: application/json' \
     -d '[["internal_id","acct-987","User profile","custom_t_1","VIP","first_name","Alice"]]' 

# Log a purchase + a profile update in one round-trip
curl -X POST 'https://api:KEY@app.personyze.com/rest/do' \
     -H 'Content-Type: application/json' \
     -d '[
       ["email","alice@example.com","Product purchased","SKU-1234","quantity",2,"amount",259.98],
       ["email","alice@example.com","User profile","customer_segment","loyal"]
     ]' 

sessions_archive

Una fila por sesión de visitante (un periodo continuo de actividad). Respaldado por la tabla de archivo de larga duración — mucho más ancha que events, con metadatos de ubicación, dispositivo, pantalla y navegador.

Identificación / gestión

Geo / idioma / dispositivo

Contadores de interacción

URL de entrada y referente

UTM / campaña publicitaria

ad_campaign, ad_source, ad_medium, ad_term, ad_content — los parámetros UTM estándar tal como se capturan al llegar.

Ejemplos

# Sessions for a user, most recent first
curl 'https://api:KEY@app.personyze.com/rest/sessions_archive
        /where/user_id=5712334
        /columns/first_visit_id,session_start_time,total_visits,country_code,city
        /order_by_desc/session_start_time
        /limit/100'

# Single session by primary key
curl 'https://api:KEY@app.personyze.com/rest/sessions_archive
        /where/first_visit_id=900000000123
        /columns/user_id,session_start_time,total_visits,total_goal_value'

Columnas indexadas: first_visit_id, user_id, además de varias más. Las consultas deben filtrar por una columna indexada o la solicitud se rechaza como recorrido de tabla completa.

user_interests

Intereses, categorías, etiquetas y etiquetas de familia/cruzadas/upsell por usuario, deducidos por el proceso del tracker. Una fila por (user_id, value, class, time). Solo lectura.

Columnas

Columnas indexadas: user_id, time. Las consultas deben filtrar por una columna indexada.

Ejemplos

# All interests for one user, strongest first
curl 'https://api:KEY@app.personyze.com/rest/user_interests
        /where/user_id=5712334
        /columns/value,class,rank,n_times,time
        /order_by_desc/rank
        /limit/100'

# Only categories, recently updated
curl 'https://api:KEY@app.personyze.com/rest/user_interests
        /where/user_id=5712334&class=category
        /order_by_desc/time
        /limit/50'

products_stats_*

Contadores de interacción agregados por producto que mantiene el proceso de resúmenes fuera de línea. Se exponen seis periodos móviles en rutas separadas — elija el que corresponda a su horizonte de informes. Todos comparten la misma forma de columnas e índices; solo cambia el periodo.

Endpoints

Identificación

Contadores por producto (número de interacciones con este producto dentro del periodo)

Estadísticas de distribución de todo el catálogo

El mismo valor en todas las filas — describe todo el catálogo dentro de este periodo. Para cada métrica M ∈ {viewed, delivered, extra, favorite, goal}:

Los 3 últimos usuarios con objetivo (los compradores más recientes de este producto)

Columnas indexadas

internal_id, n_viewed, n_delivered, n_extra, n_favorite, n_goal, last_goal_user_id_0, last_goal_user_id_1, last_goal_user_id_2. Las consultas deben filtrar por (u ordenar con order_by) una de ellas.

Ejemplos

# Top 50 most-viewed products this week
curl 'https://api:KEY@app.personyze.com/rest/products_stats_week
        /where/n_viewed>0
        /columns/internal_id,n_viewed,n_delivered,n_extra,n_goal,percentile_viewed
        /order_by_desc/n_viewed
        /limit/50'

# Lookup one product's lifetime stats
curl 'https://api:KEY@app.personyze.com/rest/products_stats_all
        /where/internal_id=SKU-12345'

# What a specific user purchased recently (matches against last 3 goal users)
curl 'https://api:KEY@app.personyze.com/rest/products_stats_recent
        /where/last_goal_user_id_0=5712334
        /columns/internal_id,n_goal,last_goal_user_time_0'

summary_actions

KPI diarios agregados por acción — una fila por (day, action_id) para las acciones vinculadas a una campaña concreta (condition_id). Solo lectura.

Identificación

Exposición de la acción

Atribución de productos (cuando esta acción recomendó productos)

Atribución de artículos

La misma forma que la atribución de productos, pero para artículos: articles_recom_viewed_n_times, articles_recom_viewed_n_sessions, articles_recom_extra_n_times, articles_recom_extra_n_sessions, articles_recom_extra_value, articles_recom_goal_n_times, articles_recom_goal_n_sessions, articles_recom_goal_value.

Eventos de objetivo personalizados por cuenta

Una cuenta puede configurar hasta 12 eventos de objetivo. Por cada contenedor de evento configurado en su cuenta con un valor distinto de cero en goal_event_index (N de 1 a 12), aparecen cuatro columnas adicionales en la respuesta:

• goal_event_N_name — Nombre visible del evento de objetivo configurado. Se devuelve como una cadena literal, igual en todas las filas.
• goal_event_N_n_times — Cuántas veces se activó este evento de objetivo durante una sesión en la que se ejecutó la acción.
• goal_event_N_n_sessions — En cuántas sesiones distintas se activó este evento de objetivo al menos una vez después de ejecutarse la acción.
• goal_event_N_value — Suma de los valores monetarios notificados para este evento de objetivo en las veces contadas en goal_event_N_n_times (cero salvo que el contenedor del evento de objetivo esté configurado para capturar un valor).

Ejemplos

# Last 30 days, daily KPIs per action
curl 'https://api:KEY@app.personyze.com/rest/summary_actions
        /where/day>1730000000
        /columns/day,action_name,n_executed,n_delivered,n_extra,products_goal_value
        /order_by_desc/day
        /limit/1000'

# A specific action's lifetime
curl 'https://api:KEY@app.personyze.com/rest/summary_actions
        /where/action_id=42&day>1700000000
        /order_by/day
        /limit/1000'

tracker_code

Devuelve el fragmento de JS que se inserta en su sitio para arrancar el tracker de Personyze. El contenido se deriva de la configuración de su cuenta (ID de cuenta, host de seguimiento, indicadores async/no-hide).

Respuesta

Un fragmento text/html sin más (o JS dentro de<script>) listo para pegar en un <head>. El cuerpo no es JSON — es el único endpoint REST que devuelve HTML sin procesar.

Ejemplo

curl 'https://api:KEY@app.personyze.com/rest/tracker_code'

<script>(function(s){
    s.async = true;
    s.src = '//lcounter.personyze.com/stat-track-lib.js';
    s.onload = function() {
        _S_T.async = true;
        _S_T.setup(5919, "example.com www.example.com");
    };
    (document.querySelector('head') || document.documentElement).appendChild(s);
}(document.createElement('script')))</script>

Próximos pasos