Download OpenAPI specification:Download
LianaAutomation REST API documentation.
LianaAutomation REST API supports two authentication methods. OAuth 2.0 Bearer
token authentication is recommended for new integrations and is available only
on the rest.automation.lianacloud.com host. The legacy HMAC-SHA256 method
remains supported on other hosts, with a phased deprecation described below.
OAuth 2.0 client credentials authentication is the recommended method for
server-to-server integrations. It is available only when calling the API via
the rest.automation.lianacloud.com host — no other LianaAutomation REST API
host supports it. A short-lived access token is obtained from the LianaCloud
token service and sent as a Bearer token in the Authorization header. No
request signing or additional headers are required.
Create OAuth client credentials in LianaAccount or contact your account manager. Each credential set is associated with a customer account and carries a set of permitted scopes.
Exchange your client credentials for an access token using the OAuth 2.0 client credentials grant:
POST https://tokens.lianacloud.com/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=<your-client-id>&client_secret=<your-client-secret>&scope=automation-api
The token service returns a JSON response:
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 900,
"scope": "automation-api"
}
The token must carry at least one scope from the automation-api namespace.
Use automation-api as the scope value when requesting the token.
Include the access token in the Authorization header of every request:
Authorization: Bearer <access-token>
Content-Type: application/json
The Date and Content-md5 headers are not required when using Bearer tokens.
Access tokens are short-lived (the expires_in field in seconds shows the lifetime).
When a token expires, the API returns a 401 response. Request a new token from the
token service using the same client credentials.
Deprecation notice: On the
rest.automation.lianacloud.comhost, legacy HMAC-SHA256 authentication will be discontinued after 31 December 2026, after which OAuth 2.0 Bearer token authentication will be the only supported method on that host. Migrate existing integrations to OAuth before that date. This deprecation does not apply to other LianaAutomation REST API hosts — they do not have OAuth available and will continue to use the legacy method after that date; contact your account manager if you are unsure which host your integration uses.
The legacy method authenticates requests using an HMAC-SHA256 signature computed from the request content. It requires the following headers on every request:
Date: Timestamp in ISO 8601Authorization: REALM USERID:SIGNATUREContent-md5: MD5 hash of the request bodyContent-Type: application/jsonREALM USERID:SIGNATURE
The header is valid for 15 minutes based on the given timestamp.
The signature is an HMAC-SHA256 of a newline-separated string, using the REST user password as the key. The string is constructed from the following fields in order:
POSTContent-md5 headerapplication/jsonDate headerPOST
b41c090e9b32a3f85c631db1af38b0af
application/json
2099-01-01 00:00:00+0200
{"ping":"pong"}
/rest/v1/pingpong
HMAC_SHA256("password", message)
= d0e9d4895b0a06e19623b6c63cf6b173d9fa8ca3427ccb680c22209b90d7bb5e
Authentication failures return HTTP 401. A wrong URL or REALM returns HTTP 404.
This utility function can be used for verifying connections with the LianaAutomation REST API. This is the first command you should try out before investing time into the more complex ones
| ping | string |
{- "ping": "pong"
}{- "pong": "pong"
}Bring data to LianaAutomation from external systems.
| channel required | string The channel system name or ID. Channel ID is used to track the source of the data. Can be found from LianaAutomation under Settings from the Admin Channels -page |
| no_duplicates | boolean If true, do not create a new duplicate event when an identical event already exists. Automations will not be triggered. Default: false |
| skip_automations | boolean If true, this import will not trigger automations. Default: false |
| allow_identity_update | boolean If true, the import can update email and sms values of the identity. Default: false |
required | Array of objects An array of multiple identities and events related to that identity. |
{- "channel": "string",
- "no_duplicates": false,
- "skip_automations": false,
- "allow_identity_update": false,
- "data": [
- {
- "identity": {
- "email": "string",
- "sms": "string",
- "extra1": "string",
- "token": "string"
}, - "events": [
- {
- "verb": "string",
- "items": {
- "example-key1": "string",
- "example-key2": "string"
}
}
]
}
]
}{- "succeed": true,
- "handle": "string"
}Make a database search request
| channels | Array of strings Channels to search from |
| verbs | Array of strings Event types to search for |
| from | string <date-time> Event is newer than |
| to | string <date-time> Event is older than |
| include_data | boolean Include event data in response |
| limit | integer Default: 10000 Limit event count in result. Maximum is 10000 |
| offset | integer Offset for traversing large event counts |
Array of objects Persons to search for |
{- "channels": [
- 1
], - "verbs": [
- "contact"
], - "from": "2019-08-24T14:15:22Z",
- "to": "2019-08-24T14:15:22Z",
- "include_data": true,
- "limit": 10000,
- "offset": 0,
- "identities": [
- {
- "email": "user@company.com",
- "sms": "+3560101234567",
- "extra1": "extra1",
- "token": "abc123",
- "id": "1234"
}
]
}{- "handle": "1234"
}Check if a requested database search is completed.
| handle | string The handle returned as response from the initial request |
{- "handle": "1234"
}{- "ready": true
}Fetch search results of a finished request
| handle | string The handle returned as response from the initial request |
{- "handle": "1234"
}[- {
- "at": "2019-08-24T14:15:22Z",
- "verb": "created",
- "channel": "2",
- "identity": {
- "id": "1234",
- "token": "abc123",
- "email": "user@company.com",
- "sms": "+3580101234567",
- "extra1": "extra1"
}, - "data": {
- "date": "2019-08-24T14:15:22Z",
- "origin": "admin.mailer.domain"
}
}
]Request data to be deleted from database.
| channels | Array of strings Channels to delete from |
Array of objects Persons to delete |
{- "channels": [
- 1
], - "identities": [
- {
- "id": [
- "1234"
], - "email": [
- "user@company.com"
], - "sms": [
- "+3580101234567"
], - "extra1": [
- "extra1"
]
}
]
}{- "handle": "1234"
}Check if a delete request is finished.
| handle | string The handle returned as response from the initial request |
{- "handle": "1234"
}{- "ready": true
}Returns LianaAutomation system id of the deleted items.
| handle | string The handle returned as response from the initial request |
{- "handle": "1234"
}{- "deleted": [
- [
- 1,
- 2,
- 3
]
]
}Make a request to export the contents of a given segment.
Segment ID
1{- "handle": "1234"
}Check if an export request is ready.
| handle | string The handle returned as response from the initial request |
{- "handle": "1234"
}{- "ready": true
}Export results of a finished export request.
| handle | string The handle returned as response from the initial request |
{- "handle": "1234"
}[- {
- "email": "user@company.com",
- "sms": "+3580101234567",
- "system-event-date": "2019-08-24T14:15:22Z",
- "formsend-sentfrom": "NULL",
- "id": 1234
}
]List of channels. Depending on channel type different fields will be returned.
[- {
- "id": 1,
- "name": "Automation",
- "color": "#37aef3",
- "front_url": "//t.lianacem.com",
- "icon": "",
- "tracking_enabled": true,
- "notes": "",
- "system_name": "",
- "tracking_js": "",
- "import_js": "",
- "verbs": {
- "contact": true,
- "formsend": false
}, - "type": "empty",
- "default_url": "",
- "events": 100
}
]Create channel. Only channels without type can be created.
| name required | string |
| color | string |
| tracking_enabled | boolean Default: false |
| notes | string |
{- "name": "Automation",
- "color": "#37aef3",
- "tracking_enabled": true,
- "notes": ""
}{- "id": 1,
- "name": "Automation",
- "color": "#37aef3",
- "front_url": "//t.lianacem.com",
- "icon": "",
- "tracking_enabled": true,
- "notes": "",
- "system_name": "",
- "tracking_js": "",
- "import_js": "",
- "verbs": {
- "contact": true,
- "formsend": false
}, - "type": "empty",
- "default_url": "",
- "events": 100
}Edit channel. Only channels without type can be edited.
| id required | integer |
| name | string |
| color | string |
| tracking_enabled | boolean Default: false |
| notes | string |
{- "id": 10,
- "name": "Automation",
- "color": "#37aef3",
- "tracking_enabled": true,
- "notes": ""
}{- "id": 1,
- "name": "Automation",
- "color": "#37aef3",
- "front_url": "//t.lianacem.com",
- "icon": "",
- "tracking_enabled": true,
- "notes": "",
- "system_name": "",
- "tracking_js": "",
- "import_js": "",
- "verbs": {
- "contact": true,
- "formsend": false
}, - "type": "empty",
- "default_url": "",
- "events": 100
}Delete channel. Channel can be deleted only if it doesn't have type, events and is not used in any automation or segment.
| id required | integer |
{- "id": 10
}{- "succeed": true
}Make a automations report request
| start_date required | string |
| end_date required | string |
{- "start_date": "2022-02-01",
- "end_date": "2022-02-25"
}{- "handle": "1234"
}Check if a requested automations report is completed.
| handle | string The handle returned as response from the initial request |
{- "handle": "1234"
}{- "ready": true
}Fetch results of a finished request
| handle | string The handle returned as response from the initial request |
{- "handle": "1234"
}[- {
- "id": 91,
- "name": "Automation",
- "enabled": true,
- "summary": {
- "bounces": 0,
- "clickers": 0,
- "clicks": 0,
- "ctr": 0,
- "engagement": 5,
- "non-openers": 19,
- "openers": 81,
- "opens": 100,
- "or": 81,
- "persons": 100,
- "person-engagement": 0,
- "sent": 400
}, - "messages": [
- {
- "id": 58,
- "subject": "Message subject",
- "rates": {
- "current": {
- "mailopen": {
- "avg": 41.5,
- "total": 41.5,
- "trend": -88
}, - "maillink": {
- "avg": 0,
- "total": 0,
- "trend": 0
}
}, - "month": {
- "mailopen": {
- "avg": 0,
- "total": 0,
- "trend": 0
}, - "maillink": {
- "avg": 0,
- "total": 0,
- "trend": 0
}
}
}, - "graph": {
- "mailsent": {
- "counts": [
- 0,
- 1,
- 1
], - "total_count": 2,
- "highest_count": 2
}, - "mailopen": {
- "counts": [
- 1,
- 0,
- 2
], - "ratios": [
- 20.5,
- 0,
- 1.1
], - "total_count": 3,
- "highest_count": 2,
- "highest_ratio": 20.5
}, - "maillink": {
- "counts": [
- 1,
- 0,
- 1
], - "ratios": [
- 15.5,
- 0,
- 2.5
], - "total_count": 2,
- "highest_count": 1,
- "highest_ratio": 15.5
}, - "categories": [
- "2020-06-01T00:00:00+03:00",
- "2020-07-01T00:00:00+03:00",
- "2020-08-01T00:00:00+03:00"
], - "highest_count": 3,
- "highest_ratio": 20.5,
- "interval": "month"
}, - "summary": {
- "bounces": 0,
- "clickers": 0,
- "clicks": 0,
- "ctr": 0,
- "engagement": 5,
- "non-openers": 19,
- "openers": 81,
- "opens": 100,
- "or": 81,
- "person-engagement": 0,
- "persons": 100,
- "sent": 400
}
}
]
}
]{- "installation_name": "LianaAutomation",
}