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.

Privacy requests

Find, export and delete one person, as Settings → Data & privacy → Visitor requests does. Your account’s own API key only.

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.

Deleting

DELETE /rest/users/where/… removes the profile row only: the person’s visits, events, form answers, chats and the rest stay, and the request is not logged. To answer a person’s request to be forgotten, use privacy-delete.

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

coupons

Records codes of your coupons used at a checkout the tag did not see — your own order system, a till, a coupon engine’s callback — as redemptions: POST /rest/coupons/redeemed (or /rest/coupons). See Coupon Codes.

Request shape

{"code": "SPRING-K7Q2MX", "time": 1790000000, "email": "ann@example.com", "order": "#1001"}

Or several at once: {"redemptions": [ … ]}, at most 500. Only code is required; time is unix seconds (default: now), email finds the shopper and order is kept with the use. The answer: recorded, already, unknown and unknown_codes.

Privacy: privacy-person, privacy-export, privacy-delete

Answer a person’s request to see or delete their data from your own systems: a privacy tool (OneTrust, Transcend, DataGrail), Zapier, Make, n8n or a script. These three objects do exactly what Settings → Data & privacy → Visitor requests does, and every call is written to its Request log, with the source API and the key’s fingerprint.

privacy_person, privacy_export and privacy_delete work too. Send the person in a POST body rather than in the URL: URLs are written to access logs along the way. Personyze keeps neither the body nor the person’s address in its own REST logs for these objects.

Which key

Your account’s API key, from Settings → Integrations → Full-featured API — the key Zapier, Make and n8n connect with (see Authentication). A key issued for an integration — WordPress, Segment, Shopify or Magento — is refused with 403: it was issued to send data in, not to find or delete people.

Fields

Examples

# Who is this person, and what do we hold?
curl -X POST 'https://api:KEY@app.personyze.com/rest/privacy-person' \
     -H 'Content-Type: application/json' \
     -d '{"q":"ann@example.com"}'

# Everything held about one visitor id, as a file
curl -X POST 'https://api:KEY@app.personyze.com/rest/privacy-export' \
     -H 'Content-Type: application/json' \
     -d '{"q":"-1234567890","by":"user_id"}'

# Delete the profiles whose email address it is
curl -X POST 'https://api:KEY@app.personyze.com/rest/privacy-delete' \
     -H 'Content-Type: application/json' \
     -d '{"q":"ann@example.com","by":"email"}'

The receipt

privacy-delete answers with deleted (store by store, with counts), kept (the suppression list, soft bounces and SMS STOPs, kept so the person is never emailed or texted again), notReached (files exported earlier, your own import files, copies already sent to connected tools, report totals), requestId (the Request log row) and unfinished. Meeting bookings and orders lose their personal details and stay in your reports.

A deletion has a time budget of about 45 seconds. A person with years of visits may not be finished within it: then unfinished names the stores left. What was deleted stays deleted and logged — send the same request again until unfinished is empty.

Errors

Full reference, with answer samples: REST privacy objects.

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