Personyze Personyze developer docs
Open Personyze
REST API

Personyze External API

How third-party applications read and change data on a Personyze account.

Personyze developer documentation Questions: support@personyze.com

Personyze External API makes possible for third-party applications to read and change data on your real account, like add/delete Placeholders, Products in the catalog, etc.

The API utilizes HTTP protocol. If your application is capable of making HTTP requests (nowadays this is true for almost 100% applications), it can connect to Personyze server, send HTTP requests and get responces.

Data exchange is happening in JSON format.

The conversation is object-wise. That is there are several "objects" like placeholders, products, users, that you can ask 4 different things to do with them:

  1. Get information. For example get listing of all or some selected products in the database. To do this use HTTP GET request.
  2. Add new items (e.g. products). POST request.
  3. Change items. PUT request.
  4. Delete items. DELETE request.

Request example

To do simplest request run the following command in your nice system terminal:

curl 'https://api:FD09908F25BECB09D78EBEA1DADFB618651F612D@app.personyze.com/rest/placeholders'

You just need to replace my api key which looks like FD09908F25BECB09D78EBEA1DADFB618651F612D with yours one.

And this will print JSON array of placeholders in your account. If you don't have placeholders, create them here.

Here is how to add new placeholder:

curl --data '{"name": "Fake", "html_id": ".fake"}' 'https://api:FD09908F25BECB09D78EBEA1DADFB618651F612D@app.personyze.com/rest/placeholders'

Then you can see the new placeholder added to the list. When API request completed, it printed a number to the terminal. This number is new placeholder Id, that you can use to change or delete it.

Change:

curl -X PUT --data '{"html_id": "#fake"}' 'https://api:FD09908F25BECB09D78EBEA1DADFB618651F612D@app.personyze.com/rest/placeholders/14'

Number 14 in app.personyze.com/rest/placeholders/14 is placeholder id from the previous request. Your number will be likely different.

And finally we will delete that fake and unneeded placeholder:

curl -X DELETE 'https://api:FD09908F25BECB09D78EBEA1DADFB618651F612D@app.personyze.com/rest/placeholders/14'

Request format

First example above sent HTTP GET request to app.personyze.com/rest/placeholders. To get information about various objects do requests to app.personyze.com/rest/{OBJECT} sending your api key through HTTP "Basic" authentication. Username must be "api", the password is your key. Need to send requests through secure HTTPS protocol. No special HTTP headers needed.

POST and PUT requests (2nd and 3rd above) need to send request body in JSON format.

GET, PUT and DELETE requests can use additional parameters in the request path right after the object name:

app.personyze.com/rest/{OBJECT}/{PARAMETERS}

Personyze offers special [[rest:path-params|syntax for path parameters]] that allows to select records by condition.

Response format

Personyze server responds with one of the following HTTP status codes:

  • 200 OK - Request completed successfully.
  • 400 Bad Request - The request was rejected: an unknown column, a malformed "where", a missing mandatory field, or a query this object doesn't support. Response body describes which.
  • 401 Unauthorized - API key is invalid, or you don't use HTTPS.
  • 500 Server Error - Error occurred. Response body will contain the description of the error.
  • 503 Temporarily Unavailable - You need to stand by number of seconds and retry the request.

On success the response body is JSON:

  • GET requests return JSON array of requested records.
  • POST requests to most objects return number identifier of new added record.
  • PUT and DELETE requests to most objects return number affected rows.

On failure the response body is plain text describing the error, not JSON.

See errors, limits and retries for the full list of messages and what to do about each.

Limitations

Personyze allows to select up to 1000 records at once. So /limit/1000 is the maximum you can ask in one request.

Some objects (like users) don't allow doing slow queries frequently. If you select a user by his first name, this implies full table scan because Personyze doesn't index users by their first name. However selecting by email will be fast. Such a query is either refused, or serves only its first 50 rows — the error message names the columns that do have indices.

Objects

Users

  • users - user profiles: import them, update them, read them back
  • zapier_users - the same as users, but POST returns a JSON object; used by the Zapier integration
  • users_columns - which custom fields exist on user profiles in your account
  • user_lists - user lists (segments)
  • user_list_users - association between users and user lists
  • user_interests - the interests Personyze inferred for each user
  • do - perform operations on users who are online right now

Catalog

Analytics

Account configuration