Planhat | The Unified Customer Platform

Developers

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.

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.

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.

Create asset

Post

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"
 }'

Create asset

Post

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"
 }'

Create asset

Post

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"
 }'

Update asset

Put

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:

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"
 }'

Update asset

Put

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:

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"
 }'

Update asset

Put

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:

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"
 }'

Get assets by ID

Get

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:

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
  }
 }'

Get assets by ID

Get

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:

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
  }
 }'

Get assets by ID

Get

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:

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
  }
 }'

Get assets List

Get

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"
  }
 ]

Get assets List

Get

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"
  }
 ]

Get assets List

Get

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"
  }
 ]

Delete assets

Delete

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
 }'

Delete assets

Delete

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
 }'

Delete assets

Delete

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
 }'

Bulk Upsert assets

Put

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.

Note: 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": []
 }'

Bulk Upsert assets

Put

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.

Note: 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": []
 }'

Bulk Upsert assets

Put

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.

Note: 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": []
 }'

Developers

API /

Asset

Asset

Property

Required

Type

Description

Property

Required

Type

Description

Property

Required

Type

Description

Create asset

Create asset

Create asset

Update asset

Example:

Update asset

Example:

Update asset

Example:

Get assets by ID

Example:

Get assets by ID

Example:

Get assets by ID

Example:

Get assets List

Get assets List

Get assets List

Delete assets

Delete assets

Delete assets

Bulk Upsert assets

Bulk Upsert assets

Bulk Upsert assets