The Personyze REST API is how third-party applications read and modify data in your account: customer profiles, product and article catalogs, placeholders, actions, audience lists, daily reporting summaries — all the same data the Personyze GUI works with. It uses standard HTTPS, accepts and returns JSON, and supports the four standard verbs (GET, POST, PUT, DELETE).
This page is the starting point. For the full setup walkthrough, see Authentication. For the path-parameter syntax (the where/columns/order_by/limit pattern that runs through every endpoint), see Path Parameters. For per-object column lists and method support, see Objects Reference.
Quick start
Fetch the user with internal ID 42:
curl 'https://api:YOUR_API_KEY@app.personyze.com/rest/users/where/internal_id=42'That’s the whole shape of every request:
https://api:<API_KEY>@app.personyze.com/rest/<object>[/<modifier>/<value>...]- HTTPS only. Plain HTTP gets
401 Unauthorized— even forlocalhostproxies. - HTTP Basic auth with username
apiand your API key as the password (or pass it inline as in thecurlexample above). - All path arguments are URL-decoded before parsing — column values containing
/,=,&, or%must be percent-encoded.
HTTP methods
| Method | Purpose | Body | Returns |
|---|---|---|---|
GET |
read | none | Array of records (or one record on the single-id form) |
POST |
create | JSON object | Numeric ID of the new record |
PUT |
update | JSON object | Number of rows affected |
DELETE |
delete | none | Number of rows affected |
POST and PUT bodies use Content-Type: application/json. application/x-www-form-urlencoded is accepted as a fallback for legacy clients but JSON is preferred.
Response codes
| Code | Meaning |
|---|---|
200 OK |
Success — body depends on method (see HTTP methods table above). Date-typed columns are serialized as YYYY-MM-DD HH:MM:SS; timestamps are Unix seconds in UTC. |
400 Bad Request |
Your input was rejected. Body is a plain-text human-readable description (e.g. “Cannot do this operation on whole table: column ‘uset_id’ is not indexed.”). Common causes: typo in column name, missing where clause on a large table, malformed JSON body. |
401 Unauthorized |
Bad or missing API key, or the request wasn’t HTTPS. |
500 Internal Server Error |
Unexpected fault on the API side — message in body. Worth retrying after a few seconds; if persistent, contact support. |
503 Service Unavailable |
Transient failure (deadlock, lost DB connection, etc.). Safe to retry with backoff. |
Conventions across endpoints
id vs internal_id
Most objects expose two identifiers:
id— the Personyze internal numeric primary key, auto-assigned on insert. Stable forever, but only meaningful within Personyze.internal_id— the external identifier you supply (your e-commerce SKU, your CRM user ID, etc.). Exposed for objects where mapping to an external system matters:users,products,articles.
For most integration code you’ll want to use internal_id — that way the same code keeps working even if the same data is re-imported into Personyze with new ids.
Indexed columns required on large tables
Endpoints that wrap large tables (users, events, sessions_archive, summary_actions, etc.) reject full-table scans. You must include either a where clause or an order_by on an indexed column. Error messages list the indexed columns/composites available — see Path Parameters → Indexed-column requirement for the full rules.
Composite indexes
Composite indexes appear in error messages as [col1, col2, col3]. Only the leading column of a composite is usable as a single-column filter. The other columns become useful only when combined with the leading column.
API keys are per-account
Every Personyze account you have access to has its own API key — they’re not interchangeable. Switching accounts means switching keys.
Limits & pagination
- 1,000-row maximum per request. Use
limit/<count>orlimit/<offset>,<count>to control page size. - Cursor pagination preferred over deep offsets. Walking the indexed
order_bycolumn with cursor-stylewhereconditions is much faster than deepoffsetvalues, which re-read all skipped rows.
where instead of paging by offset. For example, after fetching 1,000 users ordered by last_session_time descending, the next page should use where/last_session_time<<last_seen_value> rather than limit/1000,1000.Dive deeper
curl/Python/JS examples, and multi-account access. Read →where / columns / order_by / limit syntax with all operators and AND/OR composition. Read →Related guides
- Setup by Site Type — Tracking, Feeds & Integrations — pick your starting point based on your site type.
- JavaScript Action Guide — for writing custom Personyze actions that run in the browser.
- Accessing Campaign Data Client-Side — read campaign IDs and variables from JavaScript on the page.