Planhat for Developers

Opportunity

Opportunities in Planhat represent a sales opportunity, whether it's selling to a new customer or more commonly a chance of expanding an existing account.

Opportunities are not the same as Licenses, but when an opportunity is closed won in Planhat, there is an optional setting to generate a license based on the opportunity data.

Property	Required	Type	Description
_id		objectId	Planhat identifier.
salesStage		string	Sales stage of opportunity.
companyId	Yes	objectId	Related company id (planhat identifier).
companyName		string	Company name. (Autogenerated).
dealDate		string	Deal date in ISO format.
landingDate		string	Landing date of the opportunity in ISO format.
closeDate		string	Close date of the opportunity in ISO format.
externalId		string	The project id in your own system.
sourceId		string	The opportunity id from an integration (Salesforce, Hubspot, etc).
_currency		string	The currency code, for example "USD".
title		string	Title of sales opportunity.
ownerId		objectId	ObjectId of the team member owner of the opportunity.
mrr		number	Monthly opportunity value.
arr		number	Annual opportunity value.
nrr		number	Non recurrent value.
contractLength		integer	Contract Length (months, defaults to 12).
status		string	Status of the opportunity, could be: active, won or lost.
stageHistory		array	Array of objects containing the history of this opportunity. (Autogenerated).
custom		object	Custom object with your custom properties.

Opportunities in Planhat represent a sales opportunity, whether it's selling to a new customer or more commonly a chance of expanding an existing account.

Opportunities are not the same as Licenses, but when an opportunity is closed won in Planhat, there is an optional setting to generate a license based on the opportunity data.

Property	Required	Type	Description
_id		objectId	Planhat identifier.
salesStage		string	Sales stage of opportunity.
companyId	Yes	objectId	Related company id (planhat identifier).
companyName		string	Company name. (Autogenerated).
dealDate		string	Deal date in ISO format.
landingDate		string	Landing date of the opportunity in ISO format.
closeDate		string	Close date of the opportunity in ISO format.
externalId		string	The project id in your own system.
sourceId		string	The opportunity id from an integration (Salesforce, Hubspot, etc).
_currency		string	The currency code, for example "USD".
title		string	Title of sales opportunity.
ownerId		objectId	ObjectId of the team member owner of the opportunity.
mrr		number	Monthly opportunity value.
arr		number	Annual opportunity value.
nrr		number	Non recurrent value.
contractLength		integer	Contract Length (months, defaults to 12).
status		string	Status of the opportunity, could be: active, won or lost.
stageHistory		array	Array of objects containing the history of this opportunity. (Autogenerated).
custom		object	Custom object with your custom properties.

Opportunities in Planhat represent a sales opportunity, whether it's selling to a new customer or more commonly a chance of expanding an existing account.

Opportunities are not the same as Licenses, but when an opportunity is closed won in Planhat, there is an optional setting to generate a license based on the opportunity data.

Property	Required	Type	Description
_id		objectId	Planhat identifier.
salesStage		string	Sales stage of opportunity.
companyId	Yes	objectId	Related company id (planhat identifier).
companyName		string	Company name. (Autogenerated).
dealDate		string	Deal date in ISO format.
landingDate		string	Landing date of the opportunity in ISO format.
closeDate		string	Close date of the opportunity in ISO format.
externalId		string	The project id in your own system.
sourceId		string	The opportunity id from an integration (Salesforce, Hubspot, etc).
_currency		string	The currency code, for example "USD".
title		string	Title of sales opportunity.
ownerId		objectId	ObjectId of the team member owner of the opportunity.
mrr		number	Monthly opportunity value.
arr		number	Annual opportunity value.
nrr		number	Non recurrent value.
contractLength		integer	Contract Length (months, defaults to 12).
status		string	Status of the opportunity, could be: active, won or lost.
stageHistory		array	Array of objects containing the history of this opportunity. (Autogenerated).
custom		object	Custom object with your custom properties.

Post

To create an opportunity it's required to define a 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/opportunities' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "salesStage": "Pitched",
  "dealDate": "2021-08-03T00:00:00.000Z",
  "ownerId": "60ccb1c5965cc9e0f3848075",
  "_currency": "USD",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "title": "New opportunity",
  "recurringValue": 3000,
  "mrr": 250,
  "nrr": 500,
  "status": "active"
 }'

Example Response

200 ok

'{
  "status": "active",
  "_id": "6101e99b72c0e0884d5e9139",
  "salesStage": "Pitched",
  "dealDate": "2021-08-03T00:00:00.000Z",
  "ownerId": "60ccb1c5965cc9e0f3848075",
  "_currency": "USD",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "title": "New opportunity",
  "mrr": 250,
  "nrr": 500,
  "companyName": "Tenet",
  "stageHistory": [],
  "landingDate": "2021-07-28T23:34:51.636Z",
  "__v": 0
 }'

Post

To create an opportunity it's required to define a 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/opportunities' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "salesStage": "Pitched",
  "dealDate": "2021-08-03T00:00:00.000Z",
  "ownerId": "60ccb1c5965cc9e0f3848075",
  "_currency": "USD",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "title": "New opportunity",
  "recurringValue": 3000,
  "mrr": 250,
  "nrr": 500,
  "status": "active"
 }'

Example Response

200 ok

'{
  "status": "active",
  "_id": "6101e99b72c0e0884d5e9139",
  "salesStage": "Pitched",
  "dealDate": "2021-08-03T00:00:00.000Z",
  "ownerId": "60ccb1c5965cc9e0f3848075",
  "_currency": "USD",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "title": "New opportunity",
  "mrr": 250,
  "nrr": 500,
  "companyName": "Tenet",
  "stageHistory": [],
  "landingDate": "2021-07-28T23:34:51.636Z",
  "__v": 0
 }'

Post

To create an opportunity it's required to define a 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/opportunities' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "salesStage": "Pitched",
  "dealDate": "2021-08-03T00:00:00.000Z",
  "ownerId": "60ccb1c5965cc9e0f3848075",
  "_currency": "USD",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "title": "New opportunity",
  "recurringValue": 3000,
  "mrr": 250,
  "nrr": 500,
  "status": "active"
 }'

Example Response

200 ok

'{
  "status": "active",
  "_id": "6101e99b72c0e0884d5e9139",
  "salesStage": "Pitched",
  "dealDate": "2021-08-03T00:00:00.000Z",
  "ownerId": "60ccb1c5965cc9e0f3848075",
  "_currency": "USD",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "title": "New opportunity",
  "mrr": 250,
  "nrr": 500,
  "companyName": "Tenet",
  "stageHistory": [],
  "landingDate": "2021-07-28T23:34:51.636Z",
  "__v": 0
 }'

Put

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

Alternately it’s possible to update using the opportunity externalId adding a prefix and passing this keyable as identifier.

Example:

Example Request

curl --location -g --request PUT 'https://api.planhat.com/opportunities/6101e99b72c0e0884d5e9139' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "status": "won",
  "salesStage": "Closed won"
 }'

Example Response

200 ok

'{
  "_id": "6101e99b72c0e0884d5e9139",
  "status": "won",
  "salesStage": "Closed won",
  "dealDate": "2021-08-03T00:00:00.000Z",
  "ownerId": "60ccb1c5965cc9e0f3848075",
  "_currency": "USD",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "title": "New opportunity",
  "mrr": 250,
  "nrr": 500,
  "companyName": "Leo company",
  "stageHistory": [],
  "landingDate": "2021-07-28T23:34:51.636Z",
  "__v": 0,
  "closeDate": "2021-07-28T23:36:59.294Z"
 }'

Put

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

Alternately it’s possible to update using the opportunity externalId adding a prefix and passing this keyable as identifier.

Example:

Example Request

curl --location -g --request PUT 'https://api.planhat.com/opportunities/6101e99b72c0e0884d5e9139' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "status": "won",
  "salesStage": "Closed won"
 }'

Example Response

200 ok

'{
  "_id": "6101e99b72c0e0884d5e9139",
  "status": "won",
  "salesStage": "Closed won",
  "dealDate": "2021-08-03T00:00:00.000Z",
  "ownerId": "60ccb1c5965cc9e0f3848075",
  "_currency": "USD",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "title": "New opportunity",
  "mrr": 250,
  "nrr": 500,
  "companyName": "Leo company",
  "stageHistory": [],
  "landingDate": "2021-07-28T23:34:51.636Z",
  "__v": 0,
  "closeDate": "2021-07-28T23:36:59.294Z"
 }'

Put

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

Alternately it’s possible to update using the opportunity externalId adding a prefix and passing this keyable as identifier.

Example:

Example Request

curl --location -g --request PUT 'https://api.planhat.com/opportunities/6101e99b72c0e0884d5e9139' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "status": "won",
  "salesStage": "Closed won"
 }'

Example Response

200 ok

'{
  "_id": "6101e99b72c0e0884d5e9139",
  "status": "won",
  "salesStage": "Closed won",
  "dealDate": "2021-08-03T00:00:00.000Z",
  "ownerId": "60ccb1c5965cc9e0f3848075",
  "_currency": "USD",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "title": "New opportunity",
  "mrr": 250,
  "nrr": 500,
  "companyName": "Leo company",
  "stageHistory": [],
  "landingDate": "2021-07-28T23:34:51.636Z",
  "__v": 0,
  "closeDate": "2021-07-28T23:36:59.294Z"
 }'

Get

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

Alternately it’s possible to get an opportunity using its externalId and/or sourceId adding a prefix and passing one of these keyables as identifier.

Example:

Example Request

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

Example Response

200 ok

'{
  "_id": "58499569e2914f5171fa7f9d",
  "status": "lost",
  "companyId": "56bccdf554d64d837d01be86",
  "stageHistory": [
  {
  "stage": "opportunity",
  "to": "2016-12-08T17:16:25.153Z"
  }
  ],
  "landingDate": "2018-11-29T11:57:06.444Z",
  "comments": [],
  "__v": 0,
  "custom": null,
  "companyName": "Toyota"
 }'

Get

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

Alternately it’s possible to get an opportunity using its externalId and/or sourceId adding a prefix and passing one of these keyables as identifier.

Example:

Example Request

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

Example Response

200 ok

'{
  "_id": "58499569e2914f5171fa7f9d",
  "status": "lost",
  "companyId": "56bccdf554d64d837d01be86",
  "stageHistory": [
  {
  "stage": "opportunity",
  "to": "2016-12-08T17:16:25.153Z"
  }
  ],
  "landingDate": "2018-11-29T11:57:06.444Z",
  "comments": [],
  "__v": 0,
  "custom": null,
  "companyName": "Toyota"
 }'

Get

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

Alternately it’s possible to get an opportunity using its externalId and/or sourceId adding a prefix and passing one of these keyables as identifier.

Example:

Example Request

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

Example Response

200 ok

'{
  "_id": "58499569e2914f5171fa7f9d",
  "status": "lost",
  "companyId": "56bccdf554d64d837d01be86",
  "stageHistory": [
  {
  "stage": "opportunity",
  "to": "2016-12-08T17:16:25.153Z"
  }
  ],
  "landingDate": "2018-11-29T11:57:06.444Z",
  "comments": [],
  "__v": 0,
  "custom": null,
  "companyName": "Toyota"
 }'

Get

When fetching multiple opportunities 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/opportunities?limit=2&offset=0&sort=-mrr&select=_id,title,status' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

'[
  {
  "_id": "5ced0734861084738e27ff21",
  "status": "lost",
  "title": "P1 enabled!"
  },
  {
  "_id": "5804f2e90abc84bf13ac5cd7",
  "title": "Up sell Opportunity",
  "status": "won"
  }
 ]

Get

When fetching multiple opportunities 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/opportunities?limit=2&offset=0&sort=-mrr&select=_id,title,status' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

'[
  {
  "_id": "5ced0734861084738e27ff21",
  "status": "lost",
  "title": "P1 enabled!"
  },
  {
  "_id": "5804f2e90abc84bf13ac5cd7",
  "title": "Up sell Opportunity",
  "status": "won"
  }
 ]

Get

When fetching multiple opportunities 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/opportunities?limit=2&offset=0&sort=-mrr&select=_id,title,status' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

'[
  {
  "_id": "5ced0734861084738e27ff21",
  "status": "lost",
  "title": "P1 enabled!"
  },
  {
  "_id": "5804f2e90abc84bf13ac5cd7",
  "title": "Up sell Opportunity",
  "status": "won"
  }
 ]

Delete

To delete an opportunity it's required to pass the opportunity _id in the request URL as a parameter.

Example Request

curl --location -g --request DELETE 'https://api.planhat.com/opportunities/6101e99b72c0e0884d5e9139' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

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

Delete

To delete an opportunity it's required to pass the opportunity _id in the request URL as a parameter.

Example Request

curl --location -g --request DELETE 'https://api.planhat.com/opportunities/6101e99b72c0e0884d5e9139' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

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

Delete

To delete an opportunity it's required to pass the opportunity _id in the request URL as a parameter.

Example Request

curl --location -g --request DELETE 'https://api.planhat.com/opportunities/6101e99b72c0e0884d5e9139' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

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

Put

To create an opportunity it's required to define 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 opportunity it is required to specify in the payload one of the following keyables, listed in order of priority: _id, externalId.

Since this is a bulk upsert operation it's possible to create and/or update multiple opportunities 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/opportunities' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '[
  {
  "salesStage": "Pitched",
  "dealDate": "2021-08-10T00:00:00.000Z",
  "ownerId": "60ccb1c5965cc9e0f3848075",
  "_currency": "USD",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "title": "New license opportunity",
  "recurringValue": 6000,
  "status": "active"
  },
  {
  "salesStage": "Pitched",
  "dealDate": "2021-08-03T00:00:00.000Z",
  "ownerId": "60ccb1c5965cc9e0f3848075",
  "_currency": "USD",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "title": "New sale opportunity",
  "recurringValue": 1000,
  "status": "active"
  }
 ]'

Example Response

200 ok

'{
  "created": 2,
  "createdErrors": [],
  "insertsKeys": [
  {
  "_id": "6101ebd072c0e0884d5e91fb"
  },
  {
  "_id": "6101ebd072c0e0884d5e91fc"
  }
  ],
  "updated": 0,
  "updatedErrors": [],
  "updatesKeys": [],
  "nonupdates": 0,
  "modified": [],
  "upsertedIds": [
  "6101ebd072c0e0884d5e91fb",
  "6101ebd072c0e0884d5e91fc"
  ],
  "permissionErrors": []
 }'

Put

To create an opportunity it's required to define 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 opportunity it is required to specify in the payload one of the following keyables, listed in order of priority: _id, externalId.

Since this is a bulk upsert operation it's possible to create and/or update multiple opportunities 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/opportunities' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '[
  {
  "salesStage": "Pitched",
  "dealDate": "2021-08-10T00:00:00.000Z",
  "ownerId": "60ccb1c5965cc9e0f3848075",
  "_currency": "USD",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "title": "New license opportunity",
  "recurringValue": 6000,
  "status": "active"
  },
  {
  "salesStage": "Pitched",
  "dealDate": "2021-08-03T00:00:00.000Z",
  "ownerId": "60ccb1c5965cc9e0f3848075",
  "_currency": "USD",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "title": "New sale opportunity",
  "recurringValue": 1000,
  "status": "active"
  }
 ]'

Example Response

200 ok

'{
  "created": 2,
  "createdErrors": [],
  "insertsKeys": [
  {
  "_id": "6101ebd072c0e0884d5e91fb"
  },
  {
  "_id": "6101ebd072c0e0884d5e91fc"
  }
  ],
  "updated": 0,
  "updatedErrors": [],
  "updatesKeys": [],
  "nonupdates": 0,
  "modified": [],
  "upsertedIds": [
  "6101ebd072c0e0884d5e91fb",
  "6101ebd072c0e0884d5e91fc"
  ],
  "permissionErrors": []
 }'

Put

To create an opportunity it's required to define 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 opportunity it is required to specify in the payload one of the following keyables, listed in order of priority: _id, externalId.

Since this is a bulk upsert operation it's possible to create and/or update multiple opportunities 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/opportunities' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '[
  {
  "salesStage": "Pitched",
  "dealDate": "2021-08-10T00:00:00.000Z",
  "ownerId": "60ccb1c5965cc9e0f3848075",
  "_currency": "USD",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "title": "New license opportunity",
  "recurringValue": 6000,
  "status": "active"
  },
  {
  "salesStage": "Pitched",
  "dealDate": "2021-08-03T00:00:00.000Z",
  "ownerId": "60ccb1c5965cc9e0f3848075",
  "_currency": "USD",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "title": "New sale opportunity",
  "recurringValue": 1000,
  "status": "active"
  }
 ]'

Example Response

200 ok

'{
  "created": 2,
  "createdErrors": [],
  "insertsKeys": [
  {
  "_id": "6101ebd072c0e0884d5e91fb"
  },
  {
  "_id": "6101ebd072c0e0884d5e91fc"
  }
  ],
  "updated": 0,
  "updatedErrors": [],
  "updatesKeys": [],
  "nonupdates": 0,
  "modified": [],
  "upsertedIds": [
  "6101ebd072c0e0884d5e91fb",
  "6101ebd072c0e0884d5e91fc"
  ],
  "permissionErrors": []
 }'

Opportunity

Opportunity

Property

Required

Type

Description

Property

Required

Type

Description

Property

Required

Type

Description

Example:

Example:

Example:

Example:

Example:

Example: