Planhat | The Unified Customer Platform

Developers

Conversation

Conversations can be of different types such as email, chat, support tickets, and manually logged notes. You can also create your own types in Planhat to represent things such as "in person meeting", "Training", etc. The default types (email, chat, ticket, call) are reserved and should not be created over API.

Property	Required	Type	Description
_id		objectId	Planhat identifier.
subject		string	Title of the conversation.
companyId	Yes	objectId	Related company id (planhat identifier).
companyName		string	Company name. (Autogenerated).
description		string	Description of the conversation.
snippet		string	Formatted content of the conversation.
date		string	ISO date when conversation was created.
outDate		string	ISO date when conversation was sent.
createDate		string	ISO date when conversation was created. (Autogenerated).
type		string	Type of conversation. Must reference a pre-existent conversation type in Planhat, or it will default to type: note.
users		array	Array of user objects.
endusers		array	Array of involved contacts (endusers ids). (Autogenerated).
externalId		string	The conversation id in your own system.
activityTags		array	Array of strings to tag your notes.
starred		boolean	Flag to mark a conversation as important or relevant.
pinned		boolean	Pin a conversation at the top of the company and/or user profile.
emailTemplateIds		array	Array of email template ids. (Autogenerated).
isOpen		boolean	Set a conversation or ticket as open or not, mostly related to CRM integrations. (Autogenerated).
tags		array	Array of strings to tag the conversation. (Autogenerated).
waitsToBeFiltered		boolean	Internal system field. (Autogenerated).
timeBucket		array	Internal system field. (Autogenerated).
archived		boolean	Mark a conversation as archived.
numberOfParts		integer	Internal system field. (Autogenerated).
sender		array	Array of objects containing sender information. (Autogenerated).
history		array	Internal system field. (Autogenerated).
userIds		array	Array of user ids involved in the conversation. (Autogenerated).
hasMore		boolean	Internal system field. (Autogenerated).
isCustomType		boolean	Mark the conversation as custom type or not. (Autogenerated).
assigneeName		string	Internal system field. (Autogenerated).
numberOfRelevantParts		integer	Internal system field. (Autogenerated).
hasAttachments		boolean	Set to true if the conversation has attachments. (Autogenerated).
isSeen		boolean	Set to true to flag the conversation as seen. (Autogenerated).
custom		object	Custom object with your custom properties.

Property	Required	Type	Description
_id		objectId	Planhat identifier.
subject		string	Title of the conversation.
companyId	Yes	objectId	Related company id (planhat identifier).
companyName		string	Company name. (Autogenerated).
description		string	Description of the conversation.
snippet		string	Formatted content of the conversation.
date		string	ISO date when conversation was created.
outDate		string	ISO date when conversation was sent.
createDate		string	ISO date when conversation was created. (Autogenerated).
type		string	Type of conversation. Must reference a pre-existent conversation type in Planhat, or it will default to type: note.
users		array	Array of user objects.
endusers		array	Array of involved contacts (endusers ids). (Autogenerated).
externalId		string	The conversation id in your own system.
activityTags		array	Array of strings to tag your notes.
starred		boolean	Flag to mark a conversation as important or relevant.
pinned		boolean	Pin a conversation at the top of the company and/or user profile.
emailTemplateIds		array	Array of email template ids. (Autogenerated).
isOpen		boolean	Set a conversation or ticket as open or not, mostly related to CRM integrations. (Autogenerated).
tags		array	Array of strings to tag the conversation. (Autogenerated).
waitsToBeFiltered		boolean	Internal system field. (Autogenerated).
timeBucket		array	Internal system field. (Autogenerated).
archived		boolean	Mark a conversation as archived.
numberOfParts		integer	Internal system field. (Autogenerated).
sender		array	Array of objects containing sender information. (Autogenerated).
history		array	Internal system field. (Autogenerated).
userIds		array	Array of user ids involved in the conversation. (Autogenerated).
hasMore		boolean	Internal system field. (Autogenerated).
isCustomType		boolean	Mark the conversation as custom type or not. (Autogenerated).
assigneeName		string	Internal system field. (Autogenerated).
numberOfRelevantParts		integer	Internal system field. (Autogenerated).
hasAttachments		boolean	Set to true if the conversation has attachments. (Autogenerated).
isSeen		boolean	Set to true to flag the conversation as seen. (Autogenerated).
custom		object	Custom object with your custom properties.

Property	Required	Type	Description
_id		objectId	Planhat identifier.
subject		string	Title of the conversation.
companyId	Yes	objectId	Related company id (planhat identifier).
companyName		string	Company name. (Autogenerated).
description		string	Description of the conversation.
snippet		string	Formatted content of the conversation.
date		string	ISO date when conversation was created.
outDate		string	ISO date when conversation was sent.
createDate		string	ISO date when conversation was created. (Autogenerated).
type		string	Type of conversation. Must reference a pre-existent conversation type in Planhat, or it will default to type: note.
users		array	Array of user objects.
endusers		array	Array of involved contacts (endusers ids). (Autogenerated).
externalId		string	The conversation id in your own system.
activityTags		array	Array of strings to tag your notes.
starred		boolean	Flag to mark a conversation as important or relevant.
pinned		boolean	Pin a conversation at the top of the company and/or user profile.
emailTemplateIds		array	Array of email template ids. (Autogenerated).
isOpen		boolean	Set a conversation or ticket as open or not, mostly related to CRM integrations. (Autogenerated).
tags		array	Array of strings to tag the conversation. (Autogenerated).
waitsToBeFiltered		boolean	Internal system field. (Autogenerated).
timeBucket		array	Internal system field. (Autogenerated).
archived		boolean	Mark a conversation as archived.
numberOfParts		integer	Internal system field. (Autogenerated).
sender		array	Array of objects containing sender information. (Autogenerated).
history		array	Internal system field. (Autogenerated).
userIds		array	Array of user ids involved in the conversation. (Autogenerated).
hasMore		boolean	Internal system field. (Autogenerated).
isCustomType		boolean	Mark the conversation as custom type or not. (Autogenerated).
assigneeName		string	Internal system field. (Autogenerated).
numberOfRelevantParts		integer	Internal system field. (Autogenerated).
hasAttachments		boolean	Set to true if the conversation has attachments. (Autogenerated).
isSeen		boolean	Set to true to flag the conversation as seen. (Autogenerated).
custom		object	Custom object with your custom properties.

Create conversation

Post

To create a conversation, 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]".

Example Request

curl --location -g --request POST 'https://api.planhat.com/conversations' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "users": [
  {
  "id": "58e231b14246fc73139f29e8"
  }
  ],
  "date": "2021-07-29T15:29:34.330Z",
  "type": "note",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "subject": "New conversation",
  "description": "Little call with the client.",
  "endusers": [
  {
  "id": "610091916d643a7c418aef42"
  }
  ],
  "activityTags": [],
  "useSubject": true,
  "ownerId": "58e231b14246fc73139f29e8"
 }'

Example Response

200 ok

'{
  "starred": false,
  "pinned": false,
  "autoTags": [],
  "activityTags": [],
  "emailTemplateIds": [],
  "isOpen": false,
  "tags": [],
  "waitsToBeFiltered": true,
  "timeBucket": [],
  "archived": false,
  "_id": "6102e3b08084189dcbf0e3f0",
  "users": [
  {
  "id": "58e231b14246fc73139f29e8",
  "name": "Alex",
  "isOwner": true
  }
  ],
  "date": "2021-07-29T15:29:34.330Z",
  "type": "note",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "subject": "New conversation",
  "description": "Little call with the client.",
  "endusers": [
  {
  "id": "610091916d643a7c418aef42",
  "name": "Lara Croft"
  }
  ],
  "snippet": "Little call with the client.",
  "companyName": "Tenet",
  "createDate": "2021-07-29T17:21:52.347Z",
  "sender": [],
  "history": [],
  "__v": 0,
  "owner": "60ccb1c5965cc9e0f3848075",
  "followers": [],
  "userId": "610015551b990c65d4fb0a4c",
  "note": "New conversation: Little call with the client.",
  "nickName": "Test user"
 }'

Create conversation

Post

To create a conversation, 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]".

Example Request

curl --location -g --request POST 'https://api.planhat.com/conversations' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "users": [
  {
  "id": "58e231b14246fc73139f29e8"
  }
  ],
  "date": "2021-07-29T15:29:34.330Z",
  "type": "note",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "subject": "New conversation",
  "description": "Little call with the client.",
  "endusers": [
  {
  "id": "610091916d643a7c418aef42"
  }
  ],
  "activityTags": [],
  "useSubject": true,
  "ownerId": "58e231b14246fc73139f29e8"
 }'

Example Response

200 ok

'{
  "starred": false,
  "pinned": false,
  "autoTags": [],
  "activityTags": [],
  "emailTemplateIds": [],
  "isOpen": false,
  "tags": [],
  "waitsToBeFiltered": true,
  "timeBucket": [],
  "archived": false,
  "_id": "6102e3b08084189dcbf0e3f0",
  "users": [
  {
  "id": "58e231b14246fc73139f29e8",
  "name": "Alex",
  "isOwner": true
  }
  ],
  "date": "2021-07-29T15:29:34.330Z",
  "type": "note",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "subject": "New conversation",
  "description": "Little call with the client.",
  "endusers": [
  {
  "id": "610091916d643a7c418aef42",
  "name": "Lara Croft"
  }
  ],
  "snippet": "Little call with the client.",
  "companyName": "Tenet",
  "createDate": "2021-07-29T17:21:52.347Z",
  "sender": [],
  "history": [],
  "__v": 0,
  "owner": "60ccb1c5965cc9e0f3848075",
  "followers": [],
  "userId": "610015551b990c65d4fb0a4c",
  "note": "New conversation: Little call with the client.",
  "nickName": "Test user"
 }'

Create conversation

Post

To create a conversation, 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]".

Example Request

curl --location -g --request POST 'https://api.planhat.com/conversations' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "users": [
  {
  "id": "58e231b14246fc73139f29e8"
  }
  ],
  "date": "2021-07-29T15:29:34.330Z",
  "type": "note",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "subject": "New conversation",
  "description": "Little call with the client.",
  "endusers": [
  {
  "id": "610091916d643a7c418aef42"
  }
  ],
  "activityTags": [],
  "useSubject": true,
  "ownerId": "58e231b14246fc73139f29e8"
 }'

Example Response

200 ok

'{
  "starred": false,
  "pinned": false,
  "autoTags": [],
  "activityTags": [],
  "emailTemplateIds": [],
  "isOpen": false,
  "tags": [],
  "waitsToBeFiltered": true,
  "timeBucket": [],
  "archived": false,
  "_id": "6102e3b08084189dcbf0e3f0",
  "users": [
  {
  "id": "58e231b14246fc73139f29e8",
  "name": "Alex",
  "isOwner": true
  }
  ],
  "date": "2021-07-29T15:29:34.330Z",
  "type": "note",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "subject": "New conversation",
  "description": "Little call with the client.",
  "endusers": [
  {
  "id": "610091916d643a7c418aef42",
  "name": "Lara Croft"
  }
  ],
  "snippet": "Little call with the client.",
  "companyName": "Tenet",
  "createDate": "2021-07-29T17:21:52.347Z",
  "sender": [],
  "history": [],
  "__v": 0,
  "owner": "60ccb1c5965cc9e0f3848075",
  "followers": [],
  "userId": "610015551b990c65d4fb0a4c",
  "note": "New conversation: Little call with the client.",
  "nickName": "Test user"
 }'

Update conversation

Put

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

Alternately it’s possible to update using the conversation externalId and/or sourceId adding a prefix and passing one of these keyables as identifiers.

Example:

Example Request

curl --location -g --request PUT 'https://api.planhat.com/conversations/6102e3b08084189dcbf0e3f0' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "subject": "Chat with the client",
  "description": "<p>Slack chat with the client.</p>"
 }'

Example Response

200 ok

'{
  "_id": "6102e3b08084189dcbf0e3f0",
  "starred": false,
  "pinned": false,
  "autoTags": [],
  "activityTags": [],
  "emailTemplateIds": [],
  "isOpen": false,
  "tags": [],
  "waitsToBeFiltered": true,
  "timeBucket": [],
  "archived": false,
  "users": [
  {
  "id": "58e231b14246fc73139f29e8",
  "name": "Alex",
  "isOwner": true
  }
  ],
  "date": "2021-07-29T15:29:34.330Z",
  "type": "note",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "subject": "Chat with the client",
  "description": "Slack chat with the client.",
  "endusers": [
  {
  "id": "610091916d643a7c418aef42",
  "name": "Lara Croft"
  }
  ],
  "snippet": "Slack chat with the client.",
  "companyName": "Tenet",
  "createDate": "2021-07-29T17:21:52.347Z",
  "sender": [],
  "history": [],
  "__v": 0
 }'

Update conversation

Put

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

Alternately it’s possible to update using the conversation externalId and/or sourceId adding a prefix and passing one of these keyables as identifiers.

Example:

Example Request

curl --location -g --request PUT 'https://api.planhat.com/conversations/6102e3b08084189dcbf0e3f0' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "subject": "Chat with the client",
  "description": "<p>Slack chat with the client.</p>"
 }'

Example Response

200 ok

'{
  "_id": "6102e3b08084189dcbf0e3f0",
  "starred": false,
  "pinned": false,
  "autoTags": [],
  "activityTags": [],
  "emailTemplateIds": [],
  "isOpen": false,
  "tags": [],
  "waitsToBeFiltered": true,
  "timeBucket": [],
  "archived": false,
  "users": [
  {
  "id": "58e231b14246fc73139f29e8",
  "name": "Alex",
  "isOwner": true
  }
  ],
  "date": "2021-07-29T15:29:34.330Z",
  "type": "note",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "subject": "Chat with the client",
  "description": "Slack chat with the client.",
  "endusers": [
  {
  "id": "610091916d643a7c418aef42",
  "name": "Lara Croft"
  }
  ],
  "snippet": "Slack chat with the client.",
  "companyName": "Tenet",
  "createDate": "2021-07-29T17:21:52.347Z",
  "sender": [],
  "history": [],
  "__v": 0
 }'

Update conversation

Put

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

Alternately it’s possible to update using the conversation externalId and/or sourceId adding a prefix and passing one of these keyables as identifiers.

Example:

Example Request

curl --location -g --request PUT 'https://api.planhat.com/conversations/6102e3b08084189dcbf0e3f0' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "subject": "Chat with the client",
  "description": "<p>Slack chat with the client.</p>"
 }'

Example Response

200 ok

'{
  "_id": "6102e3b08084189dcbf0e3f0",
  "starred": false,
  "pinned": false,
  "autoTags": [],
  "activityTags": [],
  "emailTemplateIds": [],
  "isOpen": false,
  "tags": [],
  "waitsToBeFiltered": true,
  "timeBucket": [],
  "archived": false,
  "users": [
  {
  "id": "58e231b14246fc73139f29e8",
  "name": "Alex",
  "isOwner": true
  }
  ],
  "date": "2021-07-29T15:29:34.330Z",
  "type": "note",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "subject": "Chat with the client",
  "description": "Slack chat with the client.",
  "endusers": [
  {
  "id": "610091916d643a7c418aef42",
  "name": "Lara Croft"
  }
  ],
  "snippet": "Slack chat with the client.",
  "companyName": "Tenet",
  "createDate": "2021-07-29T17:21:52.347Z",
  "sender": [],
  "history": [],
  "__v": 0
 }'

Get conversations by ID

Get

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

Alternately it’s possible to get a conversation using its externalId adding a prefix and passing this keyable as identifiers.

Example:

Example Request

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

Example Response

200 ok

'{
  "_id": "58e57392c9437d10624593fd",
  "type": "email",
  "numberOfParts": 1,
  "hasAttachments": false,
  "source": "bcc",
  "subject": "Test 6 on Oct 21 from BCC",
  "snippet": "Two new and one existing endusers! ",
  "days": 17095,
  "companyId": "56e911619f2ff04215515515",
  "timeBucket": [
  "2016",
  "2016-Q4",
  "2016-10",
  "2016-W43"
  ],
  "history": [],
  "tags": [],
  "isOpen": false,
  "users": [
  {
  "id": "57225af2dfb33aa3022e88e9",
  "name": "Vargha",
  "isOwner": true
  }
  ],
  "endusers": [
  {
  "id": "5b47a07ff1846fd087ede384",
  "name": "Max Payne"
  }
  ],
  "date": "2016-10-21T15:24:05.000Z",
  "__v": 0,
  "companyName": "Bonnier",
  "createDate": "2016-10-21T15:24:05.000Z",
  "outDate": "2016-10-21T15:24:05.000Z",
  "numberOfRelevantParts": 1,
  "custom": {
  "Test FF field to check @today cron job": false,
  "t1": 0,
  "HScore": 0,
  "Days in Phase": 0,
  "NRR30": 0,
  "t123": "undefined",
  "Logins": 0,
  "Renewal in days": -1,
  "Activity Count": 0,
  "Week No": 29.285714285714285
  },
  "userIds": [
  "57225af2dfb33aa3022e88e9"
  ],
  "hasMore": true,
  "isCustomType": false,
  "assigneeName": "",
  "isSeen": false,
  "starred": false,
  "pinned": false,
  "archived": false
 }'

Get conversations by ID

Get

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

Alternately it’s possible to get a conversation using its externalId adding a prefix and passing this keyable as identifiers.

Example:

Example Request

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

Example Response

200 ok

'{
  "_id": "58e57392c9437d10624593fd",
  "type": "email",
  "numberOfParts": 1,
  "hasAttachments": false,
  "source": "bcc",
  "subject": "Test 6 on Oct 21 from BCC",
  "snippet": "Two new and one existing endusers! ",
  "days": 17095,
  "companyId": "56e911619f2ff04215515515",
  "timeBucket": [
  "2016",
  "2016-Q4",
  "2016-10",
  "2016-W43"
  ],
  "history": [],
  "tags": [],
  "isOpen": false,
  "users": [
  {
  "id": "57225af2dfb33aa3022e88e9",
  "name": "Vargha",
  "isOwner": true
  }
  ],
  "endusers": [
  {
  "id": "5b47a07ff1846fd087ede384",
  "name": "Max Payne"
  }
  ],
  "date": "2016-10-21T15:24:05.000Z",
  "__v": 0,
  "companyName": "Bonnier",
  "createDate": "2016-10-21T15:24:05.000Z",
  "outDate": "2016-10-21T15:24:05.000Z",
  "numberOfRelevantParts": 1,
  "custom": {
  "Test FF field to check @today cron job": false,
  "t1": 0,
  "HScore": 0,
  "Days in Phase": 0,
  "NRR30": 0,
  "t123": "undefined",
  "Logins": 0,
  "Renewal in days": -1,
  "Activity Count": 0,
  "Week No": 29.285714285714285
  },
  "userIds": [
  "57225af2dfb33aa3022e88e9"
  ],
  "hasMore": true,
  "isCustomType": false,
  "assigneeName": "",
  "isSeen": false,
  "starred": false,
  "pinned": false,
  "archived": false
 }'

Get conversations by ID

Get

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

Alternately it’s possible to get a conversation using its externalId adding a prefix and passing this keyable as identifiers.

Example:

Example Request

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

Example Response

200 ok

'{
  "_id": "58e57392c9437d10624593fd",
  "type": "email",
  "numberOfParts": 1,
  "hasAttachments": false,
  "source": "bcc",
  "subject": "Test 6 on Oct 21 from BCC",
  "snippet": "Two new and one existing endusers! ",
  "days": 17095,
  "companyId": "56e911619f2ff04215515515",
  "timeBucket": [
  "2016",
  "2016-Q4",
  "2016-10",
  "2016-W43"
  ],
  "history": [],
  "tags": [],
  "isOpen": false,
  "users": [
  {
  "id": "57225af2dfb33aa3022e88e9",
  "name": "Vargha",
  "isOwner": true
  }
  ],
  "endusers": [
  {
  "id": "5b47a07ff1846fd087ede384",
  "name": "Max Payne"
  }
  ],
  "date": "2016-10-21T15:24:05.000Z",
  "__v": 0,
  "companyName": "Bonnier",
  "createDate": "2016-10-21T15:24:05.000Z",
  "outDate": "2016-10-21T15:24:05.000Z",
  "numberOfRelevantParts": 1,
  "custom": {
  "Test FF field to check @today cron job": false,
  "t1": 0,
  "HScore": 0,
  "Days in Phase": 0,
  "NRR30": 0,
  "t123": "undefined",
  "Logins": 0,
  "Renewal in days": -1,
  "Activity Count": 0,
  "Week No": 29.285714285714285
  },
  "userIds": [
  "57225af2dfb33aa3022e88e9"
  ],
  "hasMore": true,
  "isCustomType": false,
  "assigneeName": "",
  "isSeen": false,
  "starred": false,
  "pinned": false,
  "archived": false
 }'

Get conversations List

Get

When fetching multiple conversations 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 30, 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/conversations?limit=2&offset=0' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

'[
  {
  "date": "2021-07-29T15:29:34.330Z",
  "userIds": [
  "58e231b14246fc73139f29e8"
  ],
  "hasMore": false,
  "isCustomType": false,
  "subject": "Chat with the client",
  "snippet": "Slack chat with the client.",
  "_id": "6102e3b08084189dcbf0e3f0",
  "type": "note",
  "tags": [],
  "createDate": "2021-07-29T17:21:52.347Z",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "companyName": "Leo company",
  "users": [
  {
  "id": "58e231b14246fc73139f29e8",
  "name": "Alex",
  "isOwner": true
  }
  ],
  "endusers": [
  {
  "id": "610091916d643a7c418aef42",
  "name": "Lara Croft"
  }
  ],
  "assigneeName": "",
  "activityTags": [],
  "hasAttachments": false,
  "isSeen": false,
  "starred": false,
  "pinned": false,
  "archived": false
  },
  {
  "date": "2021-07-26T16:51:44.146Z",
  "userIds": [
  "5f16fd8eee876638a9f2483c"
  ],
  "isCustomType": false,
  "subject": "t6",
  "_id": "60fee824a4c764252c877c2b",
  "type": "note",
  "tags": [],
  "createDate": "2021-07-26T16:51:48.720Z",
  "companyId": "584d9d5505ba1b622f04adb3",
  "companyName": "Daimler North America",
  "users": [
  {
  "id": "5f16fd8eee876638a9f2483c",
  "name": "Ernesto",
  "isOwner": true
  }
  ],
  "endusers": [],
  "assigneeName": "",
  "activityTags": [],
  "hasAttachments": false,
  "isSeen": false,
  "starred": false,
  "pinned": false,
  "archived": false,
  "custom": {
  "Activity Count": 0,
  "Days in Phase": 0,
  "Logins": 0
  }
  }
 ]'

Get conversations List

Get

When fetching multiple conversations 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 30, 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/conversations?limit=2&offset=0' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

'[
  {
  "date": "2021-07-29T15:29:34.330Z",
  "userIds": [
  "58e231b14246fc73139f29e8"
  ],
  "hasMore": false,
  "isCustomType": false,
  "subject": "Chat with the client",
  "snippet": "Slack chat with the client.",
  "_id": "6102e3b08084189dcbf0e3f0",
  "type": "note",
  "tags": [],
  "createDate": "2021-07-29T17:21:52.347Z",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "companyName": "Leo company",
  "users": [
  {
  "id": "58e231b14246fc73139f29e8",
  "name": "Alex",
  "isOwner": true
  }
  ],
  "endusers": [
  {
  "id": "610091916d643a7c418aef42",
  "name": "Lara Croft"
  }
  ],
  "assigneeName": "",
  "activityTags": [],
  "hasAttachments": false,
  "isSeen": false,
  "starred": false,
  "pinned": false,
  "archived": false
  },
  {
  "date": "2021-07-26T16:51:44.146Z",
  "userIds": [
  "5f16fd8eee876638a9f2483c"
  ],
  "isCustomType": false,
  "subject": "t6",
  "_id": "60fee824a4c764252c877c2b",
  "type": "note",
  "tags": [],
  "createDate": "2021-07-26T16:51:48.720Z",
  "companyId": "584d9d5505ba1b622f04adb3",
  "companyName": "Daimler North America",
  "users": [
  {
  "id": "5f16fd8eee876638a9f2483c",
  "name": "Ernesto",
  "isOwner": true
  }
  ],
  "endusers": [],
  "assigneeName": "",
  "activityTags": [],
  "hasAttachments": false,
  "isSeen": false,
  "starred": false,
  "pinned": false,
  "archived": false,
  "custom": {
  "Activity Count": 0,
  "Days in Phase": 0,
  "Logins": 0
  }
  }
 ]'

Get conversations List

Get

When fetching multiple conversations 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 30, 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/conversations?limit=2&offset=0' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

'[
  {
  "date": "2021-07-29T15:29:34.330Z",
  "userIds": [
  "58e231b14246fc73139f29e8"
  ],
  "hasMore": false,
  "isCustomType": false,
  "subject": "Chat with the client",
  "snippet": "Slack chat with the client.",
  "_id": "6102e3b08084189dcbf0e3f0",
  "type": "note",
  "tags": [],
  "createDate": "2021-07-29T17:21:52.347Z",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "companyName": "Leo company",
  "users": [
  {
  "id": "58e231b14246fc73139f29e8",
  "name": "Alex",
  "isOwner": true
  }
  ],
  "endusers": [
  {
  "id": "610091916d643a7c418aef42",
  "name": "Lara Croft"
  }
  ],
  "assigneeName": "",
  "activityTags": [],
  "hasAttachments": false,
  "isSeen": false,
  "starred": false,
  "pinned": false,
  "archived": false
  },
  {
  "date": "2021-07-26T16:51:44.146Z",
  "userIds": [
  "5f16fd8eee876638a9f2483c"
  ],
  "isCustomType": false,
  "subject": "t6",
  "_id": "60fee824a4c764252c877c2b",
  "type": "note",
  "tags": [],
  "createDate": "2021-07-26T16:51:48.720Z",
  "companyId": "584d9d5505ba1b622f04adb3",
  "companyName": "Daimler North America",
  "users": [
  {
  "id": "5f16fd8eee876638a9f2483c",
  "name": "Ernesto",
  "isOwner": true
  }
  ],
  "endusers": [],
  "assigneeName": "",
  "activityTags": [],
  "hasAttachments": false,
  "isSeen": false,
  "starred": false,
  "pinned": false,
  "archived": false,
  "custom": {
  "Activity Count": 0,
  "Days in Phase": 0,
  "Logins": 0
  }
  }
 ]'

Delete conversations

Delete

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

Example Response

200 ok

'{
  "starred": false,
  "pinned": false,
  "autoTags": [],
  "activityTags": [],
  "emailTemplateIds": [],
  "isOpen": false,
  "tags": [],
  "waitsToBeFiltered": true,
  "timeBucket": [],
  "archived": false,
  "_id": "6102e3b08084189dcbf0e3f0",
  "users": [
  {
  "id": "58e231b14246fc73139f29e8",
  "name": "Alex",
  "isOwner": true
  }
  ],
  "date": "2021-07-29T15:29:34.330Z",
  "type": "note",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "subject": "Chat with the client",
  "description": "<p>Slack chat with the client.</p>",
  "endusers": [
  {
  "id": "610091916d643a7c418aef42",
  "name": "Lara Croft"
  }
  ],
  "snippet": "Slack chat with the client.",
  "companyName": "Leo company",
  "createDate": "2021-07-29T17:21:52.347Z",
  "sender": [],
  "history": [],
  "__v": 0
 }'

Delete conversations

Delete

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

Example Response

200 ok

'{
  "starred": false,
  "pinned": false,
  "autoTags": [],
  "activityTags": [],
  "emailTemplateIds": [],
  "isOpen": false,
  "tags": [],
  "waitsToBeFiltered": true,
  "timeBucket": [],
  "archived": false,
  "_id": "6102e3b08084189dcbf0e3f0",
  "users": [
  {
  "id": "58e231b14246fc73139f29e8",
  "name": "Alex",
  "isOwner": true
  }
  ],
  "date": "2021-07-29T15:29:34.330Z",
  "type": "note",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "subject": "Chat with the client",
  "description": "<p>Slack chat with the client.</p>",
  "endusers": [
  {
  "id": "610091916d643a7c418aef42",
  "name": "Lara Croft"
  }
  ],
  "snippet": "Slack chat with the client.",
  "companyName": "Leo company",
  "createDate": "2021-07-29T17:21:52.347Z",
  "sender": [],
  "history": [],
  "__v": 0
 }'

Delete conversations

Delete

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

Example Response

200 ok

'{
  "starred": false,
  "pinned": false,
  "autoTags": [],
  "activityTags": [],
  "emailTemplateIds": [],
  "isOpen": false,
  "tags": [],
  "waitsToBeFiltered": true,
  "timeBucket": [],
  "archived": false,
  "_id": "6102e3b08084189dcbf0e3f0",
  "users": [
  {
  "id": "58e231b14246fc73139f29e8",
  "name": "Alex",
  "isOwner": true
  }
  ],
  "date": "2021-07-29T15:29:34.330Z",
  "type": "note",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "subject": "Chat with the client",
  "description": "<p>Slack chat with the client.</p>",
  "endusers": [
  {
  "id": "610091916d643a7c418aef42",
  "name": "Lara Croft"
  }
  ],
  "snippet": "Slack chat with the client.",
  "companyName": "Leo company",
  "createDate": "2021-07-29T17:21:52.347Z",
  "sender": [],
  "history": [],
  "__v": 0
 }'

Bulk Upsert conversations

Put

To create a conversation 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]".

To update a conversation it is required to specify in the payload the _id or the externalId or sourceId.

Since this is a bulk upsert operation it's possible to create and/or update multiple conversations 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/conversations' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '[
  {
  "users": [
  {
  "id": "58e231b14246fc73139f29e8"
  }
  ],
  "date": "2021-07-29T15:29:34.330Z",
  "type": "note",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "subject": "New conversation",
  "description": "Little call with the client.",
  "endusers": [
  {
  "id": "610091916d643a7c418aef42"
  }
  ],
  "activityTags": [],
  "useSubject": true,
  "ownerId": "58e231b14246fc73139f29e8"
  }
 ]'

Example Response

200 ok

'{
  "created": 1,
  "createdErrors": [],
  "insertsKeys": [
  {
  "_id": "61672167d4ac8780f8f680af"
  }
  ],
  "updated": 0,
  "updatedErrors": [],
  "updatesKeys": [],
  "nonupdates": 0,
  "modified": [],
  "upsertedIds": [
  "61672167d4ac8780f8f680af"
  ],
  "permissionErrors": []
 }'

Bulk Upsert conversations

Put

To create a conversation 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]".

To update a conversation it is required to specify in the payload the _id or the externalId or sourceId.

Since this is a bulk upsert operation it's possible to create and/or update multiple conversations 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/conversations' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '[
  {
  "users": [
  {
  "id": "58e231b14246fc73139f29e8"
  }
  ],
  "date": "2021-07-29T15:29:34.330Z",
  "type": "note",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "subject": "New conversation",
  "description": "Little call with the client.",
  "endusers": [
  {
  "id": "610091916d643a7c418aef42"
  }
  ],
  "activityTags": [],
  "useSubject": true,
  "ownerId": "58e231b14246fc73139f29e8"
  }
 ]'

Example Response

200 ok

'{
  "created": 1,
  "createdErrors": [],
  "insertsKeys": [
  {
  "_id": "61672167d4ac8780f8f680af"
  }
  ],
  "updated": 0,
  "updatedErrors": [],
  "updatesKeys": [],
  "nonupdates": 0,
  "modified": [],
  "upsertedIds": [
  "61672167d4ac8780f8f680af"
  ],
  "permissionErrors": []
 }'

Bulk Upsert conversations

Put

To create a conversation 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]".

To update a conversation it is required to specify in the payload the _id or the externalId or sourceId.

Since this is a bulk upsert operation it's possible to create and/or update multiple conversations 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/conversations' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '[
  {
  "users": [
  {
  "id": "58e231b14246fc73139f29e8"
  }
  ],
  "date": "2021-07-29T15:29:34.330Z",
  "type": "note",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "subject": "New conversation",
  "description": "Little call with the client.",
  "endusers": [
  {
  "id": "610091916d643a7c418aef42"
  }
  ],
  "activityTags": [],
  "useSubject": true,
  "ownerId": "58e231b14246fc73139f29e8"
  }
 ]'

Example Response

200 ok

'{
  "created": 1,
  "createdErrors": [],
  "insertsKeys": [
  {
  "_id": "61672167d4ac8780f8f680af"
  }
  ],
  "updated": 0,
  "updatedErrors": [],
  "updatesKeys": [],
  "nonupdates": 0,
  "modified": [],
  "upsertedIds": [
  "61672167d4ac8780f8f680af"
  ],
  "permissionErrors": []
 }'

Developers

API /

Conversation

Conversation

Property

Required

Type

Description

Property

Required

Type

Description

Property

Required

Type

Description

Create conversation

Create conversation

Create conversation

Update conversation

Example:

Update conversation

Example:

Update conversation

Example:

Get conversations by ID

Example:

Get conversations by ID

Example:

Get conversations by ID

Example:

Get conversations List

Get conversations List

Get conversations List

Delete conversations

Delete conversations

Delete conversations

Bulk Upsert conversations

Bulk Upsert conversations

Bulk Upsert conversations