Documentation / Developer / Lytics APIs

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.

GDPR deletions in Lytics go through a number of steps before being marked as "completed":

  1. The first round "soft" deletes the current data so no new data will be logged until hard removals have occurred. Profiles should not be accessible at this point.

  2. A batch process begins the removal, where the profile data is deleted from the Lytics system.

  3. Event backups are purged of any events associated with the profile.

  4. A second profile deletion takes place to ensure that any access of backups during the event purge does not spoil the GDPR process.

  5. The GDPR request is marked as "completed."

The body of the response contains a state entry, which defines where in the deletion lifecycle this request exists. The state may include one of the following:

  • initial - the request has been created, but soft-deletion has not occurred

  • primary - soft-deletion has occurred, but we are waiting on first round of hard deletions.

  • archive - primary hard deletion has occurred, but we are still processing removing these identifiers from backups.

  • secondary - the data has been removed from backups, and we are waiting for the second hard deletion.

  • done - all phases have been complete

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",
        "state": {
            "current": "archive"    
        }
        "completed": false
    }
}