Asset
Asset
Assets in Planhat can represent many different things depending on your use case. It could be drones, if you're selling a drone tracking product, or it could be instances of your product in cases where a single customer can run multiple instances of your product in parallel. Assets could also represent your different products.
More generally, Assets are "nested objects" for which you may want to track usage separately, but don't need to treat them as separate customers with individual contacts, conversations, etc.
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
companyId | Yes | objectId | Related company id (planhat identifier). |
companyName | string | Company name. (Autogenerated). | |
externalId | string | The asset id in your system. | |
sourceId | string | The id in the source system that created the asset. | |
name | Yes | string | Name of the asset. |
serialNumber | string | Serial number of the asset. | |
value | number | Value of the asset. | |
_currency | string | Currency of the asset value, for example "USD". | |
installDate | string | ISO date when the asset was installed. | |
status | string | Status of the asset (no restrictions on values, typically "Active"). | |
ownerId | objectId | ObjectId of the team member that owns the asset. | |
ownerName | string | Owner name of the asset. (Autogenerated). | |
custom | object | Custom object with your custom properties. |
Assets in Planhat can represent many different things depending on your use case. It could be drones, if you're selling a drone tracking product, or it could be instances of your product in cases where a single customer can run multiple instances of your product in parallel. Assets could also represent your different products.
More generally, Assets are "nested objects" for which you may want to track usage separately, but don't need to treat them as separate customers with individual contacts, conversations, etc.
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
companyId | Yes | objectId | Related company id (planhat identifier). |
companyName | string | Company name. (Autogenerated). | |
externalId | string | The asset id in your system. | |
sourceId | string | The id in the source system that created the asset. | |
name | Yes | string | Name of the asset. |
serialNumber | string | Serial number of the asset. | |
value | number | Value of the asset. | |
_currency | string | Currency of the asset value, for example "USD". | |
installDate | string | ISO date when the asset was installed. | |
status | string | Status of the asset (no restrictions on values, typically "Active"). | |
ownerId | objectId | ObjectId of the team member that owns the asset. | |
ownerName | string | Owner name of the asset. (Autogenerated). | |
custom | object | Custom object with your custom properties. |
Assets in Planhat can represent many different things depending on your use case. It could be drones, if you're selling a drone tracking product, or it could be instances of your product in cases where a single customer can run multiple instances of your product in parallel. Assets could also represent your different products.
More generally, Assets are "nested objects" for which you may want to track usage separately, but don't need to treat them as separate customers with individual contacts, conversations, etc.
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
companyId | Yes | objectId | Related company id (planhat identifier). |
companyName | string | Company name. (Autogenerated). | |
externalId | string | The asset id in your system. | |
sourceId | string | The id in the source system that created the asset. | |
name | Yes | string | Name of the asset. |
serialNumber | string | Serial number of the asset. | |
value | number | Value of the asset. | |
_currency | string | Currency of the asset value, for example "USD". | |
installDate | string | ISO date when the asset was installed. | |
status | string | Status of the asset (no restrictions on values, typically "Active"). | |
ownerId | objectId | ObjectId of the team member that owns the asset. | |
ownerName | string | Owner name of the asset. (Autogenerated). | |
custom | object | Custom object with your custom properties. |
To create an asset it's required to define a name and a valid companyId.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
To create an asset it's required to define a name and a valid companyId.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
Example Request
curl --location -g --request POST 'https://api.planhat.com/assets' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Asset name",
"companyId": "60df26bfa259250cba9cf816",
"externalId": 1234,
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
}
}'
Example Response
200 ok
'{
"_id": "60faeda853b8f717ebe36146",
"name": "Asset name",
"companyId": "60df26bfa259250cba9cf816",
"externalId": "1234",
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
},
"companyName": "Test Company"
}'To create an asset it's required to define a name and a valid companyId.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
To create an asset it's required to define a name and a valid companyId.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
Example Request
curl --location -g --request POST 'https://api.planhat.com/assets' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Asset name",
"companyId": "60df26bfa259250cba9cf816",
"externalId": 1234,
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
}
}'
Example Response
200 ok
'{
"_id": "60faeda853b8f717ebe36146",
"name": "Asset name",
"companyId": "60df26bfa259250cba9cf816",
"externalId": "1234",
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
},
"companyName": "Test Company"
}'To create an asset it's required to define a name and a valid companyId.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
To create an asset it's required to define a name and a valid companyId.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
Example Request
curl --location -g --request POST 'https://api.planhat.com/assets' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Asset name",
"companyId": "60df26bfa259250cba9cf816",
"externalId": 1234,
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
}
}'
Example Response
200 ok
'{
"_id": "60faeda853b8f717ebe36146",
"name": "Asset name",
"companyId": "60df26bfa259250cba9cf816",
"externalId": "1234",
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
},
"companyName": "Test Company"
}'To update an asset it's required to pass the asset _id in the request URL as a parameter.
Alternately it’s possible to update using the asset externalId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
To update an asset it's required to pass the asset _id in the request URL as a parameter.
Alternately it’s possible to update using the asset externalId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request PUT 'https://api.planhat.com/assets/60faeda853b8f717ebe36146' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Asset name 2"
}'
Example Response
200 ok
'{
"_id": "60ff061d681a6b4da9248694",
"name": "Asset name 2",
"companyId": "60df26bfa259250cba9cf816",
"externalId": "12323",
"companyName": "Test Company"
"__v": 0,
"sourceId": "12323"
}'To update an asset it's required to pass the asset _id in the request URL as a parameter.
Alternately it’s possible to update using the asset externalId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
To update an asset it's required to pass the asset _id in the request URL as a parameter.
Alternately it’s possible to update using the asset externalId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request PUT 'https://api.planhat.com/assets/60faeda853b8f717ebe36146' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Asset name 2"
}'
Example Response
200 ok
'{
"_id": "60ff061d681a6b4da9248694",
"name": "Asset name 2",
"companyId": "60df26bfa259250cba9cf816",
"externalId": "12323",
"companyName": "Test Company"
"__v": 0,
"sourceId": "12323"
}'To update an asset it's required to pass the asset _id in the request URL as a parameter.
Alternately it’s possible to update using the asset externalId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
To update an asset it's required to pass the asset _id in the request URL as a parameter.
Alternately it’s possible to update using the asset externalId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request PUT 'https://api.planhat.com/assets/60faeda853b8f717ebe36146' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Asset name 2"
}'
Example Response
200 ok
'{
"_id": "60ff061d681a6b4da9248694",
"name": "Asset name 2",
"companyId": "60df26bfa259250cba9cf816",
"externalId": "12323",
"companyName": "Test Company"
"__v": 0,
"sourceId": "12323"
}'To get a specific asset it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get an asset using its externalId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
To get a specific asset it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get an asset using its externalId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request GET 'https://api.planhat.com/assets/5ffcce42ad67267f66741147' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
200 ok
'{
"_id": "5ffcce42ad67267f66741147",
"companyId": "56bccdf554d64d837d01be9d",
"companyName": "Tenet",
"name": "Gold asset",
"__v": 0,
"custom": {
"Comments": "",
"Main Product": [
"Recipe Database"
],
"Days in Phase": 0,
"NRR30": 0,
"t123": "undefined",
"Logins": 0,
"Overall Outlet Health": 4,
"Kary FF": null
},
"externalId": "4467",
"usage": {
"6053b728fa96fa0262729a3d": 0,
"6053ba62ca3eaf023a54d268": 0
}
}'To get a specific asset it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get an asset using its externalId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
To get a specific asset it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get an asset using its externalId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request GET 'https://api.planhat.com/assets/5ffcce42ad67267f66741147' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
200 ok
'{
"_id": "5ffcce42ad67267f66741147",
"companyId": "56bccdf554d64d837d01be9d",
"companyName": "Tenet",
"name": "Gold asset",
"__v": 0,
"custom": {
"Comments": "",
"Main Product": [
"Recipe Database"
],
"Days in Phase": 0,
"NRR30": 0,
"t123": "undefined",
"Logins": 0,
"Overall Outlet Health": 4,
"Kary FF": null
},
"externalId": "4467",
"usage": {
"6053b728fa96fa0262729a3d": 0,
"6053ba62ca3eaf023a54d268": 0
}
}'To get a specific asset it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get an asset using its externalId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
To get a specific asset it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get an asset using its externalId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request GET 'https://api.planhat.com/assets/5ffcce42ad67267f66741147' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
200 ok
'{
"_id": "5ffcce42ad67267f66741147",
"companyId": "56bccdf554d64d837d01be9d",
"companyName": "Tenet",
"name": "Gold asset",
"__v": 0,
"custom": {
"Comments": "",
"Main Product": [
"Recipe Database"
],
"Days in Phase": 0,
"NRR30": 0,
"t123": "undefined",
"Logins": 0,
"Overall Outlet Health": 4,
"Kary FF": null
},
"externalId": "4467",
"usage": {
"6053b728fa96fa0262729a3d": 0,
"6053ba62ca3eaf023a54d268": 0
}
}'When fetching multiple assets there are some options that can be used via query params:
companyId: Filter using company id.
limit: Limit the list length. Default as 100, max. 2000.
offset: Start the list on a specific integer index.
sort: Sort based on a specific property. Prefix the property "-" to change the sort order.
select: Select specific properties. Multiple properties can be specified separating them by commas.
When fetching multiple assets there are some options that can be used via query params:
companyId: Filter using company id.
limit: Limit the list length. Default as 100, max. 2000.
offset: Start the list on a specific integer index.
sort: Sort based on a specific property. Prefix the property "-" to change the sort order.
select: Select specific properties. Multiple properties can be specified separating them by commas.
Example Request
curl --location -g --request GET 'https://api.planhat.com/assets?limit=2&offset=0&sort=-name&select=_id,name,companyId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
200 ok
'[
{
"_id": "60fb0869694ea374023924cb",
"companyId": "56bccdf554d64d837d01be4a",
"name": "ZPA Product"
},
{
"_id": "601c0a253e5ed41388982528",
"companyId": "6011889f52181c5640bf41ba",
"name": "Trello.io"
}
]
When fetching multiple assets there are some options that can be used via query params:
companyId: Filter using company id.
limit: Limit the list length. Default as 100, max. 2000.
offset: Start the list on a specific integer index.
sort: Sort based on a specific property. Prefix the property "-" to change the sort order.
select: Select specific properties. Multiple properties can be specified separating them by commas.
When fetching multiple assets there are some options that can be used via query params:
companyId: Filter using company id.
limit: Limit the list length. Default as 100, max. 2000.
offset: Start the list on a specific integer index.
sort: Sort based on a specific property. Prefix the property "-" to change the sort order.
select: Select specific properties. Multiple properties can be specified separating them by commas.
Example Request
curl --location -g --request GET 'https://api.planhat.com/assets?limit=2&offset=0&sort=-name&select=_id,name,companyId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
200 ok
'[
{
"_id": "60fb0869694ea374023924cb",
"companyId": "56bccdf554d64d837d01be4a",
"name": "ZPA Product"
},
{
"_id": "601c0a253e5ed41388982528",
"companyId": "6011889f52181c5640bf41ba",
"name": "Trello.io"
}
]
When fetching multiple assets there are some options that can be used via query params:
companyId: Filter using company id.
limit: Limit the list length. Default as 100, max. 2000.
offset: Start the list on a specific integer index.
sort: Sort based on a specific property. Prefix the property "-" to change the sort order.
select: Select specific properties. Multiple properties can be specified separating them by commas.
When fetching multiple assets there are some options that can be used via query params:
companyId: Filter using company id.
limit: Limit the list length. Default as 100, max. 2000.
offset: Start the list on a specific integer index.
sort: Sort based on a specific property. Prefix the property "-" to change the sort order.
select: Select specific properties. Multiple properties can be specified separating them by commas.
Example Request
curl --location -g --request GET 'https://api.planhat.com/assets?limit=2&offset=0&sort=-name&select=_id,name,companyId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
200 ok
'[
{
"_id": "60fb0869694ea374023924cb",
"companyId": "56bccdf554d64d837d01be4a",
"name": "ZPA Product"
},
{
"_id": "601c0a253e5ed41388982528",
"companyId": "6011889f52181c5640bf41ba",
"name": "Trello.io"
}
]
To delete an asset it's required to pass the _id in the request URL as a parameter.
To delete an asset it's required to pass the _id in the request URL as a parameter.
Example Request
curl --location -g --request DELETE 'https://api.planhat.com/assets/60faeda853b8f717ebe36146' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
200 ok
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'To delete an asset it's required to pass the _id in the request URL as a parameter.
To delete an asset it's required to pass the _id in the request URL as a parameter.
Example Request
curl --location -g --request DELETE 'https://api.planhat.com/assets/60faeda853b8f717ebe36146' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
200 ok
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'To delete an asset it's required to pass the _id in the request URL as a parameter.
To delete an asset it's required to pass the _id in the request URL as a parameter.
Example Request
curl --location -g --request DELETE 'https://api.planhat.com/assets/60faeda853b8f717ebe36146' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
200 ok
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'To create an asset it's required to define a name and a valid companyId.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
To update an asset it is required to specify in the payload one of the following keyables, listed in order of priority: _id, sourceId, externalId.
Since this is a bulk upsert operation it's possible to create and/or update multiple assets with the same payload.
For more details please refer to the bulk upsert section.
There is an upper limit of 5,000 items per request.
Example Request
curl --location -g --request PUT 'https://api.planhat.com/assets' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"name": "Asset name",
"companyId": "60df26bfa259250cba9cf816",
"externalId": 1234,
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
}
},
{
"name": "Asset name 2",
"companyId": "60df26bfa259250cba9cf816",
"externalId": 1235,
"sourceId": "sfc-1235",
"custom": {
"field": "custom field"
}
}
]'
Example Response
200 ok
'{
"created": 2,
"createdErrors": [],
"insertsKeys": [
{
"_id": "60fde9ad57df5b411cf39be5",
"sourceId": "sfc-1234",
"externalId": "1234"
},
{
"_id": "60fde9ad57df5b411cf39be6",
"sourceId": "sfc-1235",
"externalId": "1235"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"60fde9ad57df5b411cf39be5",
"60fde9ad57df5b411cf39be6"
],
"permissionErrors": []
}'To create an asset it's required to define a name and a valid companyId.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
To update an asset it is required to specify in the payload one of the following keyables, listed in order of priority: _id, sourceId, externalId.
Since this is a bulk upsert operation it's possible to create and/or update multiple assets with the same payload.
For more details please refer to the bulk upsert section.
There is an upper limit of 5,000 items per request.
Example Request
curl --location -g --request PUT 'https://api.planhat.com/assets' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"name": "Asset name",
"companyId": "60df26bfa259250cba9cf816",
"externalId": 1234,
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
}
},
{
"name": "Asset name 2",
"companyId": "60df26bfa259250cba9cf816",
"externalId": 1235,
"sourceId": "sfc-1235",
"custom": {
"field": "custom field"
}
}
]'
Example Response
200 ok
'{
"created": 2,
"createdErrors": [],
"insertsKeys": [
{
"_id": "60fde9ad57df5b411cf39be5",
"sourceId": "sfc-1234",
"externalId": "1234"
},
{
"_id": "60fde9ad57df5b411cf39be6",
"sourceId": "sfc-1235",
"externalId": "1235"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"60fde9ad57df5b411cf39be5",
"60fde9ad57df5b411cf39be6"
],
"permissionErrors": []
}'To create an asset it's required to define a name and a valid companyId.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
To update an asset it is required to specify in the payload one of the following keyables, listed in order of priority: _id, sourceId, externalId.
Since this is a bulk upsert operation it's possible to create and/or update multiple assets with the same payload.
For more details please refer to the bulk upsert section.
There is an upper limit of 5,000 items per request.
Example Request
curl --location -g --request PUT 'https://api.planhat.com/assets' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"name": "Asset name",
"companyId": "60df26bfa259250cba9cf816",
"externalId": 1234,
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
}
},
{
"name": "Asset name 2",
"companyId": "60df26bfa259250cba9cf816",
"externalId": 1235,
"sourceId": "sfc-1235",
"custom": {
"field": "custom field"
}
}
]'
Example Response
200 ok
'{
"created": 2,
"createdErrors": [],
"insertsKeys": [
{
"_id": "60fde9ad57df5b411cf39be5",
"sourceId": "sfc-1234",
"externalId": "1234"
},
{
"_id": "60fde9ad57df5b411cf39be6",
"sourceId": "sfc-1235",
"externalId": "1235"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"60fde9ad57df5b411cf39be5",
"60fde9ad57df5b411cf39be6"
],
"permissionErrors": []
}'