Developing with Lytics / Lytics API Documentation

Personalization

Entity API, ie Personalization or Profile API.

Retrieve attributes and segments an entity (most likely a user) is a member of.

The Entity is a User most likely, but since Lytics is organized as a Graph Database, other types of entities may be modeled such as Accounts, or Company, Content, or custom.

# read a single user
curl -s -H "Authorization: $LIOKEY" \
  -XGET "https://api.lytics.io/api/entity/user/user_id/user123" | jq '.'

Personalization

/api/entity/{table}/{fieldname}/{fieldval}{?fields,segments,meta}

Used to return the Entity object (usually a user, content item, url, account, etc).

  • :entitytype user, account, content, product etc
Parameters
tablestring (required)
Ex: user
Table name, user normally.
fieldnamestring (required)
Ex: email
Field name of identity to use as lookup
fieldvalstring (required)
Ex: [email protected]
Field value of identity
fieldsstring (optional)
Ex: name,org,city
comma delimited field list to be returned
segmentsbool (optional)
Ex: true
Default: true
Should segments this user is member of be included?
metabool (optional)
Ex: true
Default: true
Should Meta Fields be included?
GET

User Me

/api/me/{fieldname}/{fieldval}{?fields,segments,meta,download}

Get single User Entity. This is an alias for /api/entity/user.

Parameters
fieldnamestring (required)
Ex: email
Field name of identity to use as lookup
fieldvalstring (required)
Ex: [email protected]
Field value of identity
fieldsstring (optional)
Ex: name,org,city
comma delimited field list to be returned
segmentsbool (optional)
Ex: true
Default: true
Should segments this user is member of be included?
metabool (optional)
Ex: true
Default: true
Should Meta Fields be included?
downloadbool (optional)
Ex: false
Default: false
Should the content-disposition header set to attachment to download the user as a file?

Response 200

Headers
Content-Type: application/json
Body
{
    "data": {
        "segments": [
            "email_us_based",
            "web_users",
            "all"
        ]
    },
    "message": "success",
    "meta": {
        "by_fields": [
            "user_id",
            "email",
            "fbuid",
            "_uids"
        ],
        "format": "json",
        "name": "user"
    },
    "status": 200
}
GET

Personalization

/api/entity/{table}/{fieldname}/{fieldval}{?fields,segments,meta,download}

Get single User Entity.

# get user whose user_id = user123
curl -s -H "Authorization: $LIOKEY" \
  -XGET "https://api.lytics.io/api/entity/user/user_id/user123" | jq '.'

# get user whose email = [email protected]
curl -s -H "Authorization: $LIOKEY" \
  -XGET "https://api.lytics.io/api/entity/user/email/[email protected]" | jq '.'
Parameters
fieldnamestring (optional)
Default: _uid
fieldvalstring (required)
Ex: [email protected]
Field value of identity
fieldsstring (optional)
Ex: name,org,city
comma delimited field list to be returned
segmentsbool (optional)
Ex: true
Default: true
Should segments this user is member of be included?
metabool (optional)
Ex: true
Default: true
Should Meta Fields be included?
downloadbool (optional)
Ex: false
Default: false
Should the content-disposition header set to attachment to download the user as a file?

Response 200

Headers
Content-Type: application/json
Body
{
    "data": {
        "segments": [
            "email_us_based",
            "web_users",
            "all"
        ]
    },
    "message": "success",
    "meta": {
        "by_fields": [
            "user_id",
            "email",
            "fbuid",
            "_uids"
        ],
        "format": "json",
        "name": "user"
    },
    "status": 200
}
GET

Web Personalization

/api/entity/{table}/{fieldval}?{fields,segments,meta,download}

Get single User Entity using cookie id. This is same as entity api but you don't specify a fieldname (user_id, email, etc) and instead it only uses the cookie identifier.

Parameters
fieldvalstring (required)
Ex: [email protected]
Field value of identity
fieldsstring (optional)
Ex: name,org,city
comma delimited field list to be returned
segmentsbool (optional)
Ex: true
Default: true
Should segments this user is member of be included?
metabool (optional)
Ex: true
Default: true
Should Meta Fields be included?
downloadbool (optional)
Ex: false
Default: false
Should the content-disposition header set to attachment to download the user as a file?

Response 200

Headers
Content-Type: application/json
Body
{
    "data": {
        "segments": [
            "email_us_based",
            "web_users",
            "all"
        ]
    },
    "message": "success",
    "meta": {
        "by_fields": [
            "user_id",
            "email",
            "fbuid",
            "_uids"
        ],
        "format": "json",
        "name": "user"
    },
    "status": 200
}

Profile Deletion

/api/entity/{table}/{fieldname}/{fieldval}

For managing profiles for GDPR purposes.

Parameters
fieldnamestring (required)
Ex: _uid
Field name of identity to use as lookup (could be email, user_id, etc)
fieldvalstring (required)
Ex: [email protected]
Field value of identity
DELETE

Profile Delete Request

/api/entity/{table}/{fieldname}/{fieldval}

Deletes a single Entity (normally a user).

This API persists a deletion event for the particular profile provided. This operation is asynchronous; it will take some time for the profile to be removed from downstream databases and indexes. This request returns a "request_id" which may be used to determine the status of that deletion. While the profile may become unavailable quickly, it may take a while for the full process to complete since it includes all archived historic data. When checking the status of a deletion request, it is important to note that the status flag returned includes both steps of the deletion process.

# Delete user whose "user_id" = "userdeleteme12"
# user_id can be any by-field

curl -s -H "Authorization: $LIOKEY" \
  -XDELETE "https://api.lytics.io/api/entity/user/user_id/userdeleteme12" | jq '.'

Use Cases

  • GDPR right to be forgotten, a user asks for profile to be deleted.
Parameters
fieldnamestring (required)
Ex: _uid
Field name of identity to use as lookup (could be email, user_id, etc)
fieldvalstring (required)
Ex: [email protected]
Field value of identity

Response 200

Headers
Content-Type: application/json
Body
{
    "status": 200,
    "message": "delete request received",
    "data":{
        "request_id": "e9d5f2d3d2c7a7d0e801-1526083200",
        "completed": false
    }
}
GET

Profile Deletion Status

/api/entity/deletestatus/{request_id}

Retrieves the status of a submitted deletion event.

Parameters
request_idstring (required)
Ex: e9d5f2d3d2c7a7d0e801-1526083200
RequestID of previously submitted deletion event

Response 200

Headers
Content-Type: application/json
Body
{
    "status": 200,
    "message": "delete request received",
    "data":{
        "request_id": "e9d5f2d3d2c7a7d0e801-1526083200",
        "completed": false
    }
}