Planhat | The Unified Customer Platform

Developers

Task

Tasks are the things that you plan to do in the future. It can be a simple "to-do" without any specific due date, a reminder of something to be done at a specific point in time, or even a meeting with a start and end time.

Most of the time these tasks will be automatically generated in Planhat based on rules you set up. It's also common to have tasks as steps in a Playbook. But tasks can also be created ad-hoc just like you would in any task management app.

Tasks managed over the API should typically have the mainType property set to task, the other potential value is event, which indicates that it was synced to or from a calendar like Google Calendar. Though it's also possible to create tasks of type event in Planhat without syncing them back to any calendar.

Once a task is completed it's archived and generally not visible in Planhat anymore. Sometimes when completing a task, say a training session, you want to log a note summarizing how it went, this is managed automatically by Planhat when working in the Planhat app.

Property	Required	Type	Description
_id		objectId	Planhat identifier.
mainType	Yes	string	Required type should be always task.
companyId	Yes	objectId	Related company id (planhat identifier).
companyName		string	Company name. (Autogenerated).
startTime		string	ISO date when the task will start.
endTime		string	ISO date when the task will end.
dateDone		string	ISO date when the task was completed.
action		string	Title of the task, e.g. "Send Invoice"
description		string	Some description of the task.
repeat		string	If task repeatable then should send how often. The options are: daily, weekly, monthly, quarterly, yearly and custom.
repeatDays		integer	Number of days that the task will be repeated. Required if a custom repeat interval is set.
type		string	Type of task.
ownerId		objectId	ObjectId of the team member that owns the task.
ownerName		string	Owner name of the task. (Autogenerated).
doneBy		objectId	ObjectId of the team member who did the task.
sourceId		string	The task id from an integration (Sales Force, Hubspot, etc).
noSpecificTime		boolean	True if the task doesn't have any specific date to be executed. (Autogenerated).
shared		boolean	True if the task is shared. (Autogenerated).
overdueNotified		boolean	True if the task was notified due overdue. (Autogenerated).
activityTags		array	Array of string to tags.
isArchived		boolean	Flag the task as archived.
status		string	Each task can be assigned a status in Planhat. It’s a text string that should match the name of one of the task statuses in Planhat. If the name doesn’t match any of the statuses in Planhat it will still be saved.
checklist		array	Array of check list actions to be executed with the task.
snippet		string	Formatted content of the task.
endusers		array	Array of involved contacts. (Autogenerated).
users		array	Array of involved users. (Autogenerated).
custom		object	Custom object with your custom properties.
createdAt		string	An automatically created field that holds the Task creation ISO date.
updatedAt		string	Automatically created and updated field that holds the ISO date when the task was last modified.

Property	Required	Type	Description
_id		objectId	Planhat identifier.
mainType	Yes	string	Required type should be always task.
companyId	Yes	objectId	Related company id (planhat identifier).
companyName		string	Company name. (Autogenerated).
startTime		string	ISO date when the task will start.
endTime		string	ISO date when the task will end.
dateDone		string	ISO date when the task was completed.
action		string	Title of the task, e.g. "Send Invoice"
description		string	Some description of the task.
repeat		string	If task repeatable then should send how often. The options are: daily, weekly, monthly, quarterly, yearly and custom.
repeatDays		integer	Number of days that the task will be repeated. Required if a custom repeat interval is set.
type		string	Type of task.
ownerId		objectId	ObjectId of the team member that owns the task.
ownerName		string	Owner name of the task. (Autogenerated).
doneBy		objectId	ObjectId of the team member who did the task.
sourceId		string	The task id from an integration (Sales Force, Hubspot, etc).
noSpecificTime		boolean	True if the task doesn't have any specific date to be executed. (Autogenerated).
shared		boolean	True if the task is shared. (Autogenerated).
overdueNotified		boolean	True if the task was notified due overdue. (Autogenerated).
activityTags		array	Array of string to tags.
isArchived		boolean	Flag the task as archived.
status		string	Each task can be assigned a status in Planhat. It’s a text string that should match the name of one of the task statuses in Planhat. If the name doesn’t match any of the statuses in Planhat it will still be saved.
checklist		array	Array of check list actions to be executed with the task.
snippet		string	Formatted content of the task.
endusers		array	Array of involved contacts. (Autogenerated).
users		array	Array of involved users. (Autogenerated).
custom		object	Custom object with your custom properties.
createdAt		string	An automatically created field that holds the Task creation ISO date.
updatedAt		string	Automatically created and updated field that holds the ISO date when the task was last modified.

Property	Required	Type	Description
_id		objectId	Planhat identifier.
mainType	Yes	string	Required type should be always task.
companyId	Yes	objectId	Related company id (planhat identifier).
companyName		string	Company name. (Autogenerated).
startTime		string	ISO date when the task will start.
endTime		string	ISO date when the task will end.
dateDone		string	ISO date when the task was completed.
action		string	Title of the task, e.g. "Send Invoice"
description		string	Some description of the task.
repeat		string	If task repeatable then should send how often. The options are: daily, weekly, monthly, quarterly, yearly and custom.
repeatDays		integer	Number of days that the task will be repeated. Required if a custom repeat interval is set.
type		string	Type of task.
ownerId		objectId	ObjectId of the team member that owns the task.
ownerName		string	Owner name of the task. (Autogenerated).
doneBy		objectId	ObjectId of the team member who did the task.
sourceId		string	The task id from an integration (Sales Force, Hubspot, etc).
noSpecificTime		boolean	True if the task doesn't have any specific date to be executed. (Autogenerated).
shared		boolean	True if the task is shared. (Autogenerated).
overdueNotified		boolean	True if the task was notified due overdue. (Autogenerated).
activityTags		array	Array of string to tags.
isArchived		boolean	Flag the task as archived.
status		string	Each task can be assigned a status in Planhat. It’s a text string that should match the name of one of the task statuses in Planhat. If the name doesn’t match any of the statuses in Planhat it will still be saved.
checklist		array	Array of check list actions to be executed with the task.
snippet		string	Formatted content of the task.
endusers		array	Array of involved contacts. (Autogenerated).
users		array	Array of involved users. (Autogenerated).
custom		object	Custom object with your custom properties.
createdAt		string	An automatically created field that holds the Task creation ISO date.
updatedAt		string	Automatically created and updated field that holds the ISO date when the task was last modified.

Create task

Post

To create a task it is 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]".

If the mainType is not specified it will be created with the default value: "task"

It is recommended to set the action field, think of it as the task's title e.g. "Send Invoice"

Example Request

curl --location -g --request POST 'https://api.planhat.com/tasks' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "ownerId": "58e231b14246fc73139f29e8",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "mainType": "task",
  "noSpecificTime": true,
  "startTime": "2021-07-29T00:00:00.00Z",
  "repeat": "daily",
  "action": "New task",
  "description": "<p>Call the client.</p>"
 }'

Example Response

200 ok

'{
  "mainType": "task",
  "noSpecificTime": true,
  "shared": false,
  "overdueNotified": false,
  "activityTags": [],
  "isArchived": false,
  "status": "In-progress",
  "_id": "6102c9748084189dcbf0df60",
  "ownerId": "58e231b14246fc73139f29e8",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "startTime": "2021-07-29T00:00:00.000Z",
  "repeat": "daily",
  "action": "New task",
  "description": "<p>Call the client.</p>",
  "snippet": "Call the client.",
  "companyName": "Tenet",
  "endusers": [],
  "users": [],
  "checklist": [],
  "__v": 0,
  "userEmail": "user@planhat.com",
  "createdAt": "2022-07-05T09:51:52.818Z",
  "updatedAt": "2022-07-05T09:51:52.818Z"
 }'

Create task

Post

To create a task it is 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]".

If the mainType is not specified it will be created with the default value: "task"

It is recommended to set the action field, think of it as the task's title e.g. "Send Invoice"

Example Request

curl --location -g --request POST 'https://api.planhat.com/tasks' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "ownerId": "58e231b14246fc73139f29e8",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "mainType": "task",
  "noSpecificTime": true,
  "startTime": "2021-07-29T00:00:00.00Z",
  "repeat": "daily",
  "action": "New task",
  "description": "<p>Call the client.</p>"
 }'

Example Response

200 ok

'{
  "mainType": "task",
  "noSpecificTime": true,
  "shared": false,
  "overdueNotified": false,
  "activityTags": [],
  "isArchived": false,
  "status": "In-progress",
  "_id": "6102c9748084189dcbf0df60",
  "ownerId": "58e231b14246fc73139f29e8",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "startTime": "2021-07-29T00:00:00.000Z",
  "repeat": "daily",
  "action": "New task",
  "description": "<p>Call the client.</p>",
  "snippet": "Call the client.",
  "companyName": "Tenet",
  "endusers": [],
  "users": [],
  "checklist": [],
  "__v": 0,
  "userEmail": "user@planhat.com",
  "createdAt": "2022-07-05T09:51:52.818Z",
  "updatedAt": "2022-07-05T09:51:52.818Z"
 }'

Create task

Post

To create a task it is 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]".

If the mainType is not specified it will be created with the default value: "task"

It is recommended to set the action field, think of it as the task's title e.g. "Send Invoice"

Example Request

curl --location -g --request POST 'https://api.planhat.com/tasks' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "ownerId": "58e231b14246fc73139f29e8",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "mainType": "task",
  "noSpecificTime": true,
  "startTime": "2021-07-29T00:00:00.00Z",
  "repeat": "daily",
  "action": "New task",
  "description": "<p>Call the client.</p>"
 }'

Example Response

200 ok

'{
  "mainType": "task",
  "noSpecificTime": true,
  "shared": false,
  "overdueNotified": false,
  "activityTags": [],
  "isArchived": false,
  "status": "In-progress",
  "_id": "6102c9748084189dcbf0df60",
  "ownerId": "58e231b14246fc73139f29e8",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "startTime": "2021-07-29T00:00:00.000Z",
  "repeat": "daily",
  "action": "New task",
  "description": "<p>Call the client.</p>",
  "snippet": "Call the client.",
  "companyName": "Tenet",
  "endusers": [],
  "users": [],
  "checklist": [],
  "__v": 0,
  "userEmail": "user@planhat.com",
  "createdAt": "2022-07-05T09:51:52.818Z",
  "updatedAt": "2022-07-05T09:51:52.818Z"
 }'

Update task

Put

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

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

Example:

Example Request

curl --location -g --request PUT 'https://api.planhat.com/tasks/6102c9748084189dcbf0df60' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "action": "Daily contact",
  "sourceId": "sfdc-1234"
 }'

Example Response

200 ok

'{
  "mainType": "task",
  "noSpecificTime": true,
  "shared": false,
  "overdueNotified": false,
  "activityTags": [],
  "isArchived": false,
  "status": "In-progress",
  "_id": "6102c9748084189dcbf0df60",
  "ownerId": "58e231b14246fc73139f29e8",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "startTime": "2021-07-29T00:00:00.000Z",
  "repeat": "daily",
  "action": "Daily contact",
  "description": "<p>Call the client.</p>",
  "snippet": "Call the client.",
  "companyName": "Tenet",
  "endusers": [],
  "users": [],
  "checklist": [],
  "__v": 0,
  "ownerName": "Alex",
  "sourceId": "sfdc-1234",
  "createdAt": "2022-07-05T09:51:52.818Z",
  "updatedAt": "2022-07-05T09:51:52.818Z"
 }'

Update task

Put

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

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

Example:

Example Request

curl --location -g --request PUT 'https://api.planhat.com/tasks/6102c9748084189dcbf0df60' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "action": "Daily contact",
  "sourceId": "sfdc-1234"
 }'

Example Response

200 ok

'{
  "mainType": "task",
  "noSpecificTime": true,
  "shared": false,
  "overdueNotified": false,
  "activityTags": [],
  "isArchived": false,
  "status": "In-progress",
  "_id": "6102c9748084189dcbf0df60",
  "ownerId": "58e231b14246fc73139f29e8",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "startTime": "2021-07-29T00:00:00.000Z",
  "repeat": "daily",
  "action": "Daily contact",
  "description": "<p>Call the client.</p>",
  "snippet": "Call the client.",
  "companyName": "Tenet",
  "endusers": [],
  "users": [],
  "checklist": [],
  "__v": 0,
  "ownerName": "Alex",
  "sourceId": "sfdc-1234",
  "createdAt": "2022-07-05T09:51:52.818Z",
  "updatedAt": "2022-07-05T09:51:52.818Z"
 }'

Update task

Put

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

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

Example:

Example Request

curl --location -g --request PUT 'https://api.planhat.com/tasks/6102c9748084189dcbf0df60' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "action": "Daily contact",
  "sourceId": "sfdc-1234"
 }'

Example Response

200 ok

'{
  "mainType": "task",
  "noSpecificTime": true,
  "shared": false,
  "overdueNotified": false,
  "activityTags": [],
  "isArchived": false,
  "status": "In-progress",
  "_id": "6102c9748084189dcbf0df60",
  "ownerId": "58e231b14246fc73139f29e8",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "startTime": "2021-07-29T00:00:00.000Z",
  "repeat": "daily",
  "action": "Daily contact",
  "description": "<p>Call the client.</p>",
  "snippet": "Call the client.",
  "companyName": "Tenet",
  "endusers": [],
  "users": [],
  "checklist": [],
  "__v": 0,
  "ownerName": "Alex",
  "sourceId": "sfdc-1234",
  "createdAt": "2022-07-05T09:51:52.818Z",
  "updatedAt": "2022-07-05T09:51:52.818Z"
 }'

Get tasks by ID

Get

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

Alternately it's possible to get a task using its sourceId adding a prefix and passing this keyable as identifier.

Example:

Example Request

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

Example Response

200 ok

'{
  "_id": "5db866ceab7aac67dc3637c8",
  "mainType": "task",
  "noSpecificTime": true,
  "shared": false,
  "overdueNotified": false,
  "activityTags": [],
  "isArchived": false,
  "status": "In-progress",
  "action": "Sub activity",
  "description": "",
  "companyId": "56ccc2d39b760ff232295794",
  "companyName": "Grand Hotels",
  "createdAt": "2022-07-05T09:51:52.818Z",
  "updatedAt": "2022-07-05T09:51:52.818Z",
  "ownerId": "54ddc90a3570c76e2cbd08a5",
  "ownerName": "Niklas",
  "workflowId": "5db866ceab7aac67dc3637be",
  "workflowName": "QBR",
  "workflowTaskId": "5d27408853372f7cd1170407",
  "checklist": [],
  "parent": "5db866ceab7aac67dc3637c6",
  "sortPosition": 5,
  "snippet": "",
  "endusers": [],
  "users": [],
  "children": [],
  "comments": [],
  "__v": 0,
  "workflowTemplateId": "5a57d7754b5f1d13128a0533",
  "repeat": null,
  "custom": {
  "HScore": 0
  },
  "workflowStepId": "5db866ceab7aac67dc3637c8"
 }'

Get tasks by ID

Get

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

Alternately it's possible to get a task using its sourceId adding a prefix and passing this keyable as identifier.

Example:

Example Request

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

Example Response

200 ok

'{
  "_id": "5db866ceab7aac67dc3637c8",
  "mainType": "task",
  "noSpecificTime": true,
  "shared": false,
  "overdueNotified": false,
  "activityTags": [],
  "isArchived": false,
  "status": "In-progress",
  "action": "Sub activity",
  "description": "",
  "companyId": "56ccc2d39b760ff232295794",
  "companyName": "Grand Hotels",
  "createdAt": "2022-07-05T09:51:52.818Z",
  "updatedAt": "2022-07-05T09:51:52.818Z",
  "ownerId": "54ddc90a3570c76e2cbd08a5",
  "ownerName": "Niklas",
  "workflowId": "5db866ceab7aac67dc3637be",
  "workflowName": "QBR",
  "workflowTaskId": "5d27408853372f7cd1170407",
  "checklist": [],
  "parent": "5db866ceab7aac67dc3637c6",
  "sortPosition": 5,
  "snippet": "",
  "endusers": [],
  "users": [],
  "children": [],
  "comments": [],
  "__v": 0,
  "workflowTemplateId": "5a57d7754b5f1d13128a0533",
  "repeat": null,
  "custom": {
  "HScore": 0
  },
  "workflowStepId": "5db866ceab7aac67dc3637c8"
 }'

Get tasks by ID

Get

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

Alternately it's possible to get a task using its sourceId adding a prefix and passing this keyable as identifier.

Example:

Example Request

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

Example Response

200 ok

'{
  "_id": "5db866ceab7aac67dc3637c8",
  "mainType": "task",
  "noSpecificTime": true,
  "shared": false,
  "overdueNotified": false,
  "activityTags": [],
  "isArchived": false,
  "status": "In-progress",
  "action": "Sub activity",
  "description": "",
  "companyId": "56ccc2d39b760ff232295794",
  "companyName": "Grand Hotels",
  "createdAt": "2022-07-05T09:51:52.818Z",
  "updatedAt": "2022-07-05T09:51:52.818Z",
  "ownerId": "54ddc90a3570c76e2cbd08a5",
  "ownerName": "Niklas",
  "workflowId": "5db866ceab7aac67dc3637be",
  "workflowName": "QBR",
  "workflowTaskId": "5d27408853372f7cd1170407",
  "checklist": [],
  "parent": "5db866ceab7aac67dc3637c6",
  "sortPosition": 5,
  "snippet": "",
  "endusers": [],
  "users": [],
  "children": [],
  "comments": [],
  "__v": 0,
  "workflowTemplateId": "5a57d7754b5f1d13128a0533",
  "repeat": null,
  "custom": {
  "HScore": 0
  },
  "workflowStepId": "5db866ceab7aac67dc3637c8"
 }'

Get tasks List

Get

When fetching multiple tasks 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 500, max. 10000.
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.
enduserIds: Filter using endusers id. Multiple ids can be used separating them by commas.
isArchived: Filter archived or not archived status. Default as false and this endpoint will return objects where the mainType is event and task.

Example Request

curl --location -g --request GET 'https://api.planhat.com/tasks?limit=2&offset=0' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

'[
  {
  "_id": "5da4bbec7b1616495b53a35b",
  "mainType": "task",
  "noSpecificTime": true,
  "shared": false,
  "overdueNotified": false,
  "activityTags": [],
  "isArchived": false,
  "ownerId": "5524481f516d59216a6d2b80",
  "companyId": "56bccdf554d64d837d01be96",
  "companyName": "Daimler Group",
  "createdAt": "2022-07-05T09:51:52.818Z",
  "updatedAt": "2022-07-05T09:51:52.818Z",
  "startTime": null,
  "action": "Send them gift card",
  "ownerName": "Sarah",
  "endusers": [],
  "users": [],
  "children": [],
  "comments": [],
  "checklist": [],
  "__v": 0,
  "repeat": null,
  "custom": {
  "HScore": 0
  }
  },
  {
  "_id": "5db866ceab7aac67dc3637c8",
  "mainType": "task",
  "noSpecificTime": true,
  "shared": false,
  "overdueNotified": false,
  "activityTags": [],
  "isArchived": false,
  "action": "Sub activity",
  "description": "",
  "companyId": "56ccc2d39b760ff232295794",
  "companyName": "Grand Hotels",
  "ownerId": "54ddc90a3570c76e2cbd08a5",
  "ownerName": "Niklas",
  "workflowId": "5db866ceab7aac67dc3637be",
  "workflowName": "QBR",
  "workflowTaskId": "5d27408853372f7cd1170407",
  "checklist": [],
  "parent": "5db866ceab7aac67dc3637c6",
  "sortPosition": 5,
  "snippet": "",
  "endusers": [],
  "users": [],
  "children": [],
  "comments": [],
  "__v": 0,
  "workflowTemplateId": "5a57d7754b5f1d13128a0533",
  "repeat": null,
  "custom": {
  "HScore": 0
  },
  "workflowStepId": "5db866ceab7aac67dc3637c8"
  },
  {
  "_id": "5f05cc03da205d2dfb2ad775",
  "mainType": "event",
  "noSpecificTime": true,
  "shared": true,
  "overdueNotified": false,
  "activityTags": [],
  "isArchived": false,
  "action": "Test",
  "description": "",
  "companyId": "56bccdf554d64d837d01be55",
  "companyName": "Sweco",
  "ownerId": "564b063a508f068051ee82a5",
  "ownerName": "Diego",
  "workflowId": "5f05cc03da205d2dfb2ad773",
  "workflowName": "Churn Prevention",
  "workflowTaskId": "5ed7bba1492c366143976d13",
  "workflowTemplateId": "57fdd14e8be8ceb43f8b1bc6",
  "checklist": [
  {
  "title": "A"
  },
  {
  "title": "B"
  },
  {
  "title": "C"
  }
  ],
  "sortPosition": 1,
  "snippet": "",
  "endusers": [],
  "users": [],
  "children": [
  {
  "_id": "5f6889608baac92465787bf4"
  }
  ],
  "comments": [],
  "__v": 0,
  "custom": {
  "HScore": 0
  },
  "workflowStepId": "5f05cc03da205d2dfb2ad775"
  },
  {
  "_id": "5f317749604a74699f58f669",
  "mainType": "event",
  "noSpecificTime": true,
  "shared": false,
  "overdueNotified": false,
  "activityTags": [],
  "isArchived": false,
  "status": "In-progress",
  "companyId": "5942d6dfd4333a2f083011e8",
  "companyName": "iBM",
  "workflowId": "5f317728604a74699f58f65f",
  "workflowName": "Test Playbook",
  "workflowTemplateId": "5f317715d2b1cc0ebb619beb",
  "action": "Test Event",
  "description": "<p>Book a thing</p><p>Was it fun?</p>",
  "ownerId": "54ddc90a3570c76e2cbd08a5",
  "ownerName": "Niklas",
  "snippet": "Book a thing\n\nWas it fun?",
  "endusers": [],
  "users": [],
  "children": [],
  "comments": [],
  "checklist": [],
  "__v": 0,
  "custom": {
  "HScore": 0
  },
  "workflowStepId": "5f317749604a74699f58f669"
  }
 ]

Get tasks List

Get

When fetching multiple tasks 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 500, max. 10000.
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.
enduserIds: Filter using endusers id. Multiple ids can be used separating them by commas.
isArchived: Filter archived or not archived status. Default as false and this endpoint will return objects where the mainType is event and task.

Example Request

curl --location -g --request GET 'https://api.planhat.com/tasks?limit=2&offset=0' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

'[
  {
  "_id": "5da4bbec7b1616495b53a35b",
  "mainType": "task",
  "noSpecificTime": true,
  "shared": false,
  "overdueNotified": false,
  "activityTags": [],
  "isArchived": false,
  "ownerId": "5524481f516d59216a6d2b80",
  "companyId": "56bccdf554d64d837d01be96",
  "companyName": "Daimler Group",
  "createdAt": "2022-07-05T09:51:52.818Z",
  "updatedAt": "2022-07-05T09:51:52.818Z",
  "startTime": null,
  "action": "Send them gift card",
  "ownerName": "Sarah",
  "endusers": [],
  "users": [],
  "children": [],
  "comments": [],
  "checklist": [],
  "__v": 0,
  "repeat": null,
  "custom": {
  "HScore": 0
  }
  },
  {
  "_id": "5db866ceab7aac67dc3637c8",
  "mainType": "task",
  "noSpecificTime": true,
  "shared": false,
  "overdueNotified": false,
  "activityTags": [],
  "isArchived": false,
  "action": "Sub activity",
  "description": "",
  "companyId": "56ccc2d39b760ff232295794",
  "companyName": "Grand Hotels",
  "ownerId": "54ddc90a3570c76e2cbd08a5",
  "ownerName": "Niklas",
  "workflowId": "5db866ceab7aac67dc3637be",
  "workflowName": "QBR",
  "workflowTaskId": "5d27408853372f7cd1170407",
  "checklist": [],
  "parent": "5db866ceab7aac67dc3637c6",
  "sortPosition": 5,
  "snippet": "",
  "endusers": [],
  "users": [],
  "children": [],
  "comments": [],
  "__v": 0,
  "workflowTemplateId": "5a57d7754b5f1d13128a0533",
  "repeat": null,
  "custom": {
  "HScore": 0
  },
  "workflowStepId": "5db866ceab7aac67dc3637c8"
  },
  {
  "_id": "5f05cc03da205d2dfb2ad775",
  "mainType": "event",
  "noSpecificTime": true,
  "shared": true,
  "overdueNotified": false,
  "activityTags": [],
  "isArchived": false,
  "action": "Test",
  "description": "",
  "companyId": "56bccdf554d64d837d01be55",
  "companyName": "Sweco",
  "ownerId": "564b063a508f068051ee82a5",
  "ownerName": "Diego",
  "workflowId": "5f05cc03da205d2dfb2ad773",
  "workflowName": "Churn Prevention",
  "workflowTaskId": "5ed7bba1492c366143976d13",
  "workflowTemplateId": "57fdd14e8be8ceb43f8b1bc6",
  "checklist": [
  {
  "title": "A"
  },
  {
  "title": "B"
  },
  {
  "title": "C"
  }
  ],
  "sortPosition": 1,
  "snippet": "",
  "endusers": [],
  "users": [],
  "children": [
  {
  "_id": "5f6889608baac92465787bf4"
  }
  ],
  "comments": [],
  "__v": 0,
  "custom": {
  "HScore": 0
  },
  "workflowStepId": "5f05cc03da205d2dfb2ad775"
  },
  {
  "_id": "5f317749604a74699f58f669",
  "mainType": "event",
  "noSpecificTime": true,
  "shared": false,
  "overdueNotified": false,
  "activityTags": [],
  "isArchived": false,
  "status": "In-progress",
  "companyId": "5942d6dfd4333a2f083011e8",
  "companyName": "iBM",
  "workflowId": "5f317728604a74699f58f65f",
  "workflowName": "Test Playbook",
  "workflowTemplateId": "5f317715d2b1cc0ebb619beb",
  "action": "Test Event",
  "description": "<p>Book a thing</p><p>Was it fun?</p>",
  "ownerId": "54ddc90a3570c76e2cbd08a5",
  "ownerName": "Niklas",
  "snippet": "Book a thing\n\nWas it fun?",
  "endusers": [],
  "users": [],
  "children": [],
  "comments": [],
  "checklist": [],
  "__v": 0,
  "custom": {
  "HScore": 0
  },
  "workflowStepId": "5f317749604a74699f58f669"
  }
 ]

Get tasks List

Get

When fetching multiple tasks 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 500, max. 10000.
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.
enduserIds: Filter using endusers id. Multiple ids can be used separating them by commas.
isArchived: Filter archived or not archived status. Default as false and this endpoint will return objects where the mainType is event and task.

Example Request

curl --location -g --request GET 'https://api.planhat.com/tasks?limit=2&offset=0' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

'[
  {
  "_id": "5da4bbec7b1616495b53a35b",
  "mainType": "task",
  "noSpecificTime": true,
  "shared": false,
  "overdueNotified": false,
  "activityTags": [],
  "isArchived": false,
  "ownerId": "5524481f516d59216a6d2b80",
  "companyId": "56bccdf554d64d837d01be96",
  "companyName": "Daimler Group",
  "createdAt": "2022-07-05T09:51:52.818Z",
  "updatedAt": "2022-07-05T09:51:52.818Z",
  "startTime": null,
  "action": "Send them gift card",
  "ownerName": "Sarah",
  "endusers": [],
  "users": [],
  "children": [],
  "comments": [],
  "checklist": [],
  "__v": 0,
  "repeat": null,
  "custom": {
  "HScore": 0
  }
  },
  {
  "_id": "5db866ceab7aac67dc3637c8",
  "mainType": "task",
  "noSpecificTime": true,
  "shared": false,
  "overdueNotified": false,
  "activityTags": [],
  "isArchived": false,
  "action": "Sub activity",
  "description": "",
  "companyId": "56ccc2d39b760ff232295794",
  "companyName": "Grand Hotels",
  "ownerId": "54ddc90a3570c76e2cbd08a5",
  "ownerName": "Niklas",
  "workflowId": "5db866ceab7aac67dc3637be",
  "workflowName": "QBR",
  "workflowTaskId": "5d27408853372f7cd1170407",
  "checklist": [],
  "parent": "5db866ceab7aac67dc3637c6",
  "sortPosition": 5,
  "snippet": "",
  "endusers": [],
  "users": [],
  "children": [],
  "comments": [],
  "__v": 0,
  "workflowTemplateId": "5a57d7754b5f1d13128a0533",
  "repeat": null,
  "custom": {
  "HScore": 0
  },
  "workflowStepId": "5db866ceab7aac67dc3637c8"
  },
  {
  "_id": "5f05cc03da205d2dfb2ad775",
  "mainType": "event",
  "noSpecificTime": true,
  "shared": true,
  "overdueNotified": false,
  "activityTags": [],
  "isArchived": false,
  "action": "Test",
  "description": "",
  "companyId": "56bccdf554d64d837d01be55",
  "companyName": "Sweco",
  "ownerId": "564b063a508f068051ee82a5",
  "ownerName": "Diego",
  "workflowId": "5f05cc03da205d2dfb2ad773",
  "workflowName": "Churn Prevention",
  "workflowTaskId": "5ed7bba1492c366143976d13",
  "workflowTemplateId": "57fdd14e8be8ceb43f8b1bc6",
  "checklist": [
  {
  "title": "A"
  },
  {
  "title": "B"
  },
  {
  "title": "C"
  }
  ],
  "sortPosition": 1,
  "snippet": "",
  "endusers": [],
  "users": [],
  "children": [
  {
  "_id": "5f6889608baac92465787bf4"
  }
  ],
  "comments": [],
  "__v": 0,
  "custom": {
  "HScore": 0
  },
  "workflowStepId": "5f05cc03da205d2dfb2ad775"
  },
  {
  "_id": "5f317749604a74699f58f669",
  "mainType": "event",
  "noSpecificTime": true,
  "shared": false,
  "overdueNotified": false,
  "activityTags": [],
  "isArchived": false,
  "status": "In-progress",
  "companyId": "5942d6dfd4333a2f083011e8",
  "companyName": "iBM",
  "workflowId": "5f317728604a74699f58f65f",
  "workflowName": "Test Playbook",
  "workflowTemplateId": "5f317715d2b1cc0ebb619beb",
  "action": "Test Event",
  "description": "<p>Book a thing</p><p>Was it fun?</p>",
  "ownerId": "54ddc90a3570c76e2cbd08a5",
  "ownerName": "Niklas",
  "snippet": "Book a thing\n\nWas it fun?",
  "endusers": [],
  "users": [],
  "children": [],
  "comments": [],
  "checklist": [],
  "__v": 0,
  "custom": {
  "HScore": 0
  },
  "workflowStepId": "5f317749604a74699f58f669"
  }
 ]

Delete tasks

Delete

To delete a task 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/tasks/6102c9748084189dcbf0df60' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

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

Delete tasks

Delete

To delete a task 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/tasks/6102c9748084189dcbf0df60' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

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

Delete tasks

Delete

To delete a task 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/tasks/6102c9748084189dcbf0df60' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

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

Bulk Upsert tasks

Put

To create a task it's required to define a mainType and a valid companyId.

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

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

If the mainType is not specified it will be created with the default value: "task"

It is recommended to set the action field, think of it as the task's title e.g. "Send Invoice"

Since this is a bulk upsert operation it's possible to create and/or update multiple tasks 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/tasks' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '[{
  "mainType": "task",
  "startTime": "2022-07-05T14:02:16.181Z",
  "ownerId": "61f91285d40d7d112020c7b6",
  "ownerName": "Ernesto",
  "action": "First Onboard Call",
  "companyId": "5fd76c4daf9f4601dd313b05",
  "checklist": [{
  "title": "Prepare Material"
  },
  {
  "title": "Present"
  }
  ]
 },
 {
  "mainType": "task",
  "startTime": "2022-07-05T14:02:16.181Z",
  "ownerId": "61f91285d40d7d112020c7b6",
  "ownerName": "Ernesto",
  "action": "Send Invoice",
  "checklist": [],
  "companyId": "60c10846108183032f05bd67"
 },
 {
  "mainType": "task",
  "startTime": "2022-07-05T14:02:16.181Z",
  "ownerId": "61f91285d40d7d112020c7b6",
  "ownerName": "Ernesto",
  "companyId": "60c1075808f652259315e270",
  "action": "Creating Tasks in bulk",
  "description": "<p>Description</p>",
  "checklist": [{
  "title": "Step 1"
  },
  {
  "title": "Step 2"
  }
  ]
 }
 ]'

Example Response

200 ok

'{
  "created": 3,
  "createdErrors": [],
  "insertsKeys": [
  {
  "_id": "62c549dcfde99d59485c3314"
  },
  {
  "_id": "62c549dcfde99d59485c3315"
  },
  {
  "_id": "62c549dcfde99d59485c3316"
  }
  ],
  "updated": 0,
  "updatedErrors": [],
  "updatesKeys": [],
  "nonupdates": 0,
  "modified": [],
  "upsertedIds": [
  "62c549dcfde99d59485c3314",
  "62c549dcfde99d59485c3315",
  "62c549dcfde99d59485c3316"
  ],
  "permissionErrors": []
 }'

Bulk Upsert tasks

Put

To create a task it's required to define a mainType and a valid companyId.

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

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

If the mainType is not specified it will be created with the default value: "task"

It is recommended to set the action field, think of it as the task's title e.g. "Send Invoice"

Since this is a bulk upsert operation it's possible to create and/or update multiple tasks 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/tasks' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '[{
  "mainType": "task",
  "startTime": "2022-07-05T14:02:16.181Z",
  "ownerId": "61f91285d40d7d112020c7b6",
  "ownerName": "Ernesto",
  "action": "First Onboard Call",
  "companyId": "5fd76c4daf9f4601dd313b05",
  "checklist": [{
  "title": "Prepare Material"
  },
  {
  "title": "Present"
  }
  ]
 },
 {
  "mainType": "task",
  "startTime": "2022-07-05T14:02:16.181Z",
  "ownerId": "61f91285d40d7d112020c7b6",
  "ownerName": "Ernesto",
  "action": "Send Invoice",
  "checklist": [],
  "companyId": "60c10846108183032f05bd67"
 },
 {
  "mainType": "task",
  "startTime": "2022-07-05T14:02:16.181Z",
  "ownerId": "61f91285d40d7d112020c7b6",
  "ownerName": "Ernesto",
  "companyId": "60c1075808f652259315e270",
  "action": "Creating Tasks in bulk",
  "description": "<p>Description</p>",
  "checklist": [{
  "title": "Step 1"
  },
  {
  "title": "Step 2"
  }
  ]
 }
 ]'

Example Response

200 ok

'{
  "created": 3,
  "createdErrors": [],
  "insertsKeys": [
  {
  "_id": "62c549dcfde99d59485c3314"
  },
  {
  "_id": "62c549dcfde99d59485c3315"
  },
  {
  "_id": "62c549dcfde99d59485c3316"
  }
  ],
  "updated": 0,
  "updatedErrors": [],
  "updatesKeys": [],
  "nonupdates": 0,
  "modified": [],
  "upsertedIds": [
  "62c549dcfde99d59485c3314",
  "62c549dcfde99d59485c3315",
  "62c549dcfde99d59485c3316"
  ],
  "permissionErrors": []
 }'

Bulk Upsert tasks

Put

To create a task it's required to define a mainType and a valid companyId.

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

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

If the mainType is not specified it will be created with the default value: "task"

It is recommended to set the action field, think of it as the task's title e.g. "Send Invoice"

Since this is a bulk upsert operation it's possible to create and/or update multiple tasks 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/tasks' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '[{
  "mainType": "task",
  "startTime": "2022-07-05T14:02:16.181Z",
  "ownerId": "61f91285d40d7d112020c7b6",
  "ownerName": "Ernesto",
  "action": "First Onboard Call",
  "companyId": "5fd76c4daf9f4601dd313b05",
  "checklist": [{
  "title": "Prepare Material"
  },
  {
  "title": "Present"
  }
  ]
 },
 {
  "mainType": "task",
  "startTime": "2022-07-05T14:02:16.181Z",
  "ownerId": "61f91285d40d7d112020c7b6",
  "ownerName": "Ernesto",
  "action": "Send Invoice",
  "checklist": [],
  "companyId": "60c10846108183032f05bd67"
 },
 {
  "mainType": "task",
  "startTime": "2022-07-05T14:02:16.181Z",
  "ownerId": "61f91285d40d7d112020c7b6",
  "ownerName": "Ernesto",
  "companyId": "60c1075808f652259315e270",
  "action": "Creating Tasks in bulk",
  "description": "<p>Description</p>",
  "checklist": [{
  "title": "Step 1"
  },
  {
  "title": "Step 2"
  }
  ]
 }
 ]'

Example Response

200 ok

'{
  "created": 3,
  "createdErrors": [],
  "insertsKeys": [
  {
  "_id": "62c549dcfde99d59485c3314"
  },
  {
  "_id": "62c549dcfde99d59485c3315"
  },
  {
  "_id": "62c549dcfde99d59485c3316"
  }
  ],
  "updated": 0,
  "updatedErrors": [],
  "updatesKeys": [],
  "nonupdates": 0,
  "modified": [],
  "upsertedIds": [
  "62c549dcfde99d59485c3314",
  "62c549dcfde99d59485c3315",
  "62c549dcfde99d59485c3316"
  ],
  "permissionErrors": []
 }'

Developers

API /

Task

Task

Property

Required

Type

Description

Property

Required

Type

Description

Property

Required

Type

Description

Create task

Create task

Create task

Update task

Example:

Update task

Example:

Update task

Example:

Get tasks by ID

Example:

Get tasks by ID

Example:

Get tasks by ID

Example:

Get tasks List

Get tasks List

Get tasks List

Delete tasks

Delete tasks

Delete tasks

Bulk Upsert tasks

Bulk Upsert tasks

Bulk Upsert tasks