Planhat Logo

Developers

Planhat Logo

Developers

Issue

Issues typically represent Bugs or Feature Requests. Many of our customers fetch issues from Jira, but they can also be pushed to Planhat from other product management tools such as Product Board or Aha! You can also manage issues directly in Planhat without any external tool. Just keep in mind that the functionality is basic and mostly intended to contribute to the customer 360 view.

Issues in Planhat can link to multiple companies, to multiple endusers and to multiple conversations.

Property
Required
Type
Description

_id



objectId

Planhat identifier.

title

Yes

string

Issue title, required to create an issue.

description



string

Description for the issue.

companyIds



array

Array of companies ids involved with the issue.

companies



array

Array of companies involved with the issue. (Autogenerated).

enduserIds



array

Array of endusers ids that are part of the issue.

endusers



array

Array of endusers that are part of the issue. (Autogenerated).

conversationIds



array

Array of conversations ids that are part of the issue.

sourceId



string

The issue id from an integration (Sales Force, Hubspot, etc).

source



string

Source name or description.

sourceUrl



string

Source URL.

priority



string

Priority name or description.

archived



boolean

True if the issue is archived.

status



string

Current status of the issue.

mrrCombined



integer

Total MRR involved in this issue. (Autogenerated).

arrCombined



integer

Total ARR involved in this issue. (Autogenerated).

createdAt



string

ISO date when issue was created. (Autogenerated).

updatedAt



string

ISO date when issue was updated. (Autogenerated).

followers



array

Array of users ids following the issue.

custom



object

A flexible object with custom data.

Issues typically represent Bugs or Feature Requests. Many of our customers fetch issues from Jira, but they can also be pushed to Planhat from other product management tools such as Product Board or Aha! You can also manage issues directly in Planhat without any external tool. Just keep in mind that the functionality is basic and mostly intended to contribute to the customer 360 view.

Issues in Planhat can link to multiple companies, to multiple endusers and to multiple conversations.

Property
Required
Type
Description

_id



objectId

Planhat identifier.

title

Yes

string

Issue title, required to create an issue.

description



string

Description for the issue.

companyIds



array

Array of companies ids involved with the issue.

companies



array

Array of companies involved with the issue. (Autogenerated).

enduserIds



array

Array of endusers ids that are part of the issue.

endusers



array

Array of endusers that are part of the issue. (Autogenerated).

conversationIds



array

Array of conversations ids that are part of the issue.

sourceId



string

The issue id from an integration (Sales Force, Hubspot, etc).

source



string

Source name or description.

sourceUrl



string

Source URL.

priority



string

Priority name or description.

archived



boolean

True if the issue is archived.

status



string

Current status of the issue.

mrrCombined



integer

Total MRR involved in this issue. (Autogenerated).

arrCombined



integer

Total ARR involved in this issue. (Autogenerated).

createdAt



string

ISO date when issue was created. (Autogenerated).

updatedAt



string

ISO date when issue was updated. (Autogenerated).

followers



array

Array of users ids following the issue.

custom



object

A flexible object with custom data.

Issues typically represent Bugs or Feature Requests. Many of our customers fetch issues from Jira, but they can also be pushed to Planhat from other product management tools such as Product Board or Aha! You can also manage issues directly in Planhat without any external tool. Just keep in mind that the functionality is basic and mostly intended to contribute to the customer 360 view.

Issues in Planhat can link to multiple companies, to multiple endusers and to multiple conversations.

Property
Required
Type
Description

_id



objectId

Planhat identifier.

title

Yes

string

Issue title, required to create an issue.

description



string

Description for the issue.

companyIds



array

Array of companies ids involved with the issue.

companies



array

Array of companies involved with the issue. (Autogenerated).

enduserIds



array

Array of endusers ids that are part of the issue.

endusers



array

Array of endusers that are part of the issue. (Autogenerated).

conversationIds



array

Array of conversations ids that are part of the issue.

sourceId



string

The issue id from an integration (Sales Force, Hubspot, etc).

source



string

Source name or description.

sourceUrl



string

Source URL.

priority



string

Priority name or description.

archived



boolean

True if the issue is archived.

status



string

Current status of the issue.

mrrCombined



integer

Total MRR involved in this issue. (Autogenerated).

arrCombined



integer

Total ARR involved in this issue. (Autogenerated).

createdAt



string

ISO date when issue was created. (Autogenerated).

updatedAt



string

ISO date when issue was updated. (Autogenerated).

followers



array

Array of users ids following the issue.

custom



object

A flexible object with custom data.

Create issue

To create an issue the only real value that is required is the title but it doesn't make much sense to have an issue just with a title, that is why we suggest specifying a companyIds.

You can instead reference the company externalId or sourceId using the following command structure: "companyIds": ["extid-[company externalId]"] or "companyIds": ["srcid-[company sourceId]"].

Example Request

curl --location -g --request POST 'https://api.planhat.com/issues' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "companyIds": [
  "61006bc89a3e0b702ed8ea49"
  ],
  "enduserIds": [
  "610091916d643a7c418aef42"
  ],
  "title": "Problem with integration",
  "description": "There is a problem with our integration settings that is affecting some users.",
  "status": "Open"
 }'


Example Response

'{
  "companyMatchingValue": [],
  "companyIds": [
  "61006bc89a3e0b702ed8ea49"
  ],
  "enduserIds": [
  "610091916d643a7c418aef42"
  ],
  "conversationIds": [],
  "archived": false,
  "_id": "610411d5b046afb2109df12c",
  "title": "Problem with integration",
  "description": "There is a problem with our integration settings that is affecting some users.",
  "status": "Open",
  "companies": [
  {
  "id": "61006bc89a3e0b702ed8ea49",
  "name": "Tenet"
  }
  ],
  "endusers": [
  {
  "id": "610091916d643a7c418aef42",
  "name": "Lara Croft"
  }
  ],
  "updatedAt": "2021-07-30T14:51:01.691Z",
  "createdAt": "2021-07-30T14:51:01.691Z",
  "__v": 0
 }'
Create issue

To create an issue the only real value that is required is the title but it doesn't make much sense to have an issue just with a title, that is why we suggest specifying a companyIds.

You can instead reference the company externalId or sourceId using the following command structure: "companyIds": ["extid-[company externalId]"] or "companyIds": ["srcid-[company sourceId]"].

Example Request

curl --location -g --request POST 'https://api.planhat.com/issues' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "companyIds": [
  "61006bc89a3e0b702ed8ea49"
  ],
  "enduserIds": [
  "610091916d643a7c418aef42"
  ],
  "title": "Problem with integration",
  "description": "There is a problem with our integration settings that is affecting some users.",
  "status": "Open"
 }'


Example Response

'{
  "companyMatchingValue": [],
  "companyIds": [
  "61006bc89a3e0b702ed8ea49"
  ],
  "enduserIds": [
  "610091916d643a7c418aef42"
  ],
  "conversationIds": [],
  "archived": false,
  "_id": "610411d5b046afb2109df12c",
  "title": "Problem with integration",
  "description": "There is a problem with our integration settings that is affecting some users.",
  "status": "Open",
  "companies": [
  {
  "id": "61006bc89a3e0b702ed8ea49",
  "name": "Tenet"
  }
  ],
  "endusers": [
  {
  "id": "610091916d643a7c418aef42",
  "name": "Lara Croft"
  }
  ],
  "updatedAt": "2021-07-30T14:51:01.691Z",
  "createdAt": "2021-07-30T14:51:01.691Z",
  "__v": 0
 }'
Create issue

To create an issue the only real value that is required is the title but it doesn't make much sense to have an issue just with a title, that is why we suggest specifying a companyIds.

You can instead reference the company externalId or sourceId using the following command structure: "companyIds": ["extid-[company externalId]"] or "companyIds": ["srcid-[company sourceId]"].

Example Request

curl --location -g --request POST 'https://api.planhat.com/issues' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "companyIds": [
  "61006bc89a3e0b702ed8ea49"
  ],
  "enduserIds": [
  "610091916d643a7c418aef42"
  ],
  "title": "Problem with integration",
  "description": "There is a problem with our integration settings that is affecting some users.",
  "status": "Open"
 }'


Example Response

'{
  "companyMatchingValue": [],
  "companyIds": [
  "61006bc89a3e0b702ed8ea49"
  ],
  "enduserIds": [
  "610091916d643a7c418aef42"
  ],
  "conversationIds": [],
  "archived": false,
  "_id": "610411d5b046afb2109df12c",
  "title": "Problem with integration",
  "description": "There is a problem with our integration settings that is affecting some users.",
  "status": "Open",
  "companies": [
  {
  "id": "61006bc89a3e0b702ed8ea49",
  "name": "Tenet"
  }
  ],
  "endusers": [
  {
  "id": "610091916d643a7c418aef42",
  "name": "Lara Croft"
  }
  ],
  "updatedAt": "2021-07-30T14:51:01.691Z",
  "createdAt": "2021-07-30T14:51:01.691Z",
  "__v": 0
 }'
Update issue

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

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

Example:

Example Request

curl --location -g --request PUT 'https://api.planhat.com/issues/610411d5b046afb2109df12c' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "status": "In Progress"
 }'


Example Response

'{
  "_id": "61041245b046afb2109df1bb",
  "companyMatchingValue": [],
  "companyIds": [
  "61006bc89a3e0b702ed8ea49"
  ],
  "enduserIds": [],
  "conversationIds": [],
  "archived": false,
  "title": "Problem with integration",
  "description": "There is a problem with our integration settings that is affecting some users.",
  "status": "In Progress",
  "companies": [
  {
  "id": "61006bc89a3e0b702ed8ea49",
  "name": "Tenet"
  }
  ],
  "endusers": [],
  "updatedAt": "2021-07-30T14:52:53.441Z",
  "createdAt": "2021-07-30T14:52:53.441Z",
  "__v": 0
 }'
Update issue

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

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

Example:

Example Request

curl --location -g --request PUT 'https://api.planhat.com/issues/610411d5b046afb2109df12c' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "status": "In Progress"
 }'


Example Response

'{
  "_id": "61041245b046afb2109df1bb",
  "companyMatchingValue": [],
  "companyIds": [
  "61006bc89a3e0b702ed8ea49"
  ],
  "enduserIds": [],
  "conversationIds": [],
  "archived": false,
  "title": "Problem with integration",
  "description": "There is a problem with our integration settings that is affecting some users.",
  "status": "In Progress",
  "companies": [
  {
  "id": "61006bc89a3e0b702ed8ea49",
  "name": "Tenet"
  }
  ],
  "endusers": [],
  "updatedAt": "2021-07-30T14:52:53.441Z",
  "createdAt": "2021-07-30T14:52:53.441Z",
  "__v": 0
 }'
Update issue

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

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

Example:

Example Request

curl --location -g --request PUT 'https://api.planhat.com/issues/610411d5b046afb2109df12c' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "status": "In Progress"
 }'


Example Response

'{
  "_id": "61041245b046afb2109df1bb",
  "companyMatchingValue": [],
  "companyIds": [
  "61006bc89a3e0b702ed8ea49"
  ],
  "enduserIds": [],
  "conversationIds": [],
  "archived": false,
  "title": "Problem with integration",
  "description": "There is a problem with our integration settings that is affecting some users.",
  "status": "In Progress",
  "companies": [
  {
  "id": "61006bc89a3e0b702ed8ea49",
  "name": "Tenet"
  }
  ],
  "endusers": [],
  "updatedAt": "2021-07-30T14:52:53.441Z",
  "createdAt": "2021-07-30T14:52:53.441Z",
  "__v": 0
 }'
Get issues by ID

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

Alternately it’s possible to get an issue using its sourceId adding a prefix and passing this keyable as identifier.

Example:

Example Request

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

Example Response

'{
  "_id": "60f7df113432fd36abf8b899",
  "companyMatchingValue": [],
  "companyIds": [
  "56bccdf554d64d837d01be9d"
  ],
  "enduserIds": [],
  "conversationIds": [],
  "archived": false,
  "title": "There is a problem with the sites",
  "companies": [],
  "endusers": [],
  ": [],
  "updatedAt": "2021-07-21T08:47:13.221Z",
  "createdAt": "2021-07-21T08:47:13.221Z",
  "__v": 0,
  "status": "Done"
 }'
Get issues by ID

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

Alternately it’s possible to get an issue using its sourceId adding a prefix and passing this keyable as identifier.

Example:

Example Request

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

Example Response

'{
  "_id": "60f7df113432fd36abf8b899",
  "companyMatchingValue": [],
  "companyIds": [
  "56bccdf554d64d837d01be9d"
  ],
  "enduserIds": [],
  "conversationIds": [],
  "archived": false,
  "title": "There is a problem with the sites",
  "companies": [],
  "endusers": [],
  ": [],
  "updatedAt": "2021-07-21T08:47:13.221Z",
  "createdAt": "2021-07-21T08:47:13.221Z",
  "__v": 0,
  "status": "Done"
 }'
Get issues by ID

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

Alternately it’s possible to get an issue using its sourceId adding a prefix and passing this keyable as identifier.

Example:

Example Request

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

Example Response

'{
  "_id": "60f7df113432fd36abf8b899",
  "companyMatchingValue": [],
  "companyIds": [
  "56bccdf554d64d837d01be9d"
  ],
  "enduserIds": [],
  "conversationIds": [],
  "archived": false,
  "title": "There is a problem with the sites",
  "companies": [],
  "endusers": [],
  ": [],
  "updatedAt": "2021-07-21T08:47:13.221Z",
  "createdAt": "2021-07-21T08:47:13.221Z",
  "__v": 0,
  "status": "Done"
 }'
Get issues List

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

Example Response

'[
  {
  "_id": "61041245b046afb2109df1bb",
  "companyIds": [
  "61006bc89a3e0b702ed8ea49"
  ],
  "title": "Problem with integration",
  "status": "In Progress"
  },
  {
  "_id": "61002501cb43626b3a802f52",
  "companyIds": [
  60f7df113432fd36abf8b899
  ],
  "title": "New issue",
  "status": "Done"
  }
 ]

Get issues List

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

Example Response

'[
  {
  "_id": "61041245b046afb2109df1bb",
  "companyIds": [
  "61006bc89a3e0b702ed8ea49"
  ],
  "title": "Problem with integration",
  "status": "In Progress"
  },
  {
  "_id": "61002501cb43626b3a802f52",
  "companyIds": [
  60f7df113432fd36abf8b899
  ],
  "title": "New issue",
  "status": "Done"
  }
 ]

Get issues List

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

Example Response

'[
  {
  "_id": "61041245b046afb2109df1bb",
  "companyIds": [
  "61006bc89a3e0b702ed8ea49"
  ],
  "title": "Problem with integration",
  "status": "In Progress"
  },
  {
  "_id": "61002501cb43626b3a802f52",
  "companyIds": [
  60f7df113432fd36abf8b899
  ],
  "title": "New issue",
  "status": "Done"
  }
 ]

Delete issues

To delete an issue 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/issues/610411d5b046afb2109df12c' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

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

To delete an issue 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/issues/610411d5b046afb2109df12c' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

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

To delete an issue 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/issues/610411d5b046afb2109df12c' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

'{
  "n": 1,
  "ok": 1,
  "deletedCount": 1
 }'
Bulk Upsert issues

To create an issue it's required to define a title and companyIds.

You can instead reference the company externalId or sourceId using the following command structure: "companyIds": ["extid-[company externalId]"] or "companyIds": ["srcid-[company sourceId]"].

To update an issue it is required to specify in the payload one of the following keyables, listed in order of priority: _id, sourceId.

Since this is a bulk upsert operation it's possible to create and/or update multiple issues 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/issues' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '[
  {
  "_id": "60f7df113432fd36abf8b899",
  "status": "Done"
  },
  {
  "companyIds": [
  "61006bc89a3e0b702ed8ea49"
  ],
  "enduserIds": [
  "610091916d643a7c418aef42"
  ],
  "title": "Problem with integration",
  "description": "There is a problem with our integration settings that is affecting some users.",
  "status": "Open"
  }
 ]'


Example Response

'{
  "created": 1,
  "createdErrors": [],
  "insertsKeys": [
  {
  "_id": "610415ecb046afb2109df26b"
  }
  ],
  "updated": 1,
  "updatedErrors": [],
  "updatesKeys": [
  {
  "_id": "60f7df113432fd36abf8b899"
  }
  ],
  "nonupdates": 0,
  "modified": [
  "60f7df113432fd36abf8b899"
  ],
  "upsertedIds": [
  "610415ecb046afb2109df26b"
  ],
  "permissionErrors": []
 }'
Bulk Upsert issues

To create an issue it's required to define a title and companyIds.

You can instead reference the company externalId or sourceId using the following command structure: "companyIds": ["extid-[company externalId]"] or "companyIds": ["srcid-[company sourceId]"].

To update an issue it is required to specify in the payload one of the following keyables, listed in order of priority: _id, sourceId.

Since this is a bulk upsert operation it's possible to create and/or update multiple issues 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/issues' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '[
  {
  "_id": "60f7df113432fd36abf8b899",
  "status": "Done"
  },
  {
  "companyIds": [
  "61006bc89a3e0b702ed8ea49"
  ],
  "enduserIds": [
  "610091916d643a7c418aef42"
  ],
  "title": "Problem with integration",
  "description": "There is a problem with our integration settings that is affecting some users.",
  "status": "Open"
  }
 ]'


Example Response

'{
  "created": 1,
  "createdErrors": [],
  "insertsKeys": [
  {
  "_id": "610415ecb046afb2109df26b"
  }
  ],
  "updated": 1,
  "updatedErrors": [],
  "updatesKeys": [
  {
  "_id": "60f7df113432fd36abf8b899"
  }
  ],
  "nonupdates": 0,
  "modified": [
  "60f7df113432fd36abf8b899"
  ],
  "upsertedIds": [
  "610415ecb046afb2109df26b"
  ],
  "permissionErrors": []
 }'
Bulk Upsert issues

To create an issue it's required to define a title and companyIds.

You can instead reference the company externalId or sourceId using the following command structure: "companyIds": ["extid-[company externalId]"] or "companyIds": ["srcid-[company sourceId]"].

To update an issue it is required to specify in the payload one of the following keyables, listed in order of priority: _id, sourceId.

Since this is a bulk upsert operation it's possible to create and/or update multiple issues 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/issues' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '[
  {
  "_id": "60f7df113432fd36abf8b899",
  "status": "Done"
  },
  {
  "companyIds": [
  "61006bc89a3e0b702ed8ea49"
  ],
  "enduserIds": [
  "610091916d643a7c418aef42"
  ],
  "title": "Problem with integration",
  "description": "There is a problem with our integration settings that is affecting some users.",
  "status": "Open"
  }
 ]'


Example Response

'{
  "created": 1,
  "createdErrors": [],
  "insertsKeys": [
  {
  "_id": "610415ecb046afb2109df26b"
  }
  ],
  "updated": 1,
  "updatedErrors": [],
  "updatesKeys": [
  {
  "_id": "60f7df113432fd36abf8b899"
  }
  ],
  "nonupdates": 0,
  "modified": [
  "60f7df113432fd36abf8b899"
  ],
  "upsertedIds": [
  "610415ecb046afb2109df26b"
  ],
  "permissionErrors": []
 }'