Project
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. |
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
200 ok
'{ "_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 }'
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
200 ok
'{ "_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 }'
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
200 ok
'{ "_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 }'
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
200 ok
'{ "_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 } }'
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
200 ok
'{ "_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 } }'
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
200 ok
'{ "_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 } }'
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
200 ok
'{ "_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 }'
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
200 ok
'{ "_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 }'
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
200 ok
'{ "_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 }'
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
200 ok
'[ { "_id": "60228bae4a93f65f056d2412", "companyId": "6022884d40bd001fb4b6e554", "name": "Älvdalen 2" }, { "_id": "60228915f4d2e51f9cc29856", "companyId": "6022884d40bd001fb4b6e554", "name": "URL123" } ]
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
200 ok
'[ { "_id": "60228bae4a93f65f056d2412", "companyId": "6022884d40bd001fb4b6e554", "name": "Älvdalen 2" }, { "_id": "60228915f4d2e51f9cc29856", "companyId": "6022884d40bd001fb4b6e554", "name": "URL123" } ]
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
200 ok
'[ { "_id": "60228bae4a93f65f056d2412", "companyId": "6022884d40bd001fb4b6e554", "name": "Älvdalen 2" }, { "_id": "60228915f4d2e51f9cc29856", "companyId": "6022884d40bd001fb4b6e554", "name": "URL123" } ]
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
200 ok
'{ "n": 1, "ok": 1, "deletedCount": 1 }'
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
200 ok
'{ "n": 1, "ok": 1, "deletedCount": 1 }'
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
200 ok
'{ "n": 1, "ok": 1, "deletedCount": 1 }'
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.
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
200 ok
'{ "created": 1, "createdErrors": [], "insertsKeys": [ { "_id": "6101a93e72c0e0884d5e8e52" } ], "updated": 0, "updatedErrors": [], "updatesKeys": [], "nonupdates": 0, "modified": [], "upsertedIds": [ "6101a93e72c0e0884d5e8e52" ], "permissionErrors": [] }'
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.
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
200 ok
'{ "created": 1, "createdErrors": [], "insertsKeys": [ { "_id": "6101a93e72c0e0884d5e8e52" } ], "updated": 0, "updatedErrors": [], "updatesKeys": [], "nonupdates": 0, "modified": [], "upsertedIds": [ "6101a93e72c0e0884d5e8e52" ], "permissionErrors": [] }'
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.
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
200 ok
'{ "created": 1, "createdErrors": [], "insertsKeys": [ { "_id": "6101a93e72c0e0884d5e8e52" } ], "updated": 0, "updatedErrors": [], "updatesKeys": [], "nonupdates": 0, "modified": [], "upsertedIds": [ "6101a93e72c0e0884d5e8e52" ], "permissionErrors": [] }'