Developers
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. |
Create Opportunity
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
'{
"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
}'Create Opportunity
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
'{
"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
}'Create Opportunity
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
'{
"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
}'Update Opportunity
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
'{
"_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"
}'Update Opportunity
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
'{
"_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"
}'Update Opportunity
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
'{
"_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 Opportunities by ID
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:
or
Example Request
curl --location -g --request GET 'https://api.planhat.com/opportunities/58499569e2914f5171fa7f9d' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_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 Opportunities by ID
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:
or
Example Request
curl --location -g --request GET 'https://api.planhat.com/opportunities/58499569e2914f5171fa7f9d' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_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 Opportunities by ID
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:
or
Example Request
curl --location -g --request GET 'https://api.planhat.com/opportunities/58499569e2914f5171fa7f9d' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_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 Opportunities List
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
'[
{
"_id": "5ced0734861084738e27ff21",
"status": "lost",
"title": "P1 enabled!"
},
{
"_id": "5804f2e90abc84bf13ac5cd7",
"title": "Up sell Opportunity",
"status": "won"
}
]
get Opportunities List
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
'[
{
"_id": "5ced0734861084738e27ff21",
"status": "lost",
"title": "P1 enabled!"
},
{
"_id": "5804f2e90abc84bf13ac5cd7",
"title": "Up sell Opportunity",
"status": "won"
}
]
get Opportunities List
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
'[
{
"_id": "5ced0734861084738e27ff21",
"status": "lost",
"title": "P1 enabled!"
},
{
"_id": "5804f2e90abc84bf13ac5cd7",
"title": "Up sell Opportunity",
"status": "won"
}
]
delete Opportunities
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
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'delete Opportunities
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
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'delete Opportunities
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
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'Bulk Upsert Opportunities
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.
Note: 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
'{
"created": 2,
"createdErrors": [],
"insertsKeys": [
{
"_id": "6101ebd072c0e0884d5e91fb"
},
{
"_id": "6101ebd072c0e0884d5e91fc"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"6101ebd072c0e0884d5e91fb",
"6101ebd072c0e0884d5e91fc"
],
"permissionErrors": []
}'Bulk Upsert Opportunities
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.
Note: 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
'{
"created": 2,
"createdErrors": [],
"insertsKeys": [
{
"_id": "6101ebd072c0e0884d5e91fb"
},
{
"_id": "6101ebd072c0e0884d5e91fc"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"6101ebd072c0e0884d5e91fb",
"6101ebd072c0e0884d5e91fc"
],
"permissionErrors": []
}'Bulk Upsert Opportunities
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.
Note: 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
'{
"created": 2,
"createdErrors": [],
"insertsKeys": [
{
"_id": "6101ebd072c0e0884d5e91fb"
},
{
"_id": "6101ebd072c0e0884d5e91fc"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"6101ebd072c0e0884d5e91fb",
"6101ebd072c0e0884d5e91fc"
],
"permissionErrors": []
}'