Developers
Developers
Objective
Being very clear and focused on your goals with customers is critical, and now you can track objectives and the health per objective.
Pro-tip: use your average Objective health in the Health Score!
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
name | Yes | string | Objective name. |
health | number | Objective health. | |
companyId | Yes | objectId | Related company id (planhat identifier). |
companyName | string | Company name. (Autogenerated). | |
externalId | string | The objective id in your own system. | |
sourceId | string | The objective id from an integration (Sales Force, Hubspot, etc). | |
custom | object | Custom object with your custom properties. |
Being very clear and focused on your goals with customers is critical, and now you can track objectives and the health per objective.
Pro-tip: use your average Objective health in the Health Score!
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
name | Yes | string | Objective name. |
health | number | Objective health. | |
companyId | Yes | objectId | Related company id (planhat identifier). |
companyName | string | Company name. (Autogenerated). | |
externalId | string | The objective id in your own system. | |
sourceId | string | The objective id from an integration (Sales Force, Hubspot, etc). | |
custom | object | Custom object with your custom properties. |
Being very clear and focused on your goals with customers is critical, and now you can track objectives and the health per objective.
Pro-tip: use your average Objective health in the Health Score!
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
name | Yes | string | Objective name. |
health | number | Objective health. | |
companyId | Yes | objectId | Related company id (planhat identifier). |
companyName | string | Company name. (Autogenerated). | |
externalId | string | The objective id in your own system. | |
sourceId | string | The objective id from an integration (Sales Force, Hubspot, etc). | |
custom | object | Custom object with your custom properties. |
Create objective
To create an objective 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/objectives' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Objective name",
"health": 5,
"companyId": "60df26bfa259250cba9cf816",
"externalId": 1234,
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
}
}'
Example Response
'{
"_id": "60faeda853b8f717ebe36146",
"name": "Objective name",
"health": 5,
"companyId": "60df26bfa259250cba9cf816",
"externalId": "1234",
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
},
"companyName": "Test Company"
}'Create objective
To create an objective 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/objectives' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Objective name",
"health": 5,
"companyId": "60df26bfa259250cba9cf816",
"externalId": 1234,
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
}
}'
Example Response
'{
"_id": "60faeda853b8f717ebe36146",
"name": "Objective name",
"health": 5,
"companyId": "60df26bfa259250cba9cf816",
"externalId": "1234",
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
},
"companyName": "Test Company"
}'Create objective
To create an objective 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/objectives' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Objective name",
"health": 5,
"companyId": "60df26bfa259250cba9cf816",
"externalId": 1234,
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
}
}'
Example Response
'{
"_id": "60faeda853b8f717ebe36146",
"name": "Objective name",
"health": 5,
"companyId": "60df26bfa259250cba9cf816",
"externalId": "1234",
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
},
"companyName": "Test Company"
}'Update objective
To update an objective it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to update using the objective 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/objectives/60faeda853b8f717ebe36146' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Objective name 2"
}'
Example Response
'{
"_id": "60ff061d681a6b4da9248694",
"name": "Objective name 2",
"health": 5,
"companyId": "60df26bfa259250cba9cf816",
"externalId": "12323",
"companyName": "Test Company",
"__v": 0,
"sourceId": "12323"
}'Update objective
To update an objective it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to update using the objective 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/objectives/60faeda853b8f717ebe36146' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Objective name 2"
}'
Example Response
'{
"_id": "60ff061d681a6b4da9248694",
"name": "Objective name 2",
"health": 5,
"companyId": "60df26bfa259250cba9cf816",
"externalId": "12323",
"companyName": "Test Company",
"__v": 0,
"sourceId": "12323"
}'Update objective
To update an objective it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to update using the objective 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/objectives/60faeda853b8f717ebe36146' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Objective name 2"
}'
Example Response
'{
"_id": "60ff061d681a6b4da9248694",
"name": "Objective name 2",
"health": 5,
"companyId": "60df26bfa259250cba9cf816",
"externalId": "12323",
"companyName": "Test Company",
"__v": 0,
"sourceId": "12323"
}'Get objectives by ID
To get a specific objective it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get an objective 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/objectives/5ffcce42ad67267f66741147' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_id": "5ffcce42ad67267f66741147",
"companyId": "56bccdf554d64d837d01be9d",
"companyName": "Tenet",
"name": "Gold objective",
"health": 5,
"__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 objectives by ID
To get a specific objective it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get an objective 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/objectives/5ffcce42ad67267f66741147' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_id": "5ffcce42ad67267f66741147",
"companyId": "56bccdf554d64d837d01be9d",
"companyName": "Tenet",
"name": "Gold objective",
"health": 5,
"__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 objectives by ID
To get a specific objective it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get an objective 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/objectives/5ffcce42ad67267f66741147' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_id": "5ffcce42ad67267f66741147",
"companyId": "56bccdf554d64d837d01be9d",
"companyName": "Tenet",
"name": "Gold objective",
"health": 5,
"__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 objectives List
When fetching multiple objectives 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/objectives?limit=2&offset=0&sort=-name&select=_id,name,health,companyId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "60fb0869694ea374023924cb",
"companyId": "56bccdf554d64d837d01be4a",
"name": "ZPA Product",
"health": 5
},
{
"_id": "601c0a253e5ed41388982528",
"companyId": "6011889f52181c5640bf41ba",
"name": "Trello.io",
"health": 4
}
]'Get objectives List
When fetching multiple objectives 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/objectives?limit=2&offset=0&sort=-name&select=_id,name,health,companyId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "60fb0869694ea374023924cb",
"companyId": "56bccdf554d64d837d01be4a",
"name": "ZPA Product",
"health": 5
},
{
"_id": "601c0a253e5ed41388982528",
"companyId": "6011889f52181c5640bf41ba",
"name": "Trello.io",
"health": 4
}
]'Get objectives List
When fetching multiple objectives 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/objectives?limit=2&offset=0&sort=-name&select=_id,name,health,companyId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "60fb0869694ea374023924cb",
"companyId": "56bccdf554d64d837d01be4a",
"name": "ZPA Product",
"health": 5
},
{
"_id": "601c0a253e5ed41388982528",
"companyId": "6011889f52181c5640bf41ba",
"name": "Trello.io",
"health": 4
}
]'Delete objectives
To delete an objective 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/objectives/60faeda853b8f717ebe36146' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'Delete objectives
To delete an objective 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/objectives/60faeda853b8f717ebe36146' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'Delete objectives
To delete an objective 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/objectives/60faeda853b8f717ebe36146' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'Bulk Upsert objectives
To create an objective 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 objective 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 objectives 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/objectives' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"name": "Objective name",
"companyId": "60df26bfa259250cba9cf816",
"health": 4,
"externalId": 1234,
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
}
},
{
"name": "Objective name 2",
"companyId": "60df26bfa259250cba9cf816",
"health": 5,
"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 objectives
To create an objective 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 objective 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 objectives 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/objectives' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"name": "Objective name",
"companyId": "60df26bfa259250cba9cf816",
"health": 4,
"externalId": 1234,
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
}
},
{
"name": "Objective name 2",
"companyId": "60df26bfa259250cba9cf816",
"health": 5,
"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 objectives
To create an objective 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 objective 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 objectives 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/objectives' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"name": "Objective name",
"companyId": "60df26bfa259250cba9cf816",
"health": 4,
"externalId": 1234,
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
}
},
{
"name": "Objective name 2",
"companyId": "60df26bfa259250cba9cf816",
"health": 5,
"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": []
}'