Wiki

Personyze External API

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.
  • ''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.
  • ''401 Unauthorized'' - API key is invalid, or you don't use HTTPS.

Response body will contain:

  • 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.

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.

Objects

©2008-2023 All rights reserved. Personyze® is a registered trademark. Privacy Policy. Terms of Use.