Developers
Developers
Project
Projects can represent many different real-world objects with a natural start and stop date. A service provider for schools may use Projects to represent classes or courses. If you're selling software to run sales competitions, then each competition may be a project.
Using custom fields you can tailor projects to your needs, and just like Assets, usage data and time series data (metrics) can be associated with your Projects.
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
name | Yes | string | Project name. |
companyId | Yes | objectId | Related company id (planhat identifier). |
companyName | string | Company name. (Autogenerated). | |
externalId | string | The project id in your own system. | |
sourceId | string | The project id from an integration (Sales Force, Hubspot, etc). | |
currency | string | The currency code, for example "USD". | |
startDate | string | The project start date in ISO format. | |
endDate | string | The project end date in ISO format. | |
mrr | number | Monthly project value. | |
arr | number | Annual project value. | |
nrr | number | Non recurrent project value. | |
custom | object | Custom object with your custom properties. |
Projects can represent many different real-world objects with a natural start and stop date. A service provider for schools may use Projects to represent classes or courses. If you're selling software to run sales competitions, then each competition may be a project.
Using custom fields you can tailor projects to your needs, and just like Assets, usage data and time series data (metrics) can be associated with your Projects.
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
name | Yes | string | Project name. |
companyId | Yes | objectId | Related company id (planhat identifier). |
companyName | string | Company name. (Autogenerated). | |
externalId | string | The project id in your own system. | |
sourceId | string | The project id from an integration (Sales Force, Hubspot, etc). | |
currency | string | The currency code, for example "USD". | |
startDate | string | The project start date in ISO format. | |
endDate | string | The project end date in ISO format. | |
mrr | number | Monthly project value. | |
arr | number | Annual project value. | |
nrr | number | Non recurrent project value. | |
custom | object | Custom object with your custom properties. |
Projects can represent many different real-world objects with a natural start and stop date. A service provider for schools may use Projects to represent classes or courses. If you're selling software to run sales competitions, then each competition may be a project.
Using custom fields you can tailor projects to your needs, and just like Assets, usage data and time series data (metrics) can be associated with your Projects.
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
name | Yes | string | Project name. |
companyId | Yes | objectId | Related company id (planhat identifier). |
companyName | string | Company name. (Autogenerated). | |
externalId | string | The project id in your own system. | |
sourceId | string | The project id from an integration (Sales Force, Hubspot, etc). | |
currency | string | The currency code, for example "USD". | |
startDate | string | The project start date in ISO format. | |
endDate | string | The project end date in ISO format. | |
mrr | number | Monthly project value. | |
arr | number | Annual project value. | |
nrr | number | Non recurrent project value. | |
custom | object | Custom object with your custom properties. |
Create project
To create a project 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/projects' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"companyId": "61006bc89a3e0b702ed8ea49",
"startDate": "2021-07-26T04:00:00.000Z",
"endDate": "2021-07-31T04:00:00.000Z",
"currency": "USD",
"mrr": 1000,
"name": "New project"
}'
Example Response
'{
"_id": "6101a50072c0e0884d5e8db1",
"companyId": "61006bc89a3e0b702ed8ea49",
"startDate": "2021-07-26T04:00:00.000Z",
"endDate": "2021-07-31T04:00:00.000Z",
"currency": "USD",
"mrr": 1000,
"name": "New project",
"companyName": "Tenet",
"__v": 0
}'Create project
To create a project 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/projects' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"companyId": "61006bc89a3e0b702ed8ea49",
"startDate": "2021-07-26T04:00:00.000Z",
"endDate": "2021-07-31T04:00:00.000Z",
"currency": "USD",
"mrr": 1000,
"name": "New project"
}'
Example Response
'{
"_id": "6101a50072c0e0884d5e8db1",
"companyId": "61006bc89a3e0b702ed8ea49",
"startDate": "2021-07-26T04:00:00.000Z",
"endDate": "2021-07-31T04:00:00.000Z",
"currency": "USD",
"mrr": 1000,
"name": "New project",
"companyName": "Tenet",
"__v": 0
}'Create project
To create a project 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/projects' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"companyId": "61006bc89a3e0b702ed8ea49",
"startDate": "2021-07-26T04:00:00.000Z",
"endDate": "2021-07-31T04:00:00.000Z",
"currency": "USD",
"mrr": 1000,
"name": "New project"
}'
Example Response
'{
"_id": "6101a50072c0e0884d5e8db1",
"companyId": "61006bc89a3e0b702ed8ea49",
"startDate": "2021-07-26T04:00:00.000Z",
"endDate": "2021-07-31T04:00:00.000Z",
"currency": "USD",
"mrr": 1000,
"name": "New project",
"companyName": "Tenet",
"__v": 0
}'Update project
To update a project it's required to pass the project _id in the request URL as a parameter.
Alternately it’s possible to update using the project 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/projects/6101a50072c0e0884d5e8db1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Big project"
}'
Example Response
'{
"_id": "6101a50072c0e0884d5e8db1",
"companyId": "61006bc89a3e0b702ed8ea49",
"startDate": "2021-07-26T04:00:00.000Z",
"endDate": "2021-07-31T04:00:00.000Z",
"currency": "USD",
"mrr": 1000,
"name": "Big project",
"companyName": "Tenet",
"__v": 0,
"custom": {
"Days until project end": 2
}
}'Update project
To update a project it's required to pass the project _id in the request URL as a parameter.
Alternately it’s possible to update using the project 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/projects/6101a50072c0e0884d5e8db1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Big project"
}'
Example Response
'{
"_id": "6101a50072c0e0884d5e8db1",
"companyId": "61006bc89a3e0b702ed8ea49",
"startDate": "2021-07-26T04:00:00.000Z",
"endDate": "2021-07-31T04:00:00.000Z",
"currency": "USD",
"mrr": 1000,
"name": "Big project",
"companyName": "Tenet",
"__v": 0,
"custom": {
"Days until project end": 2
}
}'Update project
To update a project it's required to pass the project _id in the request URL as a parameter.
Alternately it’s possible to update using the project 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/projects/6101a50072c0e0884d5e8db1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Big project"
}'
Example Response
'{
"_id": "6101a50072c0e0884d5e8db1",
"companyId": "61006bc89a3e0b702ed8ea49",
"startDate": "2021-07-26T04:00:00.000Z",
"endDate": "2021-07-31T04:00:00.000Z",
"currency": "USD",
"mrr": 1000,
"name": "Big project",
"companyName": "Tenet",
"__v": 0,
"custom": {
"Days until project end": 2
}
}'Get projects by ID
To get a specific project it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get a project 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/projects/609a88660b73992504816060' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_id": "609a88660b73992504816060",
"companyId": "609975100b73992504810554",
"companyName": "Tenet",
"name": "SAP Integration",
"__v": 0,
"startDate": "2021-05-12T03:00:00.000Z",
"custom": {
"Notes": "",
"Product": [
"Product A"
],
"Days in Phase": 0,
"NRR30": 0,
"t123": "undefined",
"Logins": 0,
"Renewal in days": -1,
"Activity Count": 0,
"Week No": 29.285714285714285
},
"mrr": 1000
}'Get projects by ID
To get a specific project it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get a project 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/projects/609a88660b73992504816060' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_id": "609a88660b73992504816060",
"companyId": "609975100b73992504810554",
"companyName": "Tenet",
"name": "SAP Integration",
"__v": 0,
"startDate": "2021-05-12T03:00:00.000Z",
"custom": {
"Notes": "",
"Product": [
"Product A"
],
"Days in Phase": 0,
"NRR30": 0,
"t123": "undefined",
"Logins": 0,
"Renewal in days": -1,
"Activity Count": 0,
"Week No": 29.285714285714285
},
"mrr": 1000
}'Get projects by ID
To get a specific project it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get a project 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/projects/609a88660b73992504816060' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_id": "609a88660b73992504816060",
"companyId": "609975100b73992504810554",
"companyName": "Tenet",
"name": "SAP Integration",
"__v": 0,
"startDate": "2021-05-12T03:00:00.000Z",
"custom": {
"Notes": "",
"Product": [
"Product A"
],
"Days in Phase": 0,
"NRR30": 0,
"t123": "undefined",
"Logins": 0,
"Renewal in days": -1,
"Activity Count": 0,
"Week No": 29.285714285714285
},
"mrr": 1000
}'Get projects List
When fetching multiple projects 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/projects?limit=2&offset=0&sort=-name&select=_id,name,companyId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "60228bae4a93f65f056d2412",
"companyId": "6022884d40bd001fb4b6e554",
"name": "Älvdalen 2"
},
{
"_id": "60228915f4d2e51f9cc29856",
"companyId": "6022884d40bd001fb4b6e554",
"name": "URL123"
}
]
Get projects List
When fetching multiple projects 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/projects?limit=2&offset=0&sort=-name&select=_id,name,companyId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "60228bae4a93f65f056d2412",
"companyId": "6022884d40bd001fb4b6e554",
"name": "Älvdalen 2"
},
{
"_id": "60228915f4d2e51f9cc29856",
"companyId": "6022884d40bd001fb4b6e554",
"name": "URL123"
}
]
Get projects List
When fetching multiple projects 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/projects?limit=2&offset=0&sort=-name&select=_id,name,companyId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "60228bae4a93f65f056d2412",
"companyId": "6022884d40bd001fb4b6e554",
"name": "Älvdalen 2"
},
{
"_id": "60228915f4d2e51f9cc29856",
"companyId": "6022884d40bd001fb4b6e554",
"name": "URL123"
}
]
Delete projects
To delete a project it's required to pass the project _id in the request URL as a parameter.
Example Request
curl --location -g --request DELETE 'https://api.planhat.com/projects/6101a50072c0e0884d5e8db1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'Delete projects
To delete a project it's required to pass the project _id in the request URL as a parameter.
Example Request
curl --location -g --request DELETE 'https://api.planhat.com/projects/6101a50072c0e0884d5e8db1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'Delete projects
To delete a project it's required to pass the project _id in the request URL as a parameter.
Example Request
curl --location -g --request DELETE 'https://api.planhat.com/projects/6101a50072c0e0884d5e8db1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'Bulk Upsert projects
To create a project 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 project 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 projects 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/projects' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"_id": "6101a50072c0e0884d5e8db1",
"mrr": 10000
},
{
"companyId": "61006bc89a3e0b702ed8ea49",
"startDate": "2021-07-25T04:00:00.000Z",
"endDate": "2021-07-30T04:00:00.000Z",
"currency": "USD",
"mrr": 5000,
"name": "Improvements"
}
]'
Example Response
'{
"created": 1,
"createdErrors": [],
"insertsKeys": [
{
"_id": "6101a93e72c0e0884d5e8e52"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"6101a93e72c0e0884d5e8e52"
],
"permissionErrors": []
}'Bulk Upsert projects
To create a project 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 project 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 projects 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/projects' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"_id": "6101a50072c0e0884d5e8db1",
"mrr": 10000
},
{
"companyId": "61006bc89a3e0b702ed8ea49",
"startDate": "2021-07-25T04:00:00.000Z",
"endDate": "2021-07-30T04:00:00.000Z",
"currency": "USD",
"mrr": 5000,
"name": "Improvements"
}
]'
Example Response
'{
"created": 1,
"createdErrors": [],
"insertsKeys": [
{
"_id": "6101a93e72c0e0884d5e8e52"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"6101a93e72c0e0884d5e8e52"
],
"permissionErrors": []
}'Bulk Upsert projects
To create a project 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 project 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 projects 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/projects' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"_id": "6101a50072c0e0884d5e8db1",
"mrr": 10000
},
{
"companyId": "61006bc89a3e0b702ed8ea49",
"startDate": "2021-07-25T04:00:00.000Z",
"endDate": "2021-07-30T04:00:00.000Z",
"currency": "USD",
"mrr": 5000,
"name": "Improvements"
}
]'
Example Response
'{
"created": 1,
"createdErrors": [],
"insertsKeys": [
{
"_id": "6101a93e72c0e0884d5e8e52"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"6101a93e72c0e0884d5e8e52"
],
"permissionErrors": []
}'