Developers
Developers
Workspace
If you work with sub-instances at your customers, e.g., connecting with different departments or with different versions of your product (think like a Workspace in Slack), then this is the object to track that engagement!
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
name | Yes | string | Workspace name. |
ownerId | objectId | Related owner id (planhat identifier). | |
companyId | Yes | objectId | Related company id (planhat identifier). |
companyName | string | Company name. (Autogenerated). | |
externalId | string | The workspace id in your own system. | |
sourceId | string | The workspace id from an integration (Sales Force, Hubspot, etc). | |
custom | object | Custom object with your custom properties. |
If you work with sub-instances at your customers, e.g., connecting with different departments or with different versions of your product (think like a Workspace in Slack), then this is the object to track that engagement!
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
name | Yes | string | Workspace name. |
ownerId | objectId | Related owner id (planhat identifier). | |
companyId | Yes | objectId | Related company id (planhat identifier). |
companyName | string | Company name. (Autogenerated). | |
externalId | string | The workspace id in your own system. | |
sourceId | string | The workspace id from an integration (Sales Force, Hubspot, etc). | |
custom | object | Custom object with your custom properties. |
If you work with sub-instances at your customers, e.g., connecting with different departments or with different versions of your product (think like a Workspace in Slack), then this is the object to track that engagement!
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
name | Yes | string | Workspace name. |
ownerId | objectId | Related owner id (planhat identifier). | |
companyId | Yes | objectId | Related company id (planhat identifier). |
companyName | string | Company name. (Autogenerated). | |
externalId | string | The workspace id in your own system. | |
sourceId | string | The workspace id from an integration (Sales Force, Hubspot, etc). | |
custom | object | Custom object with your custom properties. |
Create workspace
To create a workspace 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/workspaces' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Workspace name",
"companyId": "60df26bfa259250cba9cf816",
"ownerId": "60df26bfa259250cba8cf310",
"externalId": 1234,
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
}
}'
Example Response
'{
"_id": "60faeda853b8f717ebe36146",
"name": "Workspace name",
"companyId": "60df26bfa259250cba9cf816",
"ownerId": "60df26bfa259250cba8cf310",
"externalId": "1234",
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
},
"companyName": "Test Company"
}'
Create workspace
To create a workspace 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/workspaces' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Workspace name",
"companyId": "60df26bfa259250cba9cf816",
"ownerId": "60df26bfa259250cba8cf310",
"externalId": 1234,
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
}
}'
Example Response
'{
"_id": "60faeda853b8f717ebe36146",
"name": "Workspace name",
"companyId": "60df26bfa259250cba9cf816",
"ownerId": "60df26bfa259250cba8cf310",
"externalId": "1234",
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
},
"companyName": "Test Company"
}'
Create workspace
To create a workspace 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/workspaces' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Workspace name",
"companyId": "60df26bfa259250cba9cf816",
"ownerId": "60df26bfa259250cba8cf310",
"externalId": 1234,
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
}
}'
Example Response
'{
"_id": "60faeda853b8f717ebe36146",
"name": "Workspace name",
"companyId": "60df26bfa259250cba9cf816",
"ownerId": "60df26bfa259250cba8cf310",
"externalId": "1234",
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
},
"companyName": "Test Company"
}'
Update workspace
To update a workspace it’s required to pass the _id in the request URL as a parameter.
Alternately it’s possible to update using the workspace externalId 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/workspaces/60faeda853b8f717ebe36146' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Workspace name 2"
}'
Example Response
'{
"_id": "60ff061d681a6b4da9248694",
"name": "Workspace name 2",
"companyId": "60df26bfa259250cba9cf816",
"ownerId": "60df26bfa259250cba8cf310",
"externalId": "12323",
"companyName": "Test Company"
"__v": 0,
"sourceId": "12323"
}'
Update workspace
To update a workspace it’s required to pass the _id in the request URL as a parameter.
Alternately it’s possible to update using the workspace externalId 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/workspaces/60faeda853b8f717ebe36146' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Workspace name 2"
}'
Example Response
'{
"_id": "60ff061d681a6b4da9248694",
"name": "Workspace name 2",
"companyId": "60df26bfa259250cba9cf816",
"ownerId": "60df26bfa259250cba8cf310",
"externalId": "12323",
"companyName": "Test Company"
"__v": 0,
"sourceId": "12323"
}'
Update workspace
To update a workspace it’s required to pass the _id in the request URL as a parameter.
Alternately it’s possible to update using the workspace externalId 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/workspaces/60faeda853b8f717ebe36146' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Workspace name 2"
}'
Example Response
'{
"_id": "60ff061d681a6b4da9248694",
"name": "Workspace name 2",
"companyId": "60df26bfa259250cba9cf816",
"ownerId": "60df26bfa259250cba8cf310",
"externalId": "12323",
"companyName": "Test Company"
"__v": 0,
"sourceId": "12323"
}'
Get workspaces by ID
To get a specific workspace it’s required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get a workspace using its externalId 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/workspaces/5ffcce42ad67267f66741147' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_id": "5ffcce42ad67267f66741147",
"companyId": "56bccdf554d64d837d01be9d",
"ownerId": "60df26bfa259250cba8cf310",
"companyName": "Tenet",
"name": "Gold workspace",
"__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 workspaces by ID
To get a specific workspace it’s required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get a workspace using its externalId 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/workspaces/5ffcce42ad67267f66741147' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_id": "5ffcce42ad67267f66741147",
"companyId": "56bccdf554d64d837d01be9d",
"ownerId": "60df26bfa259250cba8cf310",
"companyName": "Tenet",
"name": "Gold workspace",
"__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 workspaces by ID
To get a specific workspace it’s required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get a workspace using its externalId 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/workspaces/5ffcce42ad67267f66741147' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_id": "5ffcce42ad67267f66741147",
"companyId": "56bccdf554d64d837d01be9d",
"ownerId": "60df26bfa259250cba8cf310",
"companyName": "Tenet",
"name": "Gold workspace",
"__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 workspaces List
When fetching multiple workspaces there are some options that can be used via query params:
companyId: Filter using company id.
limit: Limit the list length. Default is 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/workspaces?limit=2&offset=0&sort=-name&select=_id,name,companyId,ownerId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "60fb0869694ea374023924cb",
"companyId": "56bccdf554d64d837d01be4a",
"name": "ZPA Product",
"ownerId": "60df26bfa259250cba8cf310"
},
{
"_id": "601c0a253e5ed41388982528",
"companyId": "6011889f52181c5640bf41ba",
"name": "Trello.io",
"ownerId": "60df26bfa259250cba8cf310"
}
]'
Get workspaces List
When fetching multiple workspaces there are some options that can be used via query params:
companyId: Filter using company id.
limit: Limit the list length. Default is 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/workspaces?limit=2&offset=0&sort=-name&select=_id,name,companyId,ownerId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "60fb0869694ea374023924cb",
"companyId": "56bccdf554d64d837d01be4a",
"name": "ZPA Product",
"ownerId": "60df26bfa259250cba8cf310"
},
{
"_id": "601c0a253e5ed41388982528",
"companyId": "6011889f52181c5640bf41ba",
"name": "Trello.io",
"ownerId": "60df26bfa259250cba8cf310"
}
]'
Get workspaces List
When fetching multiple workspaces there are some options that can be used via query params:
companyId: Filter using company id.
limit: Limit the list length. Default is 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/workspaces?limit=2&offset=0&sort=-name&select=_id,name,companyId,ownerId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "60fb0869694ea374023924cb",
"companyId": "56bccdf554d64d837d01be4a",
"name": "ZPA Product",
"ownerId": "60df26bfa259250cba8cf310"
},
{
"_id": "601c0a253e5ed41388982528",
"companyId": "6011889f52181c5640bf41ba",
"name": "Trello.io",
"ownerId": "60df26bfa259250cba8cf310"
}
]'
Delete workspaces
To delete a workspace 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/workspaces/60faeda853b8f717ebe36146' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'
Delete workspaces
To delete a workspace 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/workspaces/60faeda853b8f717ebe36146' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'
Delete workspaces
To delete a workspace 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/workspaces/60faeda853b8f717ebe36146' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'
Bulk Upsert workspaces
To create a workspace 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 a workspace 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 workspaces 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/workspaces' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"name": "Workspace name",
"companyId": "60df26bfa259250cba9cf816",
"ownerId": "60df26bfa259250cba8cf310",
"externalId": 1234,
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
}
},
{
"name": "Workspace name 2",
"companyId": "60df26bfa259250cba9cf816",
"ownerId": "60df26bfa259250cba8cf310",
"externalId": 1235,
"sourceId": "sfc-1235",
"custom": {
"field": "custom field"
}
}
]'
Example Response
'{
"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 workspaces
To create a workspace 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 a workspace 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 workspaces 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/workspaces' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"name": "Workspace name",
"companyId": "60df26bfa259250cba9cf816",
"ownerId": "60df26bfa259250cba8cf310",
"externalId": 1234,
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
}
},
{
"name": "Workspace name 2",
"companyId": "60df26bfa259250cba9cf816",
"ownerId": "60df26bfa259250cba8cf310",
"externalId": 1235,
"sourceId": "sfc-1235",
"custom": {
"field": "custom field"
}
}
]'
Example Response
'{
"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 workspaces
To create a workspace 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 a workspace 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 workspaces 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/workspaces' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"name": "Workspace name",
"companyId": "60df26bfa259250cba9cf816",
"ownerId": "60df26bfa259250cba8cf310",
"externalId": 1234,
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
}
},
{
"name": "Workspace name 2",
"companyId": "60df26bfa259250cba9cf816",
"ownerId": "60df26bfa259250cba8cf310",
"externalId": 1235,
"sourceId": "sfc-1235",
"custom": {
"field": "custom field"
}
}
]'
Example Response
'{
"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": []
}'