Planhat for 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.

Post

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

200 ok

'{
  "_id": "60faeda853b8f717ebe36146",
  "name": "Objective name",
  "health": 5,
  "companyId": "60df26bfa259250cba9cf816",
  "externalId": "1234",
  "sourceId": "sfc-1234",
  "custom": {
  "field": "custom field"
  },
  "companyName": "Test Company"
 }'

Post

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

200 ok

'{
  "_id": "60faeda853b8f717ebe36146",
  "name": "Objective name",
  "health": 5,
  "companyId": "60df26bfa259250cba9cf816",
  "externalId": "1234",
  "sourceId": "sfc-1234",
  "custom": {
  "field": "custom field"
  },
  "companyName": "Test Company"
 }'

Post

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

200 ok

'{
  "_id": "60faeda853b8f717ebe36146",
  "name": "Objective name",
  "health": 5,
  "companyId": "60df26bfa259250cba9cf816",
  "externalId": "1234",
  "sourceId": "sfc-1234",
  "custom": {
  "field": "custom field"
  },
  "companyName": "Test Company"
 }'

Put

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:

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

200 ok

'{
  "_id": "60ff061d681a6b4da9248694",
  "name": "Objective name 2",
  "health": 5,
  "companyId": "60df26bfa259250cba9cf816",
  "externalId": "12323",
  "companyName": "Test Company",
  "__v": 0,
  "sourceId": "12323"
 }'

Put

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:

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

200 ok

'{
  "_id": "60ff061d681a6b4da9248694",
  "name": "Objective name 2",
  "health": 5,
  "companyId": "60df26bfa259250cba9cf816",
  "externalId": "12323",
  "companyName": "Test Company",
  "__v": 0,
  "sourceId": "12323"
 }'

Put

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:

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

200 ok

'{
  "_id": "60ff061d681a6b4da9248694",
  "name": "Objective name 2",
  "health": 5,
  "companyId": "60df26bfa259250cba9cf816",
  "externalId": "12323",
  "companyName": "Test Company",
  "__v": 0,
  "sourceId": "12323"
 }'

Get

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:

Example Request

curl --location -g --request GET 'https://api.planhat.com/objectives/5ffcce42ad67267f66741147' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

'{
  "_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

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:

Example Request

curl --location -g --request GET 'https://api.planhat.com/objectives/5ffcce42ad67267f66741147' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

'{
  "_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

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:

Example Request

curl --location -g --request GET 'https://api.planhat.com/objectives/5ffcce42ad67267f66741147' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

'{
  "_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

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

200 ok

'[
  {
  "_id": "60fb0869694ea374023924cb",
  "companyId": "56bccdf554d64d837d01be4a",
  "name": "ZPA Product",
  "health": 5
  },
  {
  "_id": "601c0a253e5ed41388982528",
  "companyId": "6011889f52181c5640bf41ba",
  "name": "Trello.io",
  "health": 4
  }
 ]'

Get

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

200 ok

'[
  {
  "_id": "60fb0869694ea374023924cb",
  "companyId": "56bccdf554d64d837d01be4a",
  "name": "ZPA Product",
  "health": 5
  },
  {
  "_id": "601c0a253e5ed41388982528",
  "companyId": "6011889f52181c5640bf41ba",
  "name": "Trello.io",
  "health": 4
  }
 ]'

Get

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

200 ok

'[
  {
  "_id": "60fb0869694ea374023924cb",
  "companyId": "56bccdf554d64d837d01be4a",
  "name": "ZPA Product",
  "health": 5
  },
  {
  "_id": "601c0a253e5ed41388982528",
  "companyId": "6011889f52181c5640bf41ba",
  "name": "Trello.io",
  "health": 4
  }
 ]'

Delete

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

200 ok

'{
  "n": 1,
  "ok": 1,
  "deletedCount": 1
 }'

Delete

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

200 ok

'{
  "n": 1,
  "ok": 1,
  "deletedCount": 1
 }'

Delete

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

200 ok

'{
  "n": 1,
  "ok": 1,
  "deletedCount": 1
 }'

Put

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.

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

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

Put

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.

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

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

Put

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.

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

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

Objective

Objective

Property

Required

Type

Description

Property

Required

Type

Description

Property

Required

Type

Description

Example:

Example:

Example:

Example:

Example:

Example: