Synerise AI API (v1)

Download OpenAPI specification:Download

Welcome to Synerise AI API reference! We hope that you'll enjoy your stay here. If you need help with our services, feel free to contact us: support-ai@synerise.com

Authorization header is required to access almost all API endpoints and can be obtained using our Authorization API.

All endpoints return an error structure with following fields:

  • status - status code of result, 0 means OK.
  • message - message explaining error
  • timestamp - response generation timestamp in UTC timezone.
  • error - short error description intended for final Users.
  • message - longer error description intended for Developers.
  • path - the request path that generated the error.

Remember that every API call must have these headers:

Header Name Header Value
Accept application/json
Content-Type application/json
Authorization (does not apply to Log in endpoints) Bearer {JWT token}

Authentication

bearer

JWT token authorization. The token is prefixed with Bearer constant.

Security scheme type: API Key
Header parameter name: Authorization

Authorization

The Synerise AI API uses JWT as an authorization method in order to simplify the API consumption process.

The idea is very simple, you send your profile credentials to the login endpoint and it returns you a token. Then you have to pass it as an Authorization header to any subsequent request, just like here Authorization Bearer [token]

It is valid for 1 hour only, but it does not mean, that you cannot use our API any longer - if you want to prolongate the session, you just need to request a new token using Refresh token, after token expiry you have to login again using Login profile.

To verify your JWT token use an endpoint Validate token. In case of an error all endpoints return an error response with following statuses and x-status-code response header:

  • 0 - All ok.
  • 1 - Missing X-Api-Key/Authorization header.
  • 2 - Incorrect Authorization header - missing Bearer prefix.
  • 3 - JWT token expired.
  • 4 - Incorrect Authorization/X-Api-Key header.
  • 5 - Cannot authenticate due to a system error.

Sample response body: {"status": 4, "error": "Incorrect 'X-Api-Key' header.", "message": "Incorrect 'X-Api-Key' header.","timestamp":"2019-01-03 09:24:07Z"}

Checks Auth API health

Returns Auth API health check status.

Responses

200

All ok.

get /auth/v1/healthcheck
https://ai-api.synerise.com/auth/v1/healthcheck

Validates JWT token.

Validates JWT token and returns status code 200 with token's details, otherwise returns 500 and an error description.

Authorizations:

Responses

200

JWT token is valid.

500

JWT token is invalid.

get /auth/v1/token
https://ai-api.synerise.com/auth/v1/token

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "timestamp": "2019-07-26T09:15:13Z",
  • "status": 0,
  • "token": "string",
  • "validTo": "2019-07-26T09:15:13Z"
}

Generate JWT token for a profile.

Log in a profile in order to obtain a JWT token, which can be used in subsequent requests. The token is valid for 1 hour. If you want to use our API longer, you have to request a new one by requesting the Profile token refresh endpoint before this time runs out.

Request Body schema: application/json

API access credentials.

apiKey
string
secretKey
string

Responses

200

Created JWT token

500

Cannot create JWT token, some error occured.

post /auth/v1/login/profile
https://ai-api.synerise.com/auth/v1/login/profile

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "apiKey": "string",
  • "secretKey": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "timestamp": "2019-07-26T09:15:13Z",
  • "status": 0,
  • "token": "string",
  • "validTo": "2019-07-26T09:15:13Z"
}

Refreshes JWT token.

Retrieves a refreshed JWT token in order to prolongate the profile session. Requires current JWT token.

Authorizations:

Responses

200

Refreshed JWT token for the current profile.

500

Cannot refresh JWT token, some error occured.

post /auth/v1/refresh/profile
https://ai-api.synerise.com/auth/v1/refresh/profile

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "timestamp": "2019-07-26T09:15:13Z",
  • "status": 0,
  • "token": "string",
  • "validTo": "2019-07-26T09:15:13Z"
}

Events

Events upload API. The API supports uploading of events into Synerise AI profile. There is an endpoint to upload a single event of supported type or batch of events in a single request. Each endpoint is secured using JWT token authorization and supports dryRun parameter that allows to validate events without processing them.

The API supports following event types:

Each event type has few required fields, some fields are filled based on request i.e. source ip, current timestamp and date, host address and some fields can have empty value.

Uploads events in a batch

Uploads a batch of events to the system in the profile scope. The service supports up to 100 events per request. We recommend to gzip request body and a single request must contains events of single type. Following event types are supported * page.visit * transaction.charge * transaction.basket * product.addToCart * product.removeFromCart * message.send * newsletter.click * newsletter.open * newsletter.confirmSubscribe * [custom.event] (https://ai-api.synerise.com/schema/custom.event.json) Content-Encoding: gzip header.

Authorizations:
query Parameters
dryRun
boolean

Validate incoming data only.

Request Body schema: application/json

Event name and array of events to upload. Some propertes are required, most are optional.

eventType
string
Enum:"page.visit" "message.send" "transaction.charge" "transaction.basket" "product.addToCart" "product.removeFromCart" "newsletter.open" "newsletter.confirmSubscribe" "newsletter.click"
items
Array of objects (SingleEventRequestSchema) [ 1 .. 100 ] items

Responses

200

OK batch has been processed.

500

Some error occured.

post /events/v1/batch
https://ai-api.synerise.com/events/v1/batch

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "eventType": "page.visit",
  • "items":
    [
    ]
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "timestamp": "2019-07-26T09:15:13Z",
  • "status": 0,
  • "batchId": "string"
}

Upload a single event

Uploads a single event to Synerise AI profile.

Authorizations:
path Parameters
eventType
required
string
Enum:"newsletter.open" "newsletter.confirmSubscribe" "newsletter.click" "page.visit" "message.send" "transaction.charge" "product.addToCart"

Event type to upload.

query Parameters
dryRun
boolean

Validate incoming data only.

Request Body schema: application/json

Event body

clientUUID
string
eventTimestamp
string
property name*
any

Responses

200

OK event has been processed.

500

Some error occured.

post /events/v1/single/{eventType}
https://ai-api.synerise.com/events/v1/single/{eventType}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "clientUUID": "string",
  • "eventTimestamp": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "timestamp": "2019-07-26T09:15:13Z",
  • "status": 0
}

Events health

Returns Events API health check status.

Authorizations:

Responses

200

All ok.

get /events/v1/healthcheck
https://ai-api.synerise.com/events/v1/healthcheck

Segmentation

Segmentation API exposes methods to obtain different types of segmentation of your data. You can fetch analytical data as well as segmentation of particular data point, for instance your user.

RFM segments

Method returns RFM segments with thier size for Synerise AI profile.

Authorizations:

Responses

200

OK, RFM segments have been returned.

500

Some error occured.

get /segmentation/v1/rfm/segments
https://ai-api.synerise.com/segmentation/v1/rfm/segments

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "property1": "string",
  • "property2": "string"
}

RFM quantiles

Returns quantiles values used to build RFM segments for Synerise AI profile.

Authorizations:

Responses

200

OK, RFM quantiles have been returned.

500

Some error occured.

get /segmentation/v1/rfm/quantiles
https://ai-api.synerise.com/segmentation/v1/rfm/quantiles

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "frequency":
    [
    ],
  • "monetary":
    [
    ],
  • "recency":
    [
    ]
}

RFM for user

For each requested user returns information into which RFM segment particular user belongs to.

Authorizations:
Request Body schema: application/json

Users for which we're requesting segmentation

clientUUIDs
Array of strings

Responses

200

OK, RFM segments for users have been returned.

500

Some error occured.

post /segmentation/v1/rfm/clients
https://ai-api.synerise.com/segmentation/v1/rfm/clients

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "clientUUIDs":
    [
    ]
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "quantiles":
    {
    },
  • "rfm":
    {
    }
}

RFM status

Status method tells you whether RFM service is ready for your usage.

Authorizations:

Responses

200

OK RFM segmentation status has been returned.

500

Some error occured.

get /segmentation/v1/rfm/status
https://ai-api.synerise.com/segmentation/v1/rfm/status

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "ready": true,
  • "enabled": true,
  • "message": "string"
}

RFM healthcheck

Simple method which allows to check health of the RFM functionality. Please check status method if would like to get RFM status.

Authorizations:

Responses

200

OK service is available, response body describes whether it's healthy

500

Service not available

get /segmentation/v1/rfm/healthcheck
https://ai-api.synerise.com/segmentation/v1/rfm/healthcheck

RFE segments

Method returns RFE segments with thier size for Synerise AI profile.

Authorizations:

Responses

200

OK, RFE segments have been returned.

500

Some error occured.

get /segmentation/v1/rfe/segments
https://ai-api.synerise.com/segmentation/v1/rfe/segments

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "property1": "string",
  • "property2": "string"
}

RFE quantiles

Returns quantiles values used to build RFE segments for Synerise AI profile.

Authorizations:

Responses

200

OK, RFM quantiles have been returned.

500

Some error occured.

get /segmentation/v1/rfe/quantiles
https://ai-api.synerise.com/segmentation/v1/rfe/quantiles

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "frequency":
    [
    ],
  • "engagement":
    [
    ],
  • "recency":
    [
    ]
}

RFE for users

For each requested user returns information into which RFE segment particular user belongs to.

Authorizations:
Request Body schema: application/json

Users for which we're requesting segmentation

clientUUIDs
Array of strings

Responses

200

OK, RFE segments for users have been returned.

500

Some error occured.

post /segmentation/v1/rfe/clients
https://ai-api.synerise.com/segmentation/v1/rfe/clients

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "clientUUIDs":
    [
    ]
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "quantiles":
    {
    },
  • "rfm":
    {
    }
}

RFE status

Status method tells you whether RFE service is ready for your usage.

Authorizations:

Responses

200

OK, RFE segmentation status has been returned.

500

Some error occured.

get /segmentation/v1/rfe/status
https://ai-api.synerise.com/segmentation/v1/rfe/status

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "ready": true,
  • "enabled": true,
  • "message": "string"
}

RFE healthcheck

Simple method which allows to check health of the RFE functionality. Please check status method if would like to get RFE status.

Authorizations:

Responses

200

OK, service is available, response body describes whether it's healthy.

500

Service not available.

get /segmentation/v1/rfe/healthcheck
https://ai-api.synerise.com/segmentation/v1/rfe/healthcheck

Retrieve 2d coordinates of users..

Ai Segmentation of users in 2d space.

Authorizations:

Responses

200

A list of user coordinates.

get /segmentation/v1/ai/users/coordinates
https://ai-api.synerise.com/segmentation/v1/ai/users/coordinates

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "x": 0,
  • "y": 0,
  • "amount": 0,
  • "num_events": 0,
  • "time_to_last_purchase": 0
}

Retrieve statistics of users in selected area.

Retrieve statistics of users in selected area.

Authorizations:
query Parameters
xmin
required
number <float>

Minimum x coordinate value of cluster

ymin
required
number <float>

Minimum y coordinate value of cluster

xmax
required
number <float>

Maximum x coordinate value of cluster

ymax
required
number <float>

Maximum y coordinate value of cluster

Responses

200

Statistics of users in selected cluster.

400

Unsupported Parameter Value Error

get /segmentation/v1/ai/users/stats
https://ai-api.synerise.com/segmentation/v1/ai/users/stats

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "stats":
    {
    },
  • "products":
    [
    ]
}

Retrieve statistics of users in given cluster.

Retrieve statistics of users in given cluster.

Authorizations:
query Parameters
clustersNum
required
integer [ 1 .. 8 ]

Total number of clusters

clusterLabel
required
integer

Selected cluser id

Responses

200

Statistics of users in given cluster.

400

Unsupported Parameter Value Error

get /segmentation/v1/ai/users/stats/cluster
https://ai-api.synerise.com/segmentation/v1/ai/users/stats/cluster

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "stats":
    {