Personyze Personyze developer docs
Open Personyze
Users

REST Do object

Personyze developer documentation Questions: support@personyze.com

For information how REST API works, see rest main page.

This object allows you to perform operations on an online user by his user_id (Personyze user Id), internal_id (Id that you set) or email.

You need to send POST request to the "do" object. The POST body must be JSON array, where each element is description of an operation to perform on a user. So you can perform several operations (maybe on different users) in one request.

curl --data '[["internal_id", 1, "Product Added to cart", "P1000"], ["email", "john@example.com", "Product Purchased", "P1001"]]' 'https://api:FD09908F25BECB09D78EBEA1DADFB618651F612D@app.personyze.com/rest/do'

Each operation description is JSON array, where

  1. the first element is a user key name, that can be one of: "user_id", "internal_id" and "email"
  2. the second element is a value that corresponds to the key
  3. the third element is command name
  4. next elements depend on the command name

Command name can be one of:

  1. "User Profile" - set profile field, like ["internal_id", 1, "User Profile", "first_name", "John"]
  2. "Product Viewed" - report product viewed, like ["internal_id", 1, "Product Viewed", "P1000"]
  3. "Product Added to cart" - report product added to cart, like ["internal_id", 1, "Product Added to cart", "P1000"]
  4. "Product Liked"
  5. "Product Purchased"
  6. "Product Removed from cart"
  7. "Product Unliked"
  8. "Article Viewed"
  9. "Article Commented"
  10. "Article Liked"
  11. "Article Goal"
  12. "Article Unliked"

Command names are matched case-insensitively.

Quantity

Product commands accept an optional quantity, given as a "quantity" marker followed by the number:

curl --data '[["internal_id", 1, "Product Purchased", "P1000", "quantity", 3]]' 'https://api:FD09908F25BECB09D78EBEA1DADFB618651F612D@app.personyze.com/rest/do'

Without it the quantity is 1.

Setting several profile fields at once

"User Profile" takes any number of field/value pairs:

curl --data '[["email", "john@example.com", "User Profile", "first_name", "John", "industry", "e-commerce", "loyalty_tier", "gold"]]' 'https://api:FD09908F25BECB09D78EBEA1DADFB618651F612D@app.personyze.com/rest/do'

Names that aren't standard profile fields are stored as custom fields, so loyalty_tier above works without being declared first. Field names may be written in snake-case or camel-case. Sending no pairs at all fails with Nothing to set.

Errors

  • Unknown command: {name} — the command name wasn't recognised.
  • User ID is required in {command} — every command needs a user key first.
  • Product internal ID is not specified / Article internal ID is not specified — the item id argument was missing.
  • Nothing to set — a "User Profile" command with no field/value pairs.

Commands are executed in order, and a failure part-way through means the earlier commands in the same request have already been applied.

When to use something else

  • To read or delete interaction history rather than report it, and to send an explicit timestamp or monetary amount, use products_interactions.
  • To have Personyze decide what to show a user, not just record what they did, use tracker-v1.
  • To bulk-import or update profiles, use users — it is built for volume, whereas this object is for one-off operations on individuals.