Planhat | The Unified Customer Platform

Developers

Company

Companies ("accounts"), are your customers. Depending on your business these might be agencies, schools, other businesses or something else. Companies can also be your previous customers and potentially future customers (prospects).

The company object is one of the most central in Planhat since most other objects relate to it, and it's frequently used to filter out other information, such as endusers, licenses, notes etc.

In Planhat it is possible have a hierarchical structure for the companies, meaning that they can be grouped into organizations with parents and children in a tree like structure.

Property	Required	Type	Description
_id		objectId	Planhat identifier.
name	Yes	string	Name of the company.
owner		objectId	The planhat user id of the Account Manager / Success Manager to whom this company belongs. See the User model section for info about how to get the user ids.
coOwner		objectId	A potential co-pilot, in case a single owner isn’t enough. See the User model section for info about how to get the user ids.
externalId		string	The company id in your own system (will help us match other data you send over such as user activities, custom metrics etc). Not strictly required but if you’ve read this far it’s most likely something you need.
sourceId		string	The company id from an integration (Sales Force, Hubspot, etc).
phase		string	Each company can be assigned a lifecycle phase in Planhat. It’s a text string that should match the name of one of the phases in Planhat. If the name doesn’t match any of the phases in Planhat it will still be saved. (Autogenerated).
status		string	Status of company should be one of the list (prospect, coming, customer, canceled, lost). (Autogenerated).
domains		array	Array of strings of company domains based on endusers emails domains. (Autogenerated).
h		integer	Health number. (Autogenerated).
hProfile		objectId	ObjectId of the current health profile. (Autogenerated).
csmScore		integer	CSM Score from 1 to 5. (Autogenerated).
mr		number	Current MRR plus the sum of NRR over the past 30 days. (Autogenerated).
nrr30		number	NRR (Sale) value Last 30. (Autogenerated).
mrrTotal		number	Accumulated MRR. (Autogenerated).
nrrTotal		number	Accumulated non-recurring revenue. (Autogenerated).
mrTotal		number	Accumulated Revenue (mrrTotal + nrrTotal). (Autogenerated).
description		string	Company description.
address		string	Company physical address.
country		string	Company country.
city		string	Company city.
zip		string	Company postal code.
phonePrimary		string	Company primary phone number.
web		string	Company web site url.
customerFrom		string	Start date of the active license. (Autogenerated).
customerTo		string	Renewal date of the active license. (Autogenerated).
alerts		array	Array of alerts notifications. (Autogenerated).
tags		array	Array of tags.
products		array	Array of strings containing the products. (Autogenerated).
licenses		array	Array of objects containing the licenses. (Autogenerated).
sales		array	Array of objects containing the sales. (Autogenerated).
createDate		string	Creation date. (Autogenerated).
lastUpdated		string	Last update date. (Autogenerated).
lastRenewal		string	Last renewal date. (Autogenerated).
renewalDaysFromNow		number	Number of days before the renewal. (Autogenerated).
lastActive		string	Last active date. (Autogenerated).
followers		array	Array of followers (users) ids.
usage		map	Object containing the usage data. (Autogenerated).
lastTouch		string	Last touch date. (Autogenerated).
lastTouchType		string	Last touch type. (Autogenerated).
lastTouchByType		object	Object containing the info of the last contact. (Autogenerated).
nextTouch		string	Date for the next schedule touch. (Autogenerated).
phaseSince		string	Date since the last phase change. (Autogenerated).
csmScoreLog		array	Array of objects containing the csm change log. (Autogenerated).
features		array	Array of objects containing success units. (Autogenerated).
sunits		map	Map object containing success units. (Autogenerated).
shareable		object	Object containing the sharable information. (Autogenerated).
lastActivities		array	Array of objects containing the last activities. (Autogenerated).
documents		array	Array of objects containing the uploaded documents. (Autogenerated).
orgRootId		objectId	Planhat ID of the top company on the organization tree. All its children must refer to the same root ID. (Autogenerated).
orgPath		string	String containing chain of objectIds joined by commas. These describe a hierarchical order of companies within the organization. The leftmost is the parent of the organization, and the last one is the direct parent of the current company. (Autogenerated).
mrr		number	Monthly company value. (Autogenerated).
arr		number	Annual company value. (Autogenerated).
orgMrr		number	MRR of the group. (Autogenerated).
orgArr		number	ARR of the group. (Autogenerated).
renewalMrr		number	Renewal monthly value. (Autogenerated).
renewalArr		number	Renewal annual value. (Autogenerated).
orgMrrTotal		number	Total Group MRR. (Autogenerated).
orgArrTotal		number	Total Group ARR. (Autogenerated).
orgHealthTotal		number	Total group health. (Autogenerated).
orgLevel		number	Level of the current company inside the organization. (Autogenerated).
orgUnits		number	Number of child companies. (Autogenerated).
custom		object	A flexible object with custom data.

The company object is one of the most central in Planhat since most other objects relate to it, and it's frequently used to filter out other information, such as endusers, licenses, notes etc.

In Planhat it is possible have a hierarchical structure for the companies, meaning that they can be grouped into organizations with parents and children in a tree like structure.

Property	Required	Type	Description
_id		objectId	Planhat identifier.
name	Yes	string	Name of the company.
owner		objectId	The planhat user id of the Account Manager / Success Manager to whom this company belongs. See the User model section for info about how to get the user ids.
coOwner		objectId	A potential co-pilot, in case a single owner isn’t enough. See the User model section for info about how to get the user ids.
externalId		string	The company id in your own system (will help us match other data you send over such as user activities, custom metrics etc). Not strictly required but if you’ve read this far it’s most likely something you need.
sourceId		string	The company id from an integration (Sales Force, Hubspot, etc).
phase		string	Each company can be assigned a lifecycle phase in Planhat. It’s a text string that should match the name of one of the phases in Planhat. If the name doesn’t match any of the phases in Planhat it will still be saved. (Autogenerated).
status		string	Status of company should be one of the list (prospect, coming, customer, canceled, lost). (Autogenerated).
domains		array	Array of strings of company domains based on endusers emails domains. (Autogenerated).
h		integer	Health number. (Autogenerated).
hProfile		objectId	ObjectId of the current health profile. (Autogenerated).
csmScore		integer	CSM Score from 1 to 5. (Autogenerated).
mr		number	Current MRR plus the sum of NRR over the past 30 days. (Autogenerated).
nrr30		number	NRR (Sale) value Last 30. (Autogenerated).
mrrTotal		number	Accumulated MRR. (Autogenerated).
nrrTotal		number	Accumulated non-recurring revenue. (Autogenerated).
mrTotal		number	Accumulated Revenue (mrrTotal + nrrTotal). (Autogenerated).
description		string	Company description.
address		string	Company physical address.
country		string	Company country.
city		string	Company city.
zip		string	Company postal code.
phonePrimary		string	Company primary phone number.
web		string	Company web site url.
customerFrom		string	Start date of the active license. (Autogenerated).
customerTo		string	Renewal date of the active license. (Autogenerated).
alerts		array	Array of alerts notifications. (Autogenerated).
tags		array	Array of tags.
products		array	Array of strings containing the products. (Autogenerated).
licenses		array	Array of objects containing the licenses. (Autogenerated).
sales		array	Array of objects containing the sales. (Autogenerated).
createDate		string	Creation date. (Autogenerated).
lastUpdated		string	Last update date. (Autogenerated).
lastRenewal		string	Last renewal date. (Autogenerated).
renewalDaysFromNow		number	Number of days before the renewal. (Autogenerated).
lastActive		string	Last active date. (Autogenerated).
followers		array	Array of followers (users) ids.
usage		map	Object containing the usage data. (Autogenerated).
lastTouch		string	Last touch date. (Autogenerated).
lastTouchType		string	Last touch type. (Autogenerated).
lastTouchByType		object	Object containing the info of the last contact. (Autogenerated).
nextTouch		string	Date for the next schedule touch. (Autogenerated).
phaseSince		string	Date since the last phase change. (Autogenerated).
csmScoreLog		array	Array of objects containing the csm change log. (Autogenerated).
features		array	Array of objects containing success units. (Autogenerated).
sunits		map	Map object containing success units. (Autogenerated).
shareable		object	Object containing the sharable information. (Autogenerated).
lastActivities		array	Array of objects containing the last activities. (Autogenerated).
documents		array	Array of objects containing the uploaded documents. (Autogenerated).
orgRootId		objectId	Planhat ID of the top company on the organization tree. All its children must refer to the same root ID. (Autogenerated).
orgPath		string	String containing chain of objectIds joined by commas. These describe a hierarchical order of companies within the organization. The leftmost is the parent of the organization, and the last one is the direct parent of the current company. (Autogenerated).
mrr		number	Monthly company value. (Autogenerated).
arr		number	Annual company value. (Autogenerated).
orgMrr		number	MRR of the group. (Autogenerated).
orgArr		number	ARR of the group. (Autogenerated).
renewalMrr		number	Renewal monthly value. (Autogenerated).
renewalArr		number	Renewal annual value. (Autogenerated).
orgMrrTotal		number	Total Group MRR. (Autogenerated).
orgArrTotal		number	Total Group ARR. (Autogenerated).
orgHealthTotal		number	Total group health. (Autogenerated).
orgLevel		number	Level of the current company inside the organization. (Autogenerated).
orgUnits		number	Number of child companies. (Autogenerated).
custom		object	A flexible object with custom data.

The company object is one of the most central in Planhat since most other objects relate to it, and it's frequently used to filter out other information, such as endusers, licenses, notes etc.

In Planhat it is possible have a hierarchical structure for the companies, meaning that they can be grouped into organizations with parents and children in a tree like structure.

Property	Required	Type	Description
_id		objectId	Planhat identifier.
name	Yes	string	Name of the company.
owner		objectId	The planhat user id of the Account Manager / Success Manager to whom this company belongs. See the User model section for info about how to get the user ids.
coOwner		objectId	A potential co-pilot, in case a single owner isn’t enough. See the User model section for info about how to get the user ids.
externalId		string	The company id in your own system (will help us match other data you send over such as user activities, custom metrics etc). Not strictly required but if you’ve read this far it’s most likely something you need.
sourceId		string	The company id from an integration (Sales Force, Hubspot, etc).
phase		string	Each company can be assigned a lifecycle phase in Planhat. It’s a text string that should match the name of one of the phases in Planhat. If the name doesn’t match any of the phases in Planhat it will still be saved. (Autogenerated).
status		string	Status of company should be one of the list (prospect, coming, customer, canceled, lost). (Autogenerated).
domains		array	Array of strings of company domains based on endusers emails domains. (Autogenerated).
h		integer	Health number. (Autogenerated).
hProfile		objectId	ObjectId of the current health profile. (Autogenerated).
csmScore		integer	CSM Score from 1 to 5. (Autogenerated).
mr		number	Current MRR plus the sum of NRR over the past 30 days. (Autogenerated).
nrr30		number	NRR (Sale) value Last 30. (Autogenerated).
mrrTotal		number	Accumulated MRR. (Autogenerated).
nrrTotal		number	Accumulated non-recurring revenue. (Autogenerated).
mrTotal		number	Accumulated Revenue (mrrTotal + nrrTotal). (Autogenerated).
description		string	Company description.
address		string	Company physical address.
country		string	Company country.
city		string	Company city.
zip		string	Company postal code.
phonePrimary		string	Company primary phone number.
web		string	Company web site url.
customerFrom		string	Start date of the active license. (Autogenerated).
customerTo		string	Renewal date of the active license. (Autogenerated).
alerts		array	Array of alerts notifications. (Autogenerated).
tags		array	Array of tags.
products		array	Array of strings containing the products. (Autogenerated).
licenses		array	Array of objects containing the licenses. (Autogenerated).
sales		array	Array of objects containing the sales. (Autogenerated).
createDate		string	Creation date. (Autogenerated).
lastUpdated		string	Last update date. (Autogenerated).
lastRenewal		string	Last renewal date. (Autogenerated).
renewalDaysFromNow		number	Number of days before the renewal. (Autogenerated).
lastActive		string	Last active date. (Autogenerated).
followers		array	Array of followers (users) ids.
usage		map	Object containing the usage data. (Autogenerated).
lastTouch		string	Last touch date. (Autogenerated).
lastTouchType		string	Last touch type. (Autogenerated).
lastTouchByType		object	Object containing the info of the last contact. (Autogenerated).
nextTouch		string	Date for the next schedule touch. (Autogenerated).
phaseSince		string	Date since the last phase change. (Autogenerated).
csmScoreLog		array	Array of objects containing the csm change log. (Autogenerated).
features		array	Array of objects containing success units. (Autogenerated).
sunits		map	Map object containing success units. (Autogenerated).
shareable		object	Object containing the sharable information. (Autogenerated).
lastActivities		array	Array of objects containing the last activities. (Autogenerated).
documents		array	Array of objects containing the uploaded documents. (Autogenerated).
orgRootId		objectId	Planhat ID of the top company on the organization tree. All its children must refer to the same root ID. (Autogenerated).
orgPath		string	String containing chain of objectIds joined by commas. These describe a hierarchical order of companies within the organization. The leftmost is the parent of the organization, and the last one is the direct parent of the current company. (Autogenerated).
mrr		number	Monthly company value. (Autogenerated).
arr		number	Annual company value. (Autogenerated).
orgMrr		number	MRR of the group. (Autogenerated).
orgArr		number	ARR of the group. (Autogenerated).
renewalMrr		number	Renewal monthly value. (Autogenerated).
renewalArr		number	Renewal annual value. (Autogenerated).
orgMrrTotal		number	Total Group MRR. (Autogenerated).
orgArrTotal		number	Total Group ARR. (Autogenerated).
orgHealthTotal		number	Total group health. (Autogenerated).
orgLevel		number	Level of the current company inside the organization. (Autogenerated).
orgUnits		number	Number of child companies. (Autogenerated).
custom		object	A flexible object with custom data.

Create company

Post

To create a company it's required to define a name.

Example Request

curl --location -g --request POST 'https://api.planhat.com/companies' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "status": "prospect",
  "name": "Tenet",
  "externalId": "Planhat-81ock9l81wl",
  "phase": "Renewal",
  "domains": [
  "abcdinc.com",
  "777.com"
  ],
  "h": 10,
  "csmScore": 4,
  "mr": 0,
  "nrr30": 0,
  "custom": {
  "CompanyTeamMembers": [
  "564b063a508f068051ee82a5",
  "56d5dd4e8422dc141913d0ab"
  ],
  "CompanyTeamMember": "564b063a508f068051ee82a5",
  "CompanyMultiList": [
  "Test2",
  "Test3"
  ],
  "CompanyList": "Test2",
  "CompanyDate": "2020-05-08T21:00:00.000Z",
  "CompanyDay": 18395,
  "CompanyBoolean": true,
  "CompanyNumber": 33,
  "CompanyRating": 4,
  "CompanyRichText": "<p>sfsdfsdfs</p><p>aSADS</p><p>SADas</p>",
  "CompanyText": "Test"
  },
  "mrrTotal": 0,
  "nrrTotal": 5555,
  "mrTotal": 5555,
  "country": "Latvia",
  "description": "<p>Up and coming tech company</p>"
 }'

Example Response

200 ok

'{
  "_id": "60ff42f8d627295c259999af",
  "shareable": {
  "team": {
  "fields": []
  },
  "enabled": false,
  "euIds": [],
  "sunits": false
  },
  "followers": [],
  "domains": [
  "abcdinc.com",
  "777.com"
  ],
  "collaborators": [],
  "products": [],
  "tags": [],
  "lastPerformedTriggers": [],
  "status": "prospect",
  "name": "Test Company",
  "externalId": "Planhat-81ock9l81wl",
  "phase": "Renewal",
  "h": 10,
  "csmScore": 4,
  "mr": 0,
  "nrr30": 0,
  "custom": {
  "CompanyRating": 4,
  "CompanyRichText": "<p>Test</p><p>rich</p><p>text</p>",
  "CompanyText": "Test"
  },
  "mrrTotal": 0,
  "nrrTotal": 5555,
  "mrTotal": 5555,
  "country": "Latvia",
  "description": "<p>Up and coming tech company</p>",
  "csting": [
  {
  "date": "2021-07-26T23:19:20.871Z",
  "score": 4
  }
  ],
  "phaseSince": "2021-07-26T23:19:20.873Z",
  "createDate": "2021-07-26T23:19:20.873Z",
  "lastUpdated": "2021-07-26T23:19:20.877Z",
  "lastTouchByType": {},
  "sales": [],
  "licenses": [],
  "features": {},
  "usage": {},
  "documents": [],
  "links": [],
  "alerts": [],
  "lastActivities": [],
  "updatedAt": "2021-07-26T23:19:20.880Z",
  "__v": 0
 }'

Create company

Post

To create a company it's required to define a name.

Example Request

curl --location -g --request POST 'https://api.planhat.com/companies' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "status": "prospect",
  "name": "Tenet",
  "externalId": "Planhat-81ock9l81wl",
  "phase": "Renewal",
  "domains": [
  "abcdinc.com",
  "777.com"
  ],
  "h": 10,
  "csmScore": 4,
  "mr": 0,
  "nrr30": 0,
  "custom": {
  "CompanyTeamMembers": [
  "564b063a508f068051ee82a5",
  "56d5dd4e8422dc141913d0ab"
  ],
  "CompanyTeamMember": "564b063a508f068051ee82a5",
  "CompanyMultiList": [
  "Test2",
  "Test3"
  ],
  "CompanyList": "Test2",
  "CompanyDate": "2020-05-08T21:00:00.000Z",
  "CompanyDay": 18395,
  "CompanyBoolean": true,
  "CompanyNumber": 33,
  "CompanyRating": 4,
  "CompanyRichText": "<p>sfsdfsdfs</p><p>aSADS</p><p>SADas</p>",
  "CompanyText": "Test"
  },
  "mrrTotal": 0,
  "nrrTotal": 5555,
  "mrTotal": 5555,
  "country": "Latvia",
  "description": "<p>Up and coming tech company</p>"
 }'

Example Response

200 ok

'{
  "_id": "60ff42f8d627295c259999af",
  "shareable": {
  "team": {
  "fields": []
  },
  "enabled": false,
  "euIds": [],
  "sunits": false
  },
  "followers": [],
  "domains": [
  "abcdinc.com",
  "777.com"
  ],
  "collaborators": [],
  "products": [],
  "tags": [],
  "lastPerformedTriggers": [],
  "status": "prospect",
  "name": "Test Company",
  "externalId": "Planhat-81ock9l81wl",
  "phase": "Renewal",
  "h": 10,
  "csmScore": 4,
  "mr": 0,
  "nrr30": 0,
  "custom": {
  "CompanyRating": 4,
  "CompanyRichText": "<p>Test</p><p>rich</p><p>text</p>",
  "CompanyText": "Test"
  },
  "mrrTotal": 0,
  "nrrTotal": 5555,
  "mrTotal": 5555,
  "country": "Latvia",
  "description": "<p>Up and coming tech company</p>",
  "csting": [
  {
  "date": "2021-07-26T23:19:20.871Z",
  "score": 4
  }
  ],
  "phaseSince": "2021-07-26T23:19:20.873Z",
  "createDate": "2021-07-26T23:19:20.873Z",
  "lastUpdated": "2021-07-26T23:19:20.877Z",
  "lastTouchByType": {},
  "sales": [],
  "licenses": [],
  "features": {},
  "usage": {},
  "documents": [],
  "links": [],
  "alerts": [],
  "lastActivities": [],
  "updatedAt": "2021-07-26T23:19:20.880Z",
  "__v": 0
 }'

Create company

Post

To create a company it's required to define a name.

Example Request

curl --location -g --request POST 'https://api.planhat.com/companies' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "status": "prospect",
  "name": "Tenet",
  "externalId": "Planhat-81ock9l81wl",
  "phase": "Renewal",
  "domains": [
  "abcdinc.com",
  "777.com"
  ],
  "h": 10,
  "csmScore": 4,
  "mr": 0,
  "nrr30": 0,
  "custom": {
  "CompanyTeamMembers": [
  "564b063a508f068051ee82a5",
  "56d5dd4e8422dc141913d0ab"
  ],
  "CompanyTeamMember": "564b063a508f068051ee82a5",
  "CompanyMultiList": [
  "Test2",
  "Test3"
  ],
  "CompanyList": "Test2",
  "CompanyDate": "2020-05-08T21:00:00.000Z",
  "CompanyDay": 18395,
  "CompanyBoolean": true,
  "CompanyNumber": 33,
  "CompanyRating": 4,
  "CompanyRichText": "<p>sfsdfsdfs</p><p>aSADS</p><p>SADas</p>",
  "CompanyText": "Test"
  },
  "mrrTotal": 0,
  "nrrTotal": 5555,
  "mrTotal": 5555,
  "country": "Latvia",
  "description": "<p>Up and coming tech company</p>"
 }'

Example Response

200 ok

'{
  "_id": "60ff42f8d627295c259999af",
  "shareable": {
  "team": {
  "fields": []
  },
  "enabled": false,
  "euIds": [],
  "sunits": false
  },
  "followers": [],
  "domains": [
  "abcdinc.com",
  "777.com"
  ],
  "collaborators": [],
  "products": [],
  "tags": [],
  "lastPerformedTriggers": [],
  "status": "prospect",
  "name": "Test Company",
  "externalId": "Planhat-81ock9l81wl",
  "phase": "Renewal",
  "h": 10,
  "csmScore": 4,
  "mr": 0,
  "nrr30": 0,
  "custom": {
  "CompanyRating": 4,
  "CompanyRichText": "<p>Test</p><p>rich</p><p>text</p>",
  "CompanyText": "Test"
  },
  "mrrTotal": 0,
  "nrrTotal": 5555,
  "mrTotal": 5555,
  "country": "Latvia",
  "description": "<p>Up and coming tech company</p>",
  "csting": [
  {
  "date": "2021-07-26T23:19:20.871Z",
  "score": 4
  }
  ],
  "phaseSince": "2021-07-26T23:19:20.873Z",
  "createDate": "2021-07-26T23:19:20.873Z",
  "lastUpdated": "2021-07-26T23:19:20.877Z",
  "lastTouchByType": {},
  "sales": [],
  "licenses": [],
  "features": {},
  "usage": {},
  "documents": [],
  "links": [],
  "alerts": [],
  "lastActivities": [],
  "updatedAt": "2021-07-26T23:19:20.880Z",
  "__v": 0
 }'

Update company

Put

To update a company it's required to pass the company _id in the request URL as a parameter.

Alternately it’s possible to update using the company 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/companies/60ff42f8d627295c259999af' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "name": "Company new name"
 }'

Example Response

200 ok

'{
  "_id": "60ff42f8d627295c259999af",
  "shareable": {
  "team": {
  "fields": []
  },
  "enabled": false,
  "euIds": [],
  "sunits": false
  },
  "followers": [],
  "domains": [
  "abcdinc.com",
  "777.com"
  ],
  "collaborators": [],
  "products": [],
  "tags": [],
  "lastPerformedTriggers": [],
  "status": "prospect",
  "name": "Company new name",
  "externalId": "Planhat-81ock9l81wl",
  "phase": "Renewal",
  "h": 10,
  "csmScore": 4,
  "mr": 0,
  "nrr30": 0,
  "custom": {
  "CompanyRating": 4,
  "CompanyRichText": "<p>Test</p><p>rich</p><p>text</p>",
  "CompanyText": "Test"
  },
  "mrrTotal": 0,
  "nrrTotal": 5555,
  "mrTotal": 5555,
  "country": "Latvia",
  "description": "<p>Up and coming tech company</p>",
  "csmScoreLog": [
  {
  "date": "2021-07-26T23:19:20.871Z",
  "score": 4
  }
  ],
  "phaseSince": "2021-07-26T23:19:20.873Z",
  "createDate": "2021-07-26T23:19:20.873Z",
  "lastUpdated": "2021-07-26T23:24:47.778Z",
  "lastTouchByType": {},
  "sales": [],
  "licenses": [],
  "features": {},
  "usage": {},
  "documents": [],
  "links": [],
  "alerts": [],
  "updatedAt": "2021-07-26T23:24:47.778Z",
  "__v": 0
 }'

Update company

Put

To update a company it's required to pass the company _id in the request URL as a parameter.

Alternately it’s possible to update using the company 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/companies/60ff42f8d627295c259999af' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "name": "Company new name"
 }'

Example Response

200 ok

'{
  "_id": "60ff42f8d627295c259999af",
  "shareable": {
  "team": {
  "fields": []
  },
  "enabled": false,
  "euIds": [],
  "sunits": false
  },
  "followers": [],
  "domains": [
  "abcdinc.com",
  "777.com"
  ],
  "collaborators": [],
  "products": [],
  "tags": [],
  "lastPerformedTriggers": [],
  "status": "prospect",
  "name": "Company new name",
  "externalId": "Planhat-81ock9l81wl",
  "phase": "Renewal",
  "h": 10,
  "csmScore": 4,
  "mr": 0,
  "nrr30": 0,
  "custom": {
  "CompanyRating": 4,
  "CompanyRichText": "<p>Test</p><p>rich</p><p>text</p>",
  "CompanyText": "Test"
  },
  "mrrTotal": 0,
  "nrrTotal": 5555,
  "mrTotal": 5555,
  "country": "Latvia",
  "description": "<p>Up and coming tech company</p>",
  "csmScoreLog": [
  {
  "date": "2021-07-26T23:19:20.871Z",
  "score": 4
  }
  ],
  "phaseSince": "2021-07-26T23:19:20.873Z",
  "createDate": "2021-07-26T23:19:20.873Z",
  "lastUpdated": "2021-07-26T23:24:47.778Z",
  "lastTouchByType": {},
  "sales": [],
  "licenses": [],
  "features": {},
  "usage": {},
  "documents": [],
  "links": [],
  "alerts": [],
  "updatedAt": "2021-07-26T23:24:47.778Z",
  "__v": 0
 }'

Update company

Put

To update a company it's required to pass the company _id in the request URL as a parameter.

Alternately it’s possible to update using the company 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/companies/60ff42f8d627295c259999af' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "name": "Company new name"
 }'

Example Response

200 ok

'{
  "_id": "60ff42f8d627295c259999af",
  "shareable": {
  "team": {
  "fields": []
  },
  "enabled": false,
  "euIds": [],
  "sunits": false
  },
  "followers": [],
  "domains": [
  "abcdinc.com",
  "777.com"
  ],
  "collaborators": [],
  "products": [],
  "tags": [],
  "lastPerformedTriggers": [],
  "status": "prospect",
  "name": "Company new name",
  "externalId": "Planhat-81ock9l81wl",
  "phase": "Renewal",
  "h": 10,
  "csmScore": 4,
  "mr": 0,
  "nrr30": 0,
  "custom": {
  "CompanyRating": 4,
  "CompanyRichText": "<p>Test</p><p>rich</p><p>text</p>",
  "CompanyText": "Test"
  },
  "mrrTotal": 0,
  "nrrTotal": 5555,
  "mrTotal": 5555,
  "country": "Latvia",
  "description": "<p>Up and coming tech company</p>",
  "csmScoreLog": [
  {
  "date": "2021-07-26T23:19:20.871Z",
  "score": 4
  }
  ],
  "phaseSince": "2021-07-26T23:19:20.873Z",
  "createDate": "2021-07-26T23:19:20.873Z",
  "lastUpdated": "2021-07-26T23:24:47.778Z",
  "lastTouchByType": {},
  "sales": [],
  "licenses": [],
  "features": {},
  "usage": {},
  "documents": [],
  "links": [],
  "alerts": [],
  "updatedAt": "2021-07-26T23:24:47.778Z",
  "__v": 0
 }'

Get Companies by ID

Get

To get a specific company it's required to pass the _id in the request URL as a parameter.

Alternately it’s possible to get a company 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/companies/61006bc89a3e0b702ed8ea49' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

'{
  "_id": "61006bc89a3e0b702ed8ea49",
  "shareable": {
  "team": {
  "fields": []
  },
  "enabled": false,
  "euIds": [],
  "sunits": false
  },
  "followers": [],
  "domains": [
  "stjohns.k12.fl.us"
  ],
  "collaborators": [],
  "products": [],
  "tags": [],
  "lastPerformedTriggers": [],
  "owner": "60ccb1c5965cc9e0f3848075",
  "custom": {
  "Days in Phase": 0,
  "Days until renewal": 364,
  "# Overdue Invoices": 1
  },
  "name": "Tenet",
  "phase": "Onboarding",
  "status": "prospect",
  "phaseSince": "2021-07-27T20:25:44.430Z",
  "sunits": {
  "5b49b52a1ac87812818de26d": {
  "status": "on",
  "default": true
  }
  },
  "createDate": "2021-07-27T20:25:44.430Z",
  "lastUpdated": "2021-08-11T16:12:41.657Z",
  "lastTouchByType": {
  "note": "2021-08-22T16:15:50.772Z"
  },
  "sales": [
  {
  "_id": "61016c80675c1b871faf2d4f",
  "value": 10000,
  "product": "Advanced Onboarding",
  "_currency": {
  "_id": "USD",
  "rate": 1,
  "symbol": "$",
  "isBase": true,
  "__v": 0,
  "overrides": {}
  },
  "salesDate": "2021-07-28T00:00:00.000Z",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "companyName": "Tenet",
  "__v": 0,
  "externalId": "sale-1234"
  }
  ],
  "licenses": [],
  "features": {},
  "usage": {},
  "csmScoreLog": [],
  "documents": [],
  "links": [],
  "alerts": [],
  "updatedAt": "2021-08-09T16:54:17.298Z",
  "__v": 0,
  "h": 3,
  "autoRenews": false,
  "customerTo": "2022-07-27T00:00:00.000Z",
  "headId": "6100772b919fd37905810fc6",
  "lastRenewal": "2021-07-27T00:00:00.000Z",
  "mr": 15000,
  "mrTotal": 15000,
  "mrr": 0,
  "mrrTotal": 0,
  "nrr30": 15000,
  "nrrTotal": 15000,
  "renewalDate": "2022-07-27T00:00:00.000Z",
  "renewalDaysFromNow": 363,
  "renewalMrr": 0,
  "nps": 8.5,
  "sourceId": "119",
  "hDiff": -2,
  "hDiffDate": "2021-08-04T20:21:24.117Z",
  "hProfile": "5f87f152f5fc6f26057ac901",
  "orgCount": 0,
  "orgPathCount": 0
 }'

Get Companies by ID

Get

To get a specific company it's required to pass the _id in the request URL as a parameter.

Alternately it’s possible to get a company 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/companies/61006bc89a3e0b702ed8ea49' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

'{
  "_id": "61006bc89a3e0b702ed8ea49",
  "shareable": {
  "team": {
  "fields": []
  },
  "enabled": false,
  "euIds": [],
  "sunits": false
  },
  "followers": [],
  "domains": [
  "stjohns.k12.fl.us"
  ],
  "collaborators": [],
  "products": [],
  "tags": [],
  "lastPerformedTriggers": [],
  "owner": "60ccb1c5965cc9e0f3848075",
  "custom": {
  "Days in Phase": 0,
  "Days until renewal": 364,
  "# Overdue Invoices": 1
  },
  "name": "Tenet",
  "phase": "Onboarding",
  "status": "prospect",
  "phaseSince": "2021-07-27T20:25:44.430Z",
  "sunits": {
  "5b49b52a1ac87812818de26d": {
  "status": "on",
  "default": true
  }
  },
  "createDate": "2021-07-27T20:25:44.430Z",
  "lastUpdated": "2021-08-11T16:12:41.657Z",
  "lastTouchByType": {
  "note": "2021-08-22T16:15:50.772Z"
  },
  "sales": [
  {
  "_id": "61016c80675c1b871faf2d4f",
  "value": 10000,
  "product": "Advanced Onboarding",
  "_currency": {
  "_id": "USD",
  "rate": 1,
  "symbol": "$",
  "isBase": true,
  "__v": 0,
  "overrides": {}
  },
  "salesDate": "2021-07-28T00:00:00.000Z",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "companyName": "Tenet",
  "__v": 0,
  "externalId": "sale-1234"
  }
  ],
  "licenses": [],
  "features": {},
  "usage": {},
  "csmScoreLog": [],
  "documents": [],
  "links": [],
  "alerts": [],
  "updatedAt": "2021-08-09T16:54:17.298Z",
  "__v": 0,
  "h": 3,
  "autoRenews": false,
  "customerTo": "2022-07-27T00:00:00.000Z",
  "headId": "6100772b919fd37905810fc6",
  "lastRenewal": "2021-07-27T00:00:00.000Z",
  "mr": 15000,
  "mrTotal": 15000,
  "mrr": 0,
  "mrrTotal": 0,
  "nrr30": 15000,
  "nrrTotal": 15000,
  "renewalDate": "2022-07-27T00:00:00.000Z",
  "renewalDaysFromNow": 363,
  "renewalMrr": 0,
  "nps": 8.5,
  "sourceId": "119",
  "hDiff": -2,
  "hDiffDate": "2021-08-04T20:21:24.117Z",
  "hProfile": "5f87f152f5fc6f26057ac901",
  "orgCount": 0,
  "orgPathCount": 0
 }'

Get Companies by ID

Get

To get a specific company it's required to pass the _id in the request URL as a parameter.

Alternately it’s possible to get a company 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/companies/61006bc89a3e0b702ed8ea49' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

'{
  "_id": "61006bc89a3e0b702ed8ea49",
  "shareable": {
  "team": {
  "fields": []
  },
  "enabled": false,
  "euIds": [],
  "sunits": false
  },
  "followers": [],
  "domains": [
  "stjohns.k12.fl.us"
  ],
  "collaborators": [],
  "products": [],
  "tags": [],
  "lastPerformedTriggers": [],
  "owner": "60ccb1c5965cc9e0f3848075",
  "custom": {
  "Days in Phase": 0,
  "Days until renewal": 364,
  "# Overdue Invoices": 1
  },
  "name": "Tenet",
  "phase": "Onboarding",
  "status": "prospect",
  "phaseSince": "2021-07-27T20:25:44.430Z",
  "sunits": {
  "5b49b52a1ac87812818de26d": {
  "status": "on",
  "default": true
  }
  },
  "createDate": "2021-07-27T20:25:44.430Z",
  "lastUpdated": "2021-08-11T16:12:41.657Z",
  "lastTouchByType": {
  "note": "2021-08-22T16:15:50.772Z"
  },
  "sales": [
  {
  "_id": "61016c80675c1b871faf2d4f",
  "value": 10000,
  "product": "Advanced Onboarding",
  "_currency": {
  "_id": "USD",
  "rate": 1,
  "symbol": "$",
  "isBase": true,
  "__v": 0,
  "overrides": {}
  },
  "salesDate": "2021-07-28T00:00:00.000Z",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "companyName": "Tenet",
  "__v": 0,
  "externalId": "sale-1234"
  }
  ],
  "licenses": [],
  "features": {},
  "usage": {},
  "csmScoreLog": [],
  "documents": [],
  "links": [],
  "alerts": [],
  "updatedAt": "2021-08-09T16:54:17.298Z",
  "__v": 0,
  "h": 3,
  "autoRenews": false,
  "customerTo": "2022-07-27T00:00:00.000Z",
  "headId": "6100772b919fd37905810fc6",
  "lastRenewal": "2021-07-27T00:00:00.000Z",
  "mr": 15000,
  "mrTotal": 15000,
  "mrr": 0,
  "mrrTotal": 0,
  "nrr30": 15000,
  "nrrTotal": 15000,
  "renewalDate": "2022-07-27T00:00:00.000Z",
  "renewalDaysFromNow": 363,
  "renewalMrr": 0,
  "nps": 8.5,
  "sourceId": "119",
  "hDiff": -2,
  "hDiffDate": "2021-08-04T20:21:24.117Z",
  "hProfile": "5f87f152f5fc6f26057ac901",
  "orgCount": 0,
  "orgPathCount": 0
 }'

get Companies List

Get

When fetching multiple companies there are some options that can be used via query params:

companyId: Filter using company id. Multiple ids can be used separating them by commas.
limit: Limit the list length. Default as 100, max. 5000.
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/companies?limit=2&offset=0&sort=name' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

'[
  {
  "_id": "61002458cb43626b3a7fb186",
  "shareable": {
  "team": {
  "fields": []
  },
  "enabled": false,
  "euIds": [],
  "sunits": false
  },
  "domains": [
  "https://google.lv",
  "https://draugiem.lv"
  ],
  "tags": [
  "test",
  "test2"
  ],
  "owner": null,
  "coOwner": null,
  "externalId": "23z887cpocs",
  "sourceId": "23z887cpocs",
  "phase": "Onboarding",
  "status": "prospect",
  "h": 3,
  "csmScore": 3,
  "mr": 2,
  "nrr30": 3,
  "mrrTotal": 4,
  "mrTotal": 5,
  "name": "Altus",
  "phaseSince": "2021-07-27T15:20:56.552Z",
  "features": {},
  "usage": {},
  "alerts": [],
  "custom": {
  "Days in Phase": 0,
  "MRR_PLUS_TWOkwu7xl5ziq": 6
  }
  },
  {
  "_id": "6100186428706a6646358453",
  "shareable": {
  "team": {
  "fields": []
  },
  "enabled": false,
  "euIds": [],
  "sunits": false
  },
  "domains": [
  "https://google.lv",
  "https://draugiem.lv"
  ],
  "tags": [
  "test",
  "test2"
  ],
  "owner": null,
  "coOwner": null,
  "externalId": "3mfo0a71pa7",
  "sourceId": "3mfo0a71pa7",
  "phase": "Onboarding",
  "status": "prospect",
  "h": 3,
  "csmScore": 3,
  "mr": 2,
  "nrr30": 3,
  "mrrTotal": 4,
  "mrTotal": 5,
  "name": "Beta",
  "phaseSince": "2021-07-27T14:29:56.119Z",
  "features": {},
  "usage": {},
  "alerts": [],
  "custom": {
  "Days in Phase": 0,
  "MRR_PLUS_TWOkwu7xl5ziq": 6
  }
  }
 ]'

get Companies List

Get

When fetching multiple companies there are some options that can be used via query params:

companyId: Filter using company id. Multiple ids can be used separating them by commas.
limit: Limit the list length. Default as 100, max. 5000.
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/companies?limit=2&offset=0&sort=name' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

'[
  {
  "_id": "61002458cb43626b3a7fb186",
  "shareable": {
  "team": {
  "fields": []
  },
  "enabled": false,
  "euIds": [],
  "sunits": false
  },
  "domains": [
  "https://google.lv",
  "https://draugiem.lv"
  ],
  "tags": [
  "test",
  "test2"
  ],
  "owner": null,
  "coOwner": null,
  "externalId": "23z887cpocs",
  "sourceId": "23z887cpocs",
  "phase": "Onboarding",
  "status": "prospect",
  "h": 3,
  "csmScore": 3,
  "mr": 2,
  "nrr30": 3,
  "mrrTotal": 4,
  "mrTotal": 5,
  "name": "Altus",
  "phaseSince": "2021-07-27T15:20:56.552Z",
  "features": {},
  "usage": {},
  "alerts": [],
  "custom": {
  "Days in Phase": 0,
  "MRR_PLUS_TWOkwu7xl5ziq": 6
  }
  },
  {
  "_id": "6100186428706a6646358453",
  "shareable": {
  "team": {
  "fields": []
  },
  "enabled": false,
  "euIds": [],
  "sunits": false
  },
  "domains": [
  "https://google.lv",
  "https://draugiem.lv"
  ],
  "tags": [
  "test",
  "test2"
  ],
  "owner": null,
  "coOwner": null,
  "externalId": "3mfo0a71pa7",
  "sourceId": "3mfo0a71pa7",
  "phase": "Onboarding",
  "status": "prospect",
  "h": 3,
  "csmScore": 3,
  "mr": 2,
  "nrr30": 3,
  "mrrTotal": 4,
  "mrTotal": 5,
  "name": "Beta",
  "phaseSince": "2021-07-27T14:29:56.119Z",
  "features": {},
  "usage": {},
  "alerts": [],
  "custom": {
  "Days in Phase": 0,
  "MRR_PLUS_TWOkwu7xl5ziq": 6
  }
  }
 ]'

get Companies List

Get

When fetching multiple companies there are some options that can be used via query params:

companyId: Filter using company id. Multiple ids can be used separating them by commas.
limit: Limit the list length. Default as 100, max. 5000.
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/companies?limit=2&offset=0&sort=name' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

'[
  {
  "_id": "61002458cb43626b3a7fb186",
  "shareable": {
  "team": {
  "fields": []
  },
  "enabled": false,
  "euIds": [],
  "sunits": false
  },
  "domains": [
  "https://google.lv",
  "https://draugiem.lv"
  ],
  "tags": [
  "test",
  "test2"
  ],
  "owner": null,
  "coOwner": null,
  "externalId": "23z887cpocs",
  "sourceId": "23z887cpocs",
  "phase": "Onboarding",
  "status": "prospect",
  "h": 3,
  "csmScore": 3,
  "mr": 2,
  "nrr30": 3,
  "mrrTotal": 4,
  "mrTotal": 5,
  "name": "Altus",
  "phaseSince": "2021-07-27T15:20:56.552Z",
  "features": {},
  "usage": {},
  "alerts": [],
  "custom": {
  "Days in Phase": 0,
  "MRR_PLUS_TWOkwu7xl5ziq": 6
  }
  },
  {
  "_id": "6100186428706a6646358453",
  "shareable": {
  "team": {
  "fields": []
  },
  "enabled": false,
  "euIds": [],
  "sunits": false
  },
  "domains": [
  "https://google.lv",
  "https://draugiem.lv"
  ],
  "tags": [
  "test",
  "test2"
  ],
  "owner": null,
  "coOwner": null,
  "externalId": "3mfo0a71pa7",
  "sourceId": "3mfo0a71pa7",
  "phase": "Onboarding",
  "status": "prospect",
  "h": 3,
  "csmScore": 3,
  "mr": 2,
  "nrr30": 3,
  "mrrTotal": 4,
  "mrTotal": 5,
  "name": "Beta",
  "phaseSince": "2021-07-27T14:29:56.119Z",
  "features": {},
  "usage": {},
  "alerts": [],
  "custom": {
  "Days in Phase": 0,
  "MRR_PLUS_TWOkwu7xl5ziq": 6
  }
  }
 ]'

get Companies Lean List

Get

When you need a lightweight list of all companies in Planhat to match against your own ids etc. For each company profile in Planhat you'll get back the Planhat Id, External Id, Source ID (eg Salesforce) as well as the name.

When fetching lean companies there are some options that can be used via query params:

externalId: Company externalId.
sourceId: Company sourceId.
status: Company status, e.g. "lost", "prospect".

Example Request

curl --location -g --request GET 'https://api.planhat.com/leancompanies?status=prospect,lost' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

'[
  {
  "_id": "56bccdf554d64d837d01be8c",
  "name": "Chevron",
  "externalId": "chevron",
  "sourceId": "0012000001UchdsAAB"
  },
  {
  "_id": "56ccc2d39b760ff232295798",
  "sourceId": "0012000001Tjy5xAAB",
  "name": "United Oil & Gas, Singapore",
  "externalId": "CD355120-B"
  },
  {
  "_id": "56bccdf554d64d837d01be63",
  "name": "Burger King",
  "externalId": "",
  "sourceId": "0012000001VKEiVAAX"
  },
  {
  "_id": "56bccdf554d64d837d01be4e",
  "name": "McDonalds",
  "externalId": "mcdonalds",
  "sourceId": "0012000001TwtO7AAJ"
  }
 ]

get Companies Lean List

Get

When fetching lean companies there are some options that can be used via query params:

externalId: Company externalId.
sourceId: Company sourceId.
status: Company status, e.g. "lost", "prospect".

Example Request

curl --location -g --request GET 'https://api.planhat.com/leancompanies?status=prospect,lost' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

'[
  {
  "_id": "56bccdf554d64d837d01be8c",
  "name": "Chevron",
  "externalId": "chevron",
  "sourceId": "0012000001UchdsAAB"
  },
  {
  "_id": "56ccc2d39b760ff232295798",
  "sourceId": "0012000001Tjy5xAAB",
  "name": "United Oil & Gas, Singapore",
  "externalId": "CD355120-B"
  },
  {
  "_id": "56bccdf554d64d837d01be63",
  "name": "Burger King",
  "externalId": "",
  "sourceId": "0012000001VKEiVAAX"
  },
  {
  "_id": "56bccdf554d64d837d01be4e",
  "name": "McDonalds",
  "externalId": "mcdonalds",
  "sourceId": "0012000001TwtO7AAJ"
  }
 ]

get Companies Lean List

Get

When fetching lean companies there are some options that can be used via query params:

externalId: Company externalId.
sourceId: Company sourceId.
status: Company status, e.g. "lost", "prospect".

Example Request

curl --location -g --request GET 'https://api.planhat.com/leancompanies?status=prospect,lost' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

'[
  {
  "_id": "56bccdf554d64d837d01be8c",
  "name": "Chevron",
  "externalId": "chevron",
  "sourceId": "0012000001UchdsAAB"
  },
  {
  "_id": "56ccc2d39b760ff232295798",
  "sourceId": "0012000001Tjy5xAAB",
  "name": "United Oil & Gas, Singapore",
  "externalId": "CD355120-B"
  },
  {
  "_id": "56bccdf554d64d837d01be63",
  "name": "Burger King",
  "externalId": "",
  "sourceId": "0012000001VKEiVAAX"
  },
  {
  "_id": "56bccdf554d64d837d01be4e",
  "name": "McDonalds",
  "externalId": "mcdonalds",
  "sourceId": "0012000001TwtO7AAJ"
  }
 ]

delete Companies

Delete

To delete a company 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/companies/60ff42f8d627295c259999af' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

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

delete Companies

Delete

To delete a company 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/companies/60ff42f8d627295c259999af' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

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

delete Companies

Delete

To delete a company 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/companies/60ff42f8d627295c259999af' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

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

Bulk Upsert Companies

Put

To create a company it's required to define a name.

To update a company 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 companies 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/companies' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '[
  {
  "name": "Skynet",
  "externalId": 1234,
  "custom": {
  "field": "custom field"
  }
  },
  {
  "name": "Tenet",
  "sourceId": "sfc-1235",
  "custom": {
  "field": "custom field"
  }
  }
 ]'

Example Response

200 ok

'{
  "created": 1,
  "createdErrors": [],
  "updatedErrors": [],
  "insertsKeys": [
  {
  "_id": "6100512d9a3e0b702ed8e9c8",
  "sourceId": "sfc-1235"
  }
  ],
  "updated": 1,
  "updatedErrors": [],
  "updatesKeys": [
  {
  "_id": "6011889f52181c5640bf41bb",
  "sourceId": "0012000001U28SYAAZ",
  "externalId": "1234"
  }
  ],
  "nonupdates": 0,
  "modified": [
  "6011889f52181c5640bf41bb"
  ],
  "upsertedIds": [
  "6100512d9a3e0b702ed8e9c8"
  ],
  "permissionErrors": []
 }'

Bulk Upsert Companies

Put

To create a company it's required to define a name.

To update a company 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 companies 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/companies' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '[
  {
  "name": "Skynet",
  "externalId": 1234,
  "custom": {
  "field": "custom field"
  }
  },
  {
  "name": "Tenet",
  "sourceId": "sfc-1235",
  "custom": {
  "field": "custom field"
  }
  }
 ]'

Example Response

200 ok

'{
  "created": 1,
  "createdErrors": [],
  "updatedErrors": [],
  "insertsKeys": [
  {
  "_id": "6100512d9a3e0b702ed8e9c8",
  "sourceId": "sfc-1235"
  }
  ],
  "updated": 1,
  "updatedErrors": [],
  "updatesKeys": [
  {
  "_id": "6011889f52181c5640bf41bb",
  "sourceId": "0012000001U28SYAAZ",
  "externalId": "1234"
  }
  ],
  "nonupdates": 0,
  "modified": [
  "6011889f52181c5640bf41bb"
  ],
  "upsertedIds": [
  "6100512d9a3e0b702ed8e9c8"
  ],
  "permissionErrors": []
 }'

Bulk Upsert Companies

Put

To create a company it's required to define a name.

To update a company 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 companies 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/companies' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '[
  {
  "name": "Skynet",
  "externalId": 1234,
  "custom": {
  "field": "custom field"
  }
  },
  {
  "name": "Tenet",
  "sourceId": "sfc-1235",
  "custom": {
  "field": "custom field"
  }
  }
 ]'

Example Response

200 ok

'{
  "created": 1,
  "createdErrors": [],
  "updatedErrors": [],
  "insertsKeys": [
  {
  "_id": "6100512d9a3e0b702ed8e9c8",
  "sourceId": "sfc-1235"
  }
  ],
  "updated": 1,
  "updatedErrors": [],
  "updatesKeys": [
  {
  "_id": "6011889f52181c5640bf41bb",
  "sourceId": "0012000001U28SYAAZ",
  "externalId": "1234"
  }
  ],
  "nonupdates": 0,
  "modified": [
  "6011889f52181c5640bf41bb"
  ],
  "upsertedIds": [
  "6100512d9a3e0b702ed8e9c8"
  ],
  "permissionErrors": []
 }'

Developers

API /

Company

Company

Property

Required

Type

Description

Property

Required

Type

Description

Property

Required

Type

Description

Create company

Create company

Create company

Update company

Example:

Update company

Example:

Update company

Example:

Get Companies by ID

Example:

Get Companies by ID

Example:

Get Companies by ID

Example:

get Companies List

get Companies List

get Companies List

get Companies Lean List

get Companies Lean List

get Companies Lean List

delete Companies

delete Companies

delete Companies

Bulk Upsert Companies

Bulk Upsert Companies

Bulk Upsert Companies