Developers
Developers
Metrics
While User Activity says a lot about user engagement, it does not always reflect the value created. Dimension Data is a set of model level metrics (Company by default) to understand how well your customers are doing, and the value they get out of your service.
Depending on what metrics you pick you might either want to send it as it happens or once a day. Number of user logins for example. You could either send a post every time a user logs in, or you could save logins at your end and send the total count for the day to Planhat once a day. Typically the more granular data you send to Planhat, the more options you’ll have to crunch that data later.
Note: The endpoint accepts either a single object or an array, which can be useful if you run a batch update with some interval, or if you initially would like to load historical data.
Note: Regardless your location the base URL for User Tracking events is always https://analytics.planhat.com.
In table below you can get some of the field description for request.
Property | Required | Type | Description |
|---|---|---|---|
dimensionId | Yes | string | Any string without spaces or special characters. If you're sending "Share of Active Users" a good dimensionId might be "activeusershare". It is not displayed in Planhat but will be used when building Health Metrics in Planhat. |
value | Yes | number | The raw (number) value you would like to set. |
externalId | Yes | string | This is the model (company by default) external id in your systems. For this to work the objects in Planhat will need to have this externalId set. |
model | string | Company (default), EndUser, Asset and Project models are supported. | |
date | string | Pass a valid ISO format date string to specify the date of the event. If none is provided we will use the time the request was received. |
While User Activity says a lot about user engagement, it does not always reflect the value created. Dimension Data is a set of model level metrics (Company by default) to understand how well your customers are doing, and the value they get out of your service.
Depending on what metrics you pick you might either want to send it as it happens or once a day. Number of user logins for example. You could either send a post every time a user logs in, or you could save logins at your end and send the total count for the day to Planhat once a day. Typically the more granular data you send to Planhat, the more options you’ll have to crunch that data later.
Note: The endpoint accepts either a single object or an array, which can be useful if you run a batch update with some interval, or if you initially would like to load historical data.
Note: Regardless your location the base URL for User Tracking events is always https://analytics.planhat.com.
In table below you can get some of the field description for request.
Property | Required | Type | Description |
|---|---|---|---|
dimensionId | Yes | string | Any string without spaces or special characters. If you're sending "Share of Active Users" a good dimensionId might be "activeusershare". It is not displayed in Planhat but will be used when building Health Metrics in Planhat. |
value | Yes | number | The raw (number) value you would like to set. |
externalId | Yes | string | This is the model (company by default) external id in your systems. For this to work the objects in Planhat will need to have this externalId set. |
model | string | Company (default), EndUser, Asset and Project models are supported. | |
date | string | Pass a valid ISO format date string to specify the date of the event. If none is provided we will use the time the request was received. |
While User Activity says a lot about user engagement, it does not always reflect the value created. Dimension Data is a set of model level metrics (Company by default) to understand how well your customers are doing, and the value they get out of your service.
Depending on what metrics you pick you might either want to send it as it happens or once a day. Number of user logins for example. You could either send a post every time a user logs in, or you could save logins at your end and send the total count for the day to Planhat once a day. Typically the more granular data you send to Planhat, the more options you’ll have to crunch that data later.
Note: The endpoint accepts either a single object or an array, which can be useful if you run a batch update with some interval, or if you initially would like to load historical data.
Note: Regardless your location the base URL for User Tracking events is always https://analytics.planhat.com.
In table below you can get some of the field description for request.
Property | Required | Type | Description |
|---|---|---|---|
dimensionId | Yes | string | Any string without spaces or special characters. If you're sending "Share of Active Users" a good dimensionId might be "activeusershare". It is not displayed in Planhat but will be used when building Health Metrics in Planhat. |
value | Yes | number | The raw (number) value you would like to set. |
externalId | Yes | string | This is the model (company by default) external id in your systems. For this to work the objects in Planhat will need to have this externalId set. |
model | string | Company (default), EndUser, Asset and Project models are supported. | |
date | string | Pass a valid ISO format date string to specify the date of the event. If none is provided we will use the time the request was received. |
get Dimension Data
When fetching dimension data there are some options that can be used via query params:
cId: Id of company.
dimid: Id of the dimension data.
from: Days format integer representing the start day period (Days since January 1, 1970, Unix epoch).
to: Days format integer representing the end day period (Days since January 1, 1970, Unix epoch).
limit: Limit the list length.
offset: Start the list on a specific integer index.
Example Request
curl --location -g --request GET 'https://api.planhat.com/dimensiondata?cId=611547eebcdda93cc7622958&dimid=testdim&from=18858&to=18880&limit=3' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'Example Response
'[
{
"_id": "611ef080ff18a32f886e40ae",
"dimensionId": "testdim",
"time": "2021-08-20T00:00:00.000Z",
"value": 5,
"model": "Company",
"parentId": "611547eebcdda93cc7622958",
"companyId": "611547eebcdda93cc7622958",
"companyName": "Tenet"
},
{
"_id": "611ef080eb75161dc055880a",
"dimensionId": "testdim",
"time": "2021-08-20T00:00:00.000Z",
"value": 4,
"model": "Company",
"parentId": "611547eebcdda93cc7622958",
"companyId": "611547eebcdda93cc7622958",
"companyName": "Tenet"
},
{
"_id": "611ef080b067346dfd91ad22",
"dimensionId": "testdim",
"time": "2021-08-20T00:00:00.000Z",
"value": 15,
"model": "Company",
"parentId": "611547eebcdda93cc7622958",
"companyId": "611547eebcdda93cc7622958",
"companyName": "Tenet"
}
]get Dimension Data
When fetching dimension data there are some options that can be used via query params:
cId: Id of company.
dimid: Id of the dimension data.
from: Days format integer representing the start day period (Days since January 1, 1970, Unix epoch).
to: Days format integer representing the end day period (Days since January 1, 1970, Unix epoch).
limit: Limit the list length.
offset: Start the list on a specific integer index.
Example Request
curl --location -g --request GET 'https://api.planhat.com/dimensiondata?cId=611547eebcdda93cc7622958&dimid=testdim&from=18858&to=18880&limit=3' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'Example Response
'[
{
"_id": "611ef080ff18a32f886e40ae",
"dimensionId": "testdim",
"time": "2021-08-20T00:00:00.000Z",
"value": 5,
"model": "Company",
"parentId": "611547eebcdda93cc7622958",
"companyId": "611547eebcdda93cc7622958",
"companyName": "Tenet"
},
{
"_id": "611ef080eb75161dc055880a",
"dimensionId": "testdim",
"time": "2021-08-20T00:00:00.000Z",
"value": 4,
"model": "Company",
"parentId": "611547eebcdda93cc7622958",
"companyId": "611547eebcdda93cc7622958",
"companyName": "Tenet"
},
{
"_id": "611ef080b067346dfd91ad22",
"dimensionId": "testdim",
"time": "2021-08-20T00:00:00.000Z",
"value": 15,
"model": "Company",
"parentId": "611547eebcdda93cc7622958",
"companyId": "611547eebcdda93cc7622958",
"companyName": "Tenet"
}
]get Dimension Data
When fetching dimension data there are some options that can be used via query params:
cId: Id of company.
dimid: Id of the dimension data.
from: Days format integer representing the start day period (Days since January 1, 1970, Unix epoch).
to: Days format integer representing the end day period (Days since January 1, 1970, Unix epoch).
limit: Limit the list length.
offset: Start the list on a specific integer index.
Example Request
curl --location -g --request GET 'https://api.planhat.com/dimensiondata?cId=611547eebcdda93cc7622958&dimid=testdim&from=18858&to=18880&limit=3' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'Example Response
'[
{
"_id": "611ef080ff18a32f886e40ae",
"dimensionId": "testdim",
"time": "2021-08-20T00:00:00.000Z",
"value": 5,
"model": "Company",
"parentId": "611547eebcdda93cc7622958",
"companyId": "611547eebcdda93cc7622958",
"companyName": "Tenet"
},
{
"_id": "611ef080eb75161dc055880a",
"dimensionId": "testdim",
"time": "2021-08-20T00:00:00.000Z",
"value": 4,
"model": "Company",
"parentId": "611547eebcdda93cc7622958",
"companyId": "611547eebcdda93cc7622958",
"companyName": "Tenet"
},
{
"_id": "611ef080b067346dfd91ad22",
"dimensionId": "testdim",
"time": "2021-08-20T00:00:00.000Z",
"value": 15,
"model": "Company",
"parentId": "611547eebcdda93cc7622958",
"companyId": "611547eebcdda93cc7622958",
"companyName": "Tenet"
}
]Bulk Insert Metrics
To push dimension data into Planhat it is required to specify the Tenant Token (tenantUUID) in the request URL. This token is a simple UUID identifier for your tenant and it can be found in the Developer module under the Tokens section.
Example Request
curl --location -g --request POST 'https://analytics.planhat.com/dimensiondata/{{tenantUUID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"dimensionId": "flightTime",
"value": 1,
"externalId": "airbus",
"model": "Company"
},
{
"dimensionId": "debtRatio",
"value": 5.2,
"externalId": "a320",
"model": "EndUser"
}
]
Example Response
'{
"processed": 2,
"errors": []
}'Bulk Insert Metrics
To push dimension data into Planhat it is required to specify the Tenant Token (tenantUUID) in the request URL. This token is a simple UUID identifier for your tenant and it can be found in the Developer module under the Tokens section.
Example Request
curl --location -g --request POST 'https://analytics.planhat.com/dimensiondata/{{tenantUUID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"dimensionId": "flightTime",
"value": 1,
"externalId": "airbus",
"model": "Company"
},
{
"dimensionId": "debtRatio",
"value": 5.2,
"externalId": "a320",
"model": "EndUser"
}
]
Example Response
'{
"processed": 2,
"errors": []
}'Bulk Insert Metrics
To push dimension data into Planhat it is required to specify the Tenant Token (tenantUUID) in the request URL. This token is a simple UUID identifier for your tenant and it can be found in the Developer module under the Tokens section.
Example Request
curl --location -g --request POST 'https://analytics.planhat.com/dimensiondata/{{tenantUUID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"dimensionId": "flightTime",
"value": 1,
"externalId": "airbus",
"model": "Company"
},
{
"dimensionId": "debtRatio",
"value": 5.2,
"externalId": "a320",
"model": "EndUser"
}
]
Example Response
'{
"processed": 2,
"errors": []
}'