REST API — Objects Reference

Reference for every object exposed by the Personyze REST API. Each section below covers one object: its purpose, supported HTTP methods, columns (with type and indexing notes), and copy-paste-ready curl examples.

Prerequisites — read these first if you haven’t:

• REST API Overview & Quick Start — request shape, HTTP methods, response codes
• Authentication — getting your API key, sending it, multi-account setups
• Path Parameters — the where/columns/order_by/limit syntax that runs through every example below

Object index

Click an object to jump to its section. Each section has its own anchor URL — you can deep-link directly to any object’s reference.

CRUD content (read/write)

Hold your campaigns, audience, catalog, and configuration. Full CRUD for External API user and above.

Interactions / events (write-mostly)

Append-only logs of visitor interactions. Mostly used by SDKs and back-end integrations.

Reports / archive (read-only)

Tracker / SDK helpers

Used by the JS tracker, native SDKs, and integrations to self-bootstrap. Not usually called by REST API consumers directly.

users

Customer profiles. Each row is one visitor or customer. Column names are dynamic — beyond the documented housekeeping columns, you can store any custom keys/values your account needs.

Identifying / housekeeping columns

Common profile fields (custom)

first_name, middle_name, last_name, sex, birthday, timezone, current_city, current_state, current_country, religion, political, interests, relationship_status, education_year, plus custom_t_1…custom_t_6 (text), custom_i_1…custom_i_4 (integer), custom_f_1…custom_f_2 (float), custom_d_1, custom_d_2 (date) — and any additional fields you’ve configured on your account.

Examples

# 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)

Indexed columns / scan limits

GET /rest/users without a where requires order_by on an indexed column — user_id, last_session_time, data_last_modified, fb_id, email, or internal_id. Otherwise: 400 Cannot do this operation on whole table.

Throttling

POST /rest/users is serialized per Personyze account: at most one in-flight insert at a time. Requests that wait more than 1 second are rejected with 400 Too many simultaneous requests — retry with exponential backoff.

user_lists

Named lists of users (e.g. “VIPs”, “Newsletter opt-ins”). One row per list. Membership lives in a separate object — see user_list_users.

Columns

Examples

# 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

Membership: which users belong to which user_lists. One row per (user_list_id, user_id) pair.

POST accepts either an existing user_id, or a lookup key (user_internal_id, user_email) — the API resolves it to a user_id, creating a stub users row if needed.

Columns

POST body extras (resolved to user_id server-side, then dropped)

Examples

# 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

Personalization actions — what your campaigns do: render HTML, show a popup, send an email, push a notification, etc. Read-only over REST today (create/edit through the GUI).

Columns

Examples

# 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

Audience conditions — the when of campaigns. Read-only over REST.

Columns

Examples

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

placeholders

Containers of type placeholder — DOM slots where actions render content. Manage the catalog of placeholders defined for your site.

Columns

Examples

# 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

“Grab variable” containers — pull DOM/JS values from the visitor’s page back into the visitor profile. Each container says “watch this variable / DOM element; when it appears, capture it as a profile field.”

Columns

Examples

# 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

Product catalog. Each row is one SKU. Column names are dynamic — beyond the documented housekeeping columns, you can store any custom fields your catalog needs.

Identifying / housekeeping columns

Common product fields (custom)

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. The actual field set depends on your account configuration.

Renamed inputs (on POST / PUT)

Examples

# 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

Article catalog (blog posts, news, knowledge-base entries). Same shape as products but for editorial content.

Identifying / housekeeping columns

Common article fields (custom)

title, description_short, description_long, image_big_url, image_medium_url, image_small_url, author, publish_date, category, tags, rank, etc. The actual list depends on your site’s other_columns_info config.

Renamed inputs

Examples

# 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

Log of interactions on products: views, adds-to-cart, purchases, “favorite,” “delivered.” Append-mostly. Backed by an archive table.

Columns

Insert: identifying the user

POST accepts any one of these to identify the user:

Examples

# 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'

Indexed columns

user_id, [product_internal_id, user_id, transaction_time], status, time. Queries without a where on one of these (or order_by on the same) are rejected as full-table scans.

events

Generic event log — one row per tracked event captured by the JS tracker, SDK, or do endpoint. Read-only over REST today.

Columns

Examples

# 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

Form-submission log. One row per form-submit event captured by the tracker. Read-only over REST today.

Columns

The data JSON is automatically expanded into top-level keys on read — request specific custom fields by name.

Examples

# 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'

Indexed columns include user_id, action_id, and time. Queries must filter on one of these.

do

Fire-and-forget command dispatcher: send a single user-profile update or interaction event without speaking the tracker protocol. The body is an array of commands; each is dispatched independently.

Request shape

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

• <key-type>: "user_id", "internal_id", or "email". Optional — omit for commands that don’t target a user.
• <key-value>: the corresponding identifier.
• <command>: a string (case-insensitive). See list below.
• <arg…>: command-specific positional arguments.

A successful POST returns nothing; failures throw (the whole batch aborts on the first error).

Commands

User profile

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

After the command name, the args alternate field, value, field, value, …

Product interactions

["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"]

After the SKU, optional key-value pairs: "quantity", "amount", "action_id", "transaction_time".

Article interactions

["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"]

Examples

# 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

One row per visitor session (a contiguous window of activity). Backed by the long-lived archive table — much wider than events, with location, device, screen, and browser metadata.

Identifying / housekeeping

Geo / locale / device

Engagement counters

Landing URL & referrer

UTM / ad campaign

ad_campaign, ad_source, ad_medium, ad_term, ad_content — the standard UTM parameters as captured on landing.

Examples

# 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'

Indexed columns: first_visit_id, user_id, plus several others. Queries must filter on an indexed column or the request is rejected as a full-table scan.

user_interests

Per-user interests, categories, tags, and family/cross/upsale tags inferred by the tracker pipeline. One row per (user_id, value, class, time). Read-only.

Columns

Indexed columns: user_id, time. Queries must filter on an indexed column.

Examples

# 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_*

Per-product aggregated interaction counters maintained by the offline summary pipeline. Six rolling windows are exposed at separate paths — pick the one that matches your reporting horizon. All share the same column shape and indices; only the time window differs.

Endpoints

Identifying

Per-product counters (count of interactions on this product within the window)

Catalog-wide distribution stats

The same value on every row — describes the whole catalog within this window. For each metric M ∈ {viewed, delivered, extra, favorite, goal}:

Last 3 goal users (most recent purchasers of this product)

Indexed columns

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. Queries must filter on (or order_by) one of these.

Examples

# 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

Daily aggregated KPIs per action — one row per (day, action_id) for actions bound to a specific campaign (condition_id). Read-only.

Identifying

Action exposure

Product attribution (when this action recommended products)

Article attribution

Same shape as product attribution but for articles: 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.

Per-account custom goal events

An account can configure up to 12 goal events. For every event container configured in your account with a non-zero goal_event_index (N from 1 to 12), four extra columns appear in the response:

• goal_event_N_name — Display name of the configured goal event. Returned as a literal string, the same on every row.
• goal_event_N_n_times — How many times this goal event fired during a session in which the action was executed.
• goal_event_N_n_sessions — In how many distinct sessions this goal event fired at least once after the action was executed.
• goal_event_N_value — Sum of monetary values reported for this goal event across the times counted in goal_event_N_n_times (zero unless the goal-event container is configured to capture a value).

Examples

# 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

Returns the JS snippet you embed in your site to bootstrap the Personyze tracker. The contents are derived from your account’s settings (account ID, tracking host, async/no-hide flags).

Response

A plain text/html (or JS-in-<script>) snippet ready to paste into a <head>. The body is not JSON — this is the one REST endpoint that returns raw HTML.

Example

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>

Next steps