Planhat | The Unified Customer Platform

Developers

Enduser

An end user represents an individual at one of your customers, typically a user of your product, a business contact, or both. End users can automatically be created based on user tracking events, or based on conversations such as emails and tickets.

Often this automatic creation of contacts along with sync from an external CRM or similar is enough. But there are also situations where you may want to be 100% sure all your users exist in Planhat, and then it would make sense to create them in Planhat over API as soon as they get created in your own system.

If companyId is not present in the payload, and the email has a domain already registered within a company, then Planhat will auto-assign the new end user to the company using domain matching.

Property	Required	Type	Description
_id		objectId	Planhat identifier.
email	Yes	string	Email address of the end user/contact.
firstName		string	End user first name.
lastName		string	End user last name.
name		string	Composed string using the firstName and lastName. This gets autogenerated if the firstName and/or lastName are defined so there is no need to set it.
companyId	Yes	objectId	Related company id (planhat identifier).
companyName		string	Company name. (Autogenerated).
externalId		string	The end user id in your own system.
sourceId		string	The end user id from an integration (Sales Force, Hubspot, etc).
position		string	The role or position of this contact/user, e.g., "CFO".
phone		string	End user phone number, any string will do.
tags		array	Array of strings to tag each contact.
featured		boolean	Define if the end user is a featured contact.
primary		boolean	Gives extra weighting when assigning emails.
archived		boolean	Set the end user as archived; if the end user is archived, it won’t appear in the listing. Defaults to false.
sharedNotificationsPrefs		object	Object containing the notification preferences. (Autogenerated).
otherEmails		array	Array of extra emails.
npsUnsubscribed		boolean	Flag to show if the end user has unsubscribed to NPS.
nps		integer	The last NPS score submitted by the end user. (Autogenerated).
npsComment		string	The comment that was submitted with the NPS score. (Autogenerated).
npsDate		string	The date when the last NPS score was received for this end user. (Autogenerated).
npsSent		string	The date when the last NPS survey was sent to this end user. (Autogenerated).
beatTrend		integer	Internal system field. (Autogenerated).
beats		integer	Beats count. (Autogenerated).
beatsTotal		integer	Total count of beats. (Autogenerated).
convs14		integer	Internal system field. (Autogenerated).
convsTotal		integer	Internal system field. (Autogenerated).
experience		integer	Internal system field. (Autogenerated).
createDate		string	ISO date when end user was created. (Autogenerated).
updatedAt		string	ISO date when end user was updated. (Autogenerated).
lastActivities		array	Array of objects containing the last activities. (Autogenerated).
relatedEndusers		array	Array of objects containing the related or duplicate end users. (Autogenerated).
lastTouch		string	ISO date when end user was last contacted. (Autogenerated).
lastTouchType		string	Type of last contact. (Autogenerated).
lastTouchByType		object	Object containing the history of last contact dates by type. (Autogenerated).
custom		object	A flexible object with custom data.

If companyId is not present in the payload, and the email has a domain already registered within a company, then Planhat will auto-assign the new end user to the company using domain matching.

Property	Required	Type	Description
_id		objectId	Planhat identifier.
email	Yes	string	Email address of the end user/contact.
firstName		string	End user first name.
lastName		string	End user last name.
name		string	Composed string using the firstName and lastName. This gets autogenerated if the firstName and/or lastName are defined so there is no need to set it.
companyId	Yes	objectId	Related company id (planhat identifier).
companyName		string	Company name. (Autogenerated).
externalId		string	The end user id in your own system.
sourceId		string	The end user id from an integration (Sales Force, Hubspot, etc).
position		string	The role or position of this contact/user, e.g., "CFO".
phone		string	End user phone number, any string will do.
tags		array	Array of strings to tag each contact.
featured		boolean	Define if the end user is a featured contact.
primary		boolean	Gives extra weighting when assigning emails.
archived		boolean	Set the end user as archived; if the end user is archived, it won’t appear in the listing. Defaults to false.
sharedNotificationsPrefs		object	Object containing the notification preferences. (Autogenerated).
otherEmails		array	Array of extra emails.
npsUnsubscribed		boolean	Flag to show if the end user has unsubscribed to NPS.
nps		integer	The last NPS score submitted by the end user. (Autogenerated).
npsComment		string	The comment that was submitted with the NPS score. (Autogenerated).
npsDate		string	The date when the last NPS score was received for this end user. (Autogenerated).
npsSent		string	The date when the last NPS survey was sent to this end user. (Autogenerated).
beatTrend		integer	Internal system field. (Autogenerated).
beats		integer	Beats count. (Autogenerated).
beatsTotal		integer	Total count of beats. (Autogenerated).
convs14		integer	Internal system field. (Autogenerated).
convsTotal		integer	Internal system field. (Autogenerated).
experience		integer	Internal system field. (Autogenerated).
createDate		string	ISO date when end user was created. (Autogenerated).
updatedAt		string	ISO date when end user was updated. (Autogenerated).
lastActivities		array	Array of objects containing the last activities. (Autogenerated).
relatedEndusers		array	Array of objects containing the related or duplicate end users. (Autogenerated).
lastTouch		string	ISO date when end user was last contacted. (Autogenerated).
lastTouchType		string	Type of last contact. (Autogenerated).
lastTouchByType		object	Object containing the history of last contact dates by type. (Autogenerated).
custom		object	A flexible object with custom data.

If companyId is not present in the payload, and the email has a domain already registered within a company, then Planhat will auto-assign the new end user to the company using domain matching.

Property	Required	Type	Description
_id		objectId	Planhat identifier.
email	Yes	string	Email address of the end user/contact.
firstName		string	End user first name.
lastName		string	End user last name.
name		string	Composed string using the firstName and lastName. This gets autogenerated if the firstName and/or lastName are defined so there is no need to set it.
companyId	Yes	objectId	Related company id (planhat identifier).
companyName		string	Company name. (Autogenerated).
externalId		string	The end user id in your own system.
sourceId		string	The end user id from an integration (Sales Force, Hubspot, etc).
position		string	The role or position of this contact/user, e.g., "CFO".
phone		string	End user phone number, any string will do.
tags		array	Array of strings to tag each contact.
featured		boolean	Define if the end user is a featured contact.
primary		boolean	Gives extra weighting when assigning emails.
archived		boolean	Set the end user as archived; if the end user is archived, it won’t appear in the listing. Defaults to false.
sharedNotificationsPrefs		object	Object containing the notification preferences. (Autogenerated).
otherEmails		array	Array of extra emails.
npsUnsubscribed		boolean	Flag to show if the end user has unsubscribed to NPS.
nps		integer	The last NPS score submitted by the end user. (Autogenerated).
npsComment		string	The comment that was submitted with the NPS score. (Autogenerated).
npsDate		string	The date when the last NPS score was received for this end user. (Autogenerated).
npsSent		string	The date when the last NPS survey was sent to this end user. (Autogenerated).
beatTrend		integer	Internal system field. (Autogenerated).
beats		integer	Beats count. (Autogenerated).
beatsTotal		integer	Total count of beats. (Autogenerated).
convs14		integer	Internal system field. (Autogenerated).
convsTotal		integer	Internal system field. (Autogenerated).
experience		integer	Internal system field. (Autogenerated).
createDate		string	ISO date when end user was created. (Autogenerated).
updatedAt		string	ISO date when end user was updated. (Autogenerated).
lastActivities		array	Array of objects containing the last activities. (Autogenerated).
relatedEndusers		array	Array of objects containing the related or duplicate end users. (Autogenerated).
lastTouch		string	ISO date when end user was last contacted. (Autogenerated).
lastTouchType		string	Type of last contact. (Autogenerated).
lastTouchByType		object	Object containing the history of last contact dates by type. (Autogenerated).
custom		object	A flexible object with custom data.

Create enduser

Post

To create an end user it's required to define in the payload a companyId and an email, externalId, or sourceId.

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/endusers' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "featured": true,
  "email": "jane@test.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "companyId": "61006bc89a3e0b702ed8ea49"
 }'

Example Response

200 ok

'{
  "sharedNotificationsPrefs": {
  "enabled": [],
  "disabled": [],
  "disabledEvents": []
  },
  "otherEmails": [],
  "featured": true,
  "tags": [],
  "npsUnsubscribed": false,
  "beatTrend": 0,
  "beats": 0,
  "convs14": 0,
  "convsTotal": 0,
  "beatsTotal": 0,
  "experience": 0,
  "_id": "610091916d643a7c418aef42",
  "email": "jane@test.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "companyName": "Tenet",
  "name": "Jane Doe",
  "createDate": "2021-07-27T23:06:57.083Z",
  "lastActivities": [],
  "relatedEndusers": [],
  "updatedAt": "2021-07-27T23:06:57.086Z",
  "emailMd5": "550cf97cea5f2ce1f7f6a5b06c1c51a8",
  "__v": 0
 }'

Create enduser

Post

To create an end user it's required to define in the payload a companyId and an email, externalId, or sourceId.

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/endusers' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "featured": true,
  "email": "jane@test.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "companyId": "61006bc89a3e0b702ed8ea49"
 }'

Example Response

200 ok

'{
  "sharedNotificationsPrefs": {
  "enabled": [],
  "disabled": [],
  "disabledEvents": []
  },
  "otherEmails": [],
  "featured": true,
  "tags": [],
  "npsUnsubscribed": false,
  "beatTrend": 0,
  "beats": 0,
  "convs14": 0,
  "convsTotal": 0,
  "beatsTotal": 0,
  "experience": 0,
  "_id": "610091916d643a7c418aef42",
  "email": "jane@test.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "companyName": "Tenet",
  "name": "Jane Doe",
  "createDate": "2021-07-27T23:06:57.083Z",
  "lastActivities": [],
  "relatedEndusers": [],
  "updatedAt": "2021-07-27T23:06:57.086Z",
  "emailMd5": "550cf97cea5f2ce1f7f6a5b06c1c51a8",
  "__v": 0
 }'

Create enduser

Post

To create an end user it's required to define in the payload a companyId and an email, externalId, or sourceId.

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/endusers' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "featured": true,
  "email": "jane@test.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "companyId": "61006bc89a3e0b702ed8ea49"
 }'

Example Response

200 ok

'{
  "sharedNotificationsPrefs": {
  "enabled": [],
  "disabled": [],
  "disabledEvents": []
  },
  "otherEmails": [],
  "featured": true,
  "tags": [],
  "npsUnsubscribed": false,
  "beatTrend": 0,
  "beats": 0,
  "convs14": 0,
  "convsTotal": 0,
  "beatsTotal": 0,
  "experience": 0,
  "_id": "610091916d643a7c418aef42",
  "email": "jane@test.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "companyName": "Tenet",
  "name": "Jane Doe",
  "createDate": "2021-07-27T23:06:57.083Z",
  "lastActivities": [],
  "relatedEndusers": [],
  "updatedAt": "2021-07-27T23:06:57.086Z",
  "emailMd5": "550cf97cea5f2ce1f7f6a5b06c1c51a8",
  "__v": 0
 }'

Update enduser

Put

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

Alternately it’s possible to update using the end user 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/endusers/610091916d643a7c418aef42' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "firstName": "Lara",
  "lastName": "Croft"
 }'

Example Response

200 ok

'{
  "_id": "610091916d643a7c418aef42",
  "sharedNotificationsPrefs": {
  "enabled": [],
  "disabled": [],
  "disabledEvents": []
  },
  "otherEmails": [],
  "featured": true,
  "tags": [],
  "npsUnsubscribed": false,
  "beatTrend": 0,
  "beats": 0,
  "convs14": 0,
  "convsTotal": 0,
  "beatsTotal": 0,
  "experience": 0,
  "email": "jane@test.com",
  "firstName": "Lara",
  "lastName": "Croft",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "companyName": "Tenet",
  "name": "Lara Croft",
  "createDate": "2021-07-27T23:06:57.083Z",
  "relatedEndusers": [],
  "updatedAt": "2021-07-27T23:09:02.889Z",
  "emailMd5": "550cf97cea5f2ce1f7f6a5b06c1c51a8",
  "__v": 0
 }'

Update enduser

Put

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

Alternately it’s possible to update using the end user 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/endusers/610091916d643a7c418aef42' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "firstName": "Lara",
  "lastName": "Croft"
 }'

Example Response

200 ok

'{
  "_id": "610091916d643a7c418aef42",
  "sharedNotificationsPrefs": {
  "enabled": [],
  "disabled": [],
  "disabledEvents": []
  },
  "otherEmails": [],
  "featured": true,
  "tags": [],
  "npsUnsubscribed": false,
  "beatTrend": 0,
  "beats": 0,
  "convs14": 0,
  "convsTotal": 0,
  "beatsTotal": 0,
  "experience": 0,
  "email": "jane@test.com",
  "firstName": "Lara",
  "lastName": "Croft",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "companyName": "Tenet",
  "name": "Lara Croft",
  "createDate": "2021-07-27T23:06:57.083Z",
  "relatedEndusers": [],
  "updatedAt": "2021-07-27T23:09:02.889Z",
  "emailMd5": "550cf97cea5f2ce1f7f6a5b06c1c51a8",
  "__v": 0
 }'

Update enduser

Put

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

Alternately it’s possible to update using the end user 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/endusers/610091916d643a7c418aef42' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{
  "firstName": "Lara",
  "lastName": "Croft"
 }'

Example Response

200 ok

'{
  "_id": "610091916d643a7c418aef42",
  "sharedNotificationsPrefs": {
  "enabled": [],
  "disabled": [],
  "disabledEvents": []
  },
  "otherEmails": [],
  "featured": true,
  "tags": [],
  "npsUnsubscribed": false,
  "beatTrend": 0,
  "beats": 0,
  "convs14": 0,
  "convsTotal": 0,
  "beatsTotal": 0,
  "experience": 0,
  "email": "jane@test.com",
  "firstName": "Lara",
  "lastName": "Croft",
  "companyId": "61006bc89a3e0b702ed8ea49",
  "companyName": "Tenet",
  "name": "Lara Croft",
  "createDate": "2021-07-27T23:06:57.083Z",
  "relatedEndusers": [],
  "updatedAt": "2021-07-27T23:09:02.889Z",
  "emailMd5": "550cf97cea5f2ce1f7f6a5b06c1c51a8",
  "__v": 0
 }'

Get endusers by ID

Get

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

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

Example:

Example Request

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

Example Response

200 ok

'{
  "_id": "56bccdf554d64d837d01bf42",
  "companyId": "56bccdf554d64d837d01be4a",
  "companyName": "Google",
  "name": "Sadie Santos",
  "email": "sadie.santos_5@google.com",
  "lastActive": "2021-03-03T00:00:00.000Z",
  "beats": 0,
  "beatsTotal": 286.01014298852533,
  "beatTrend": 0,
  "experience": 49,
  "firstName": "Sadie",
  "lastName": "Santos",
  "relevanceRate": 0,
  "relevance": 86.82,
  "convsTotal": 9,
  "convs14": 1,
  "tags": [
  "Main User"
  ],
  "lastTouch": "2021-07-08T04:00:00.000Z",
  "lastTouchType": "QBR",
  "lastTouchByType": {
  "note": "2019-07-22T18:22:08.774Z",
  "Onboarding": "2019-11-11T19:14:16.902Z",
  "QBR": "2021-07-08T04:00:00.000Z"
  },
  "custom": {
  "Days in Phase": 0,
  "Logins": 0,
  "Renewal in days": -1,
  "Roles": "role2",
  "Activity Count": 0,
  "Week No": 29.285714285714285
  },
  "sourceId": "0030O00002m9M9UQAU",
  "createDate": "2016-02-11T18:07:49.000Z",
  "emailMd5": "86dcc89d519bb31ea34e4033b0919cab",
  "featured": false,
  "npsUnsubscribed": false,
  "otherEmails": [],
  "relatedEndusers": [],
  "sharedNotificationsPrefs": {
  "disabled": [],
  "disabledEvents": [],
  "enabled": []
  },
  "__v": 1,
  "updatedAt": "2021-07-12T09:49:56.192Z",
  "position": "CSM",
  "description": "",
  "npsSent": "2021-05-18T16:10:03.468Z"
 }'

Get endusers by ID

Get

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

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

Example:

Example Request

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

Example Response

200 ok

'{
  "_id": "56bccdf554d64d837d01bf42",
  "companyId": "56bccdf554d64d837d01be4a",
  "companyName": "Google",
  "name": "Sadie Santos",
  "email": "sadie.santos_5@google.com",
  "lastActive": "2021-03-03T00:00:00.000Z",
  "beats": 0,
  "beatsTotal": 286.01014298852533,
  "beatTrend": 0,
  "experience": 49,
  "firstName": "Sadie",
  "lastName": "Santos",
  "relevanceRate": 0,
  "relevance": 86.82,
  "convsTotal": 9,
  "convs14": 1,
  "tags": [
  "Main User"
  ],
  "lastTouch": "2021-07-08T04:00:00.000Z",
  "lastTouchType": "QBR",
  "lastTouchByType": {
  "note": "2019-07-22T18:22:08.774Z",
  "Onboarding": "2019-11-11T19:14:16.902Z",
  "QBR": "2021-07-08T04:00:00.000Z"
  },
  "custom": {
  "Days in Phase": 0,
  "Logins": 0,
  "Renewal in days": -1,
  "Roles": "role2",
  "Activity Count": 0,
  "Week No": 29.285714285714285
  },
  "sourceId": "0030O00002m9M9UQAU",
  "createDate": "2016-02-11T18:07:49.000Z",
  "emailMd5": "86dcc89d519bb31ea34e4033b0919cab",
  "featured": false,
  "npsUnsubscribed": false,
  "otherEmails": [],
  "relatedEndusers": [],
  "sharedNotificationsPrefs": {
  "disabled": [],
  "disabledEvents": [],
  "enabled": []
  },
  "__v": 1,
  "updatedAt": "2021-07-12T09:49:56.192Z",
  "position": "CSM",
  "description": "",
  "npsSent": "2021-05-18T16:10:03.468Z"
 }'

Get endusers by ID

Get

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

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

Example:

Example Request

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

Example Response

200 ok

'{
  "_id": "56bccdf554d64d837d01bf42",
  "companyId": "56bccdf554d64d837d01be4a",
  "companyName": "Google",
  "name": "Sadie Santos",
  "email": "sadie.santos_5@google.com",
  "lastActive": "2021-03-03T00:00:00.000Z",
  "beats": 0,
  "beatsTotal": 286.01014298852533,
  "beatTrend": 0,
  "experience": 49,
  "firstName": "Sadie",
  "lastName": "Santos",
  "relevanceRate": 0,
  "relevance": 86.82,
  "convsTotal": 9,
  "convs14": 1,
  "tags": [
  "Main User"
  ],
  "lastTouch": "2021-07-08T04:00:00.000Z",
  "lastTouchType": "QBR",
  "lastTouchByType": {
  "note": "2019-07-22T18:22:08.774Z",
  "Onboarding": "2019-11-11T19:14:16.902Z",
  "QBR": "2021-07-08T04:00:00.000Z"
  },
  "custom": {
  "Days in Phase": 0,
  "Logins": 0,
  "Renewal in days": -1,
  "Roles": "role2",
  "Activity Count": 0,
  "Week No": 29.285714285714285
  },
  "sourceId": "0030O00002m9M9UQAU",
  "createDate": "2016-02-11T18:07:49.000Z",
  "emailMd5": "86dcc89d519bb31ea34e4033b0919cab",
  "featured": false,
  "npsUnsubscribed": false,
  "otherEmails": [],
  "relatedEndusers": [],
  "sharedNotificationsPrefs": {
  "disabled": [],
  "disabledEvents": [],
  "enabled": []
  },
  "__v": 1,
  "updatedAt": "2021-07-12T09:49:56.192Z",
  "position": "CSM",
  "description": "",
  "npsSent": "2021-05-18T16:10:03.468Z"
 }'

Get endusers List

Get

When fetching multiple end users 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 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.
archived: Passing true the endpoint will include archived end users.
email: Passing a valid email the endpoint will return a list of end users with that email.
euId: Passing a valid Planhat ID (_id) the endpoint will return the end user with that id.

Example Request

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

Example Response

200 ok

'[
  {
  "_id": "56bccdf554d64d837d01bf2c",
  "companyId": "56bccdf554d64d837d01be59",
  "companyName": "t2",
  "name": "John Bakers",
  "email": "antonella.silva_1@att.com",
  "lastActive": "2021-07-27T02:50:04.000Z",
  "beats": 60,
  "beatsTotal": 2957.390884043649,
  "beatTrend": -3.2,
  "experience": 88,
  "firstName": "John",
  "lastName": "Bakers",
  "relevanceRate": 0,
  "relevance": 97.11,
  "convsTotal": 1,
  "convs14": 0,
  "tags": [
  "Main Contact",
  "mahamadou",
  "userss",
  "New Tag"
  ],
  "lastTouch": "2020-05-05T11:34:48.437Z",
  "lastTouchType": "Technical Life-lesson",
  "lastTouchByType": {
  "Technical Life-lesson": "2020-05-05T11:34:48.437Z"
  },
  "custom": {
  "UserType": "Admin",
  "Customer Role": "",
  "Days in Phase": 0,
  "Logins": 0,
  "Renewal in days": -1,
  "Roles": "role2",
  "Activity Count": 0,
  "Week No": 29.285714285714285
  },
  "sourceId": "0030O00002jbaN1QAI",
  "position": "Fireman",
  "phone": "07606356442",
  "featured": true,
  "createDate": "2016-02-11T18:07:49.000Z",
  "updatedAt": "2021-07-12T09:49:56.321Z",
  "emailMd5": "ea31df0c7a36b8c4c2fcddbe5faa6f4c",
  "npsUnsubscribed": false,
  "otherEmails": [],
  "sharedNotificationsPrefs": {
  "disabled": [],
  "disabledEvents": [],
  "enabled": []
  },
  "__v": 1,
  "companyExternalId": "ATT",
  "lastUpdated": "2020-10-07T16:38:47.014Z",
  "description": "",
  "externalId": "Anton",
  "npsSent": "2021-05-18T16:10:03.468Z"
  },
  {
  "_id": "56bccdf554d64d837d01bf42",
  "companyId": "56bccdf554d692837d01",
  "companyName": "Google",
  "name": "Sadie Santos",
  "email": "sadie.santos_5@google.com",
  "lastActive": "2021-03-03T00:00:00.000Z",
  "beats": 0,
  "beatsTotal": 286.01014298852533,
  "beatTrend": 0,
  "experience": 49,
  "firstName": "Sadie",
  "lastName": "Santos",
  "relevanceRate": 0,
  "relevance": 86.82,
  "convsTotal": 9,
  "convs14": 1,
  "tags": [
  "Main User"
  ],
  "lastTouch": "2021-07-08T04:00:00.000Z",
  "lastTouchType": "QBR",
  "lastTouchByType": {
  "note": "2019-07-22T18:22:08.774Z",
  "Onboarding": "2019-11-11T19:14:16.902Z",
  "QBR": "2021-07-08T04:00:00.000Z"
  },
  "custom": {
  "Days in Phase": 0,
  "Logins": 0,
  "Renewal in days": -1,
  "Roles": "role2",
  "Activity Count": 0,
  "Week No": 29.285714285714285
  },
  "sourceId": "0030O00002m9M9UQAU",
  "createDate": "2016-02-11T18:07:49.000Z",
  "emailMd5": "86dcc89d519bb31ea34e4033b0919cab",
  "featured": false,
  "npsUnsubscribed": false,
  "otherEmails": [],
  "relatedEndusers": [],
  "sharedNotificationsPrefs": {
  "disabled": [],
  "disabledEvents": [],
  "enabled": []
  },
  "__v": 1,
  "updatedAt": "2021-07-12T09:49:56.192Z",
  "position": "CSM",
  "description": "",
  "npsSent": "2021-05-18T16:10:03.468Z"
  }
 ]

Get endusers List

Get

When fetching multiple end users 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 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.
archived: Passing true the endpoint will include archived end users.
email: Passing a valid email the endpoint will return a list of end users with that email.
euId: Passing a valid Planhat ID (_id) the endpoint will return the end user with that id.

Example Request

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

Example Response

200 ok

'[
  {
  "_id": "56bccdf554d64d837d01bf2c",
  "companyId": "56bccdf554d64d837d01be59",
  "companyName": "t2",
  "name": "John Bakers",
  "email": "antonella.silva_1@att.com",
  "lastActive": "2021-07-27T02:50:04.000Z",
  "beats": 60,
  "beatsTotal": 2957.390884043649,
  "beatTrend": -3.2,
  "experience": 88,
  "firstName": "John",
  "lastName": "Bakers",
  "relevanceRate": 0,
  "relevance": 97.11,
  "convsTotal": 1,
  "convs14": 0,
  "tags": [
  "Main Contact",
  "mahamadou",
  "userss",
  "New Tag"
  ],
  "lastTouch": "2020-05-05T11:34:48.437Z",
  "lastTouchType": "Technical Life-lesson",
  "lastTouchByType": {
  "Technical Life-lesson": "2020-05-05T11:34:48.437Z"
  },
  "custom": {
  "UserType": "Admin",
  "Customer Role": "",
  "Days in Phase": 0,
  "Logins": 0,
  "Renewal in days": -1,
  "Roles": "role2",
  "Activity Count": 0,
  "Week No": 29.285714285714285
  },
  "sourceId": "0030O00002jbaN1QAI",
  "position": "Fireman",
  "phone": "07606356442",
  "featured": true,
  "createDate": "2016-02-11T18:07:49.000Z",
  "updatedAt": "2021-07-12T09:49:56.321Z",
  "emailMd5": "ea31df0c7a36b8c4c2fcddbe5faa6f4c",
  "npsUnsubscribed": false,
  "otherEmails": [],
  "sharedNotificationsPrefs": {
  "disabled": [],
  "disabledEvents": [],
  "enabled": []
  },
  "__v": 1,
  "companyExternalId": "ATT",
  "lastUpdated": "2020-10-07T16:38:47.014Z",
  "description": "",
  "externalId": "Anton",
  "npsSent": "2021-05-18T16:10:03.468Z"
  },
  {
  "_id": "56bccdf554d64d837d01bf42",
  "companyId": "56bccdf554d692837d01",
  "companyName": "Google",
  "name": "Sadie Santos",
  "email": "sadie.santos_5@google.com",
  "lastActive": "2021-03-03T00:00:00.000Z",
  "beats": 0,
  "beatsTotal": 286.01014298852533,
  "beatTrend": 0,
  "experience": 49,
  "firstName": "Sadie",
  "lastName": "Santos",
  "relevanceRate": 0,
  "relevance": 86.82,
  "convsTotal": 9,
  "convs14": 1,
  "tags": [
  "Main User"
  ],
  "lastTouch": "2021-07-08T04:00:00.000Z",
  "lastTouchType": "QBR",
  "lastTouchByType": {
  "note": "2019-07-22T18:22:08.774Z",
  "Onboarding": "2019-11-11T19:14:16.902Z",
  "QBR": "2021-07-08T04:00:00.000Z"
  },
  "custom": {
  "Days in Phase": 0,
  "Logins": 0,
  "Renewal in days": -1,
  "Roles": "role2",
  "Activity Count": 0,
  "Week No": 29.285714285714285
  },
  "sourceId": "0030O00002m9M9UQAU",
  "createDate": "2016-02-11T18:07:49.000Z",
  "emailMd5": "86dcc89d519bb31ea34e4033b0919cab",
  "featured": false,
  "npsUnsubscribed": false,
  "otherEmails": [],
  "relatedEndusers": [],
  "sharedNotificationsPrefs": {
  "disabled": [],
  "disabledEvents": [],
  "enabled": []
  },
  "__v": 1,
  "updatedAt": "2021-07-12T09:49:56.192Z",
  "position": "CSM",
  "description": "",
  "npsSent": "2021-05-18T16:10:03.468Z"
  }
 ]

Get endusers List

Get

When fetching multiple end users 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 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.
archived: Passing true the endpoint will include archived end users.
email: Passing a valid email the endpoint will return a list of end users with that email.
euId: Passing a valid Planhat ID (_id) the endpoint will return the end user with that id.

Example Request

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

Example Response

200 ok

'[
  {
  "_id": "56bccdf554d64d837d01bf2c",
  "companyId": "56bccdf554d64d837d01be59",
  "companyName": "t2",
  "name": "John Bakers",
  "email": "antonella.silva_1@att.com",
  "lastActive": "2021-07-27T02:50:04.000Z",
  "beats": 60,
  "beatsTotal": 2957.390884043649,
  "beatTrend": -3.2,
  "experience": 88,
  "firstName": "John",
  "lastName": "Bakers",
  "relevanceRate": 0,
  "relevance": 97.11,
  "convsTotal": 1,
  "convs14": 0,
  "tags": [
  "Main Contact",
  "mahamadou",
  "userss",
  "New Tag"
  ],
  "lastTouch": "2020-05-05T11:34:48.437Z",
  "lastTouchType": "Technical Life-lesson",
  "lastTouchByType": {
  "Technical Life-lesson": "2020-05-05T11:34:48.437Z"
  },
  "custom": {
  "UserType": "Admin",
  "Customer Role": "",
  "Days in Phase": 0,
  "Logins": 0,
  "Renewal in days": -1,
  "Roles": "role2",
  "Activity Count": 0,
  "Week No": 29.285714285714285
  },
  "sourceId": "0030O00002jbaN1QAI",
  "position": "Fireman",
  "phone": "07606356442",
  "featured": true,
  "createDate": "2016-02-11T18:07:49.000Z",
  "updatedAt": "2021-07-12T09:49:56.321Z",
  "emailMd5": "ea31df0c7a36b8c4c2fcddbe5faa6f4c",
  "npsUnsubscribed": false,
  "otherEmails": [],
  "sharedNotificationsPrefs": {
  "disabled": [],
  "disabledEvents": [],
  "enabled": []
  },
  "__v": 1,
  "companyExternalId": "ATT",
  "lastUpdated": "2020-10-07T16:38:47.014Z",
  "description": "",
  "externalId": "Anton",
  "npsSent": "2021-05-18T16:10:03.468Z"
  },
  {
  "_id": "56bccdf554d64d837d01bf42",
  "companyId": "56bccdf554d692837d01",
  "companyName": "Google",
  "name": "Sadie Santos",
  "email": "sadie.santos_5@google.com",
  "lastActive": "2021-03-03T00:00:00.000Z",
  "beats": 0,
  "beatsTotal": 286.01014298852533,
  "beatTrend": 0,
  "experience": 49,
  "firstName": "Sadie",
  "lastName": "Santos",
  "relevanceRate": 0,
  "relevance": 86.82,
  "convsTotal": 9,
  "convs14": 1,
  "tags": [
  "Main User"
  ],
  "lastTouch": "2021-07-08T04:00:00.000Z",
  "lastTouchType": "QBR",
  "lastTouchByType": {
  "note": "2019-07-22T18:22:08.774Z",
  "Onboarding": "2019-11-11T19:14:16.902Z",
  "QBR": "2021-07-08T04:00:00.000Z"
  },
  "custom": {
  "Days in Phase": 0,
  "Logins": 0,
  "Renewal in days": -1,
  "Roles": "role2",
  "Activity Count": 0,
  "Week No": 29.285714285714285
  },
  "sourceId": "0030O00002m9M9UQAU",
  "createDate": "2016-02-11T18:07:49.000Z",
  "emailMd5": "86dcc89d519bb31ea34e4033b0919cab",
  "featured": false,
  "npsUnsubscribed": false,
  "otherEmails": [],
  "relatedEndusers": [],
  "sharedNotificationsPrefs": {
  "disabled": [],
  "disabledEvents": [],
  "enabled": []
  },
  "__v": 1,
  "updatedAt": "2021-07-12T09:49:56.192Z",
  "position": "CSM",
  "description": "",
  "npsSent": "2021-05-18T16:10:03.468Z"
  }
 ]

Delete endusers

Delete

To delete an end user 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/endusers/610091916d643a7c418aef42' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

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

Delete endusers

Delete

To delete an end user 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/endusers/610091916d643a7c418aef42' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

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

Delete endusers

Delete

To delete an end user 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/endusers/610091916d643a7c418aef42' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'

Example Response

200 ok

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

Bulk Upsert endusers

Put

To create an end user it's required to define a companyId, and one of: email, externalId, sourceId.

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

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

Since this is a bulk upsert operation it's possible to create and/or update multiple end users 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/endusers' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '[
  {
  "email": "jane@test.com",
  "lastName": "Smith"
  },
  {
  "featured": true,
  "email": "will@test.com",
  "firstName": "Will",
  "lastName": "Smith",
  "companyId": "61006bc89a3e0b702ed8ea49"
  }
 ]'

Example Response

200 ok

'{
  "created": 1,
  "createdErrors": [],
  "insertsKeys": [
  {
  "_id": "610096a46d643a7c418af043",
  "email": "will@test.com"
  }
  ],
  "updated": 0,
  "updatedErrors": [
  {
  "item": {
  "email": "jane@test.com",
  "lastName": "Smith",
  "_id": "610091916d643a7c418aef42",
  "name": "Lara Smith"
  },
  "err": [
  {
  "error": "Not valid type"
  }
  ]
  }
  ],
  "updatesKeys": [],
  "nonupdates": 0,
  "modified": [],
  "upsertedIds": [
  "610096a46d643a7c418af043"
  ],
  "permissionErrors": []
 }'

Bulk Upsert endusers

Put

To create an end user it's required to define a companyId, and one of: email, externalId, sourceId.

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

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

Since this is a bulk upsert operation it's possible to create and/or update multiple end users 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/endusers' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '[
  {
  "email": "jane@test.com",
  "lastName": "Smith"
  },
  {
  "featured": true,
  "email": "will@test.com",
  "firstName": "Will",
  "lastName": "Smith",
  "companyId": "61006bc89a3e0b702ed8ea49"
  }
 ]'

Example Response

200 ok

'{
  "created": 1,
  "createdErrors": [],
  "insertsKeys": [
  {
  "_id": "610096a46d643a7c418af043",
  "email": "will@test.com"
  }
  ],
  "updated": 0,
  "updatedErrors": [
  {
  "item": {
  "email": "jane@test.com",
  "lastName": "Smith",
  "_id": "610091916d643a7c418aef42",
  "name": "Lara Smith"
  },
  "err": [
  {
  "error": "Not valid type"
  }
  ]
  }
  ],
  "updatesKeys": [],
  "nonupdates": 0,
  "modified": [],
  "upsertedIds": [
  "610096a46d643a7c418af043"
  ],
  "permissionErrors": []
 }'

Bulk Upsert endusers

Put

To create an end user it's required to define a companyId, and one of: email, externalId, sourceId.

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

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

Since this is a bulk upsert operation it's possible to create and/or update multiple end users 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/endusers' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '[
  {
  "email": "jane@test.com",
  "lastName": "Smith"
  },
  {
  "featured": true,
  "email": "will@test.com",
  "firstName": "Will",
  "lastName": "Smith",
  "companyId": "61006bc89a3e0b702ed8ea49"
  }
 ]'

Example Response

200 ok

'{
  "created": 1,
  "createdErrors": [],
  "insertsKeys": [
  {
  "_id": "610096a46d643a7c418af043",
  "email": "will@test.com"
  }
  ],
  "updated": 0,
  "updatedErrors": [
  {
  "item": {
  "email": "jane@test.com",
  "lastName": "Smith",
  "_id": "610091916d643a7c418aef42",
  "name": "Lara Smith"
  },
  "err": [
  {
  "error": "Not valid type"
  }
  ]
  }
  ],
  "updatesKeys": [],
  "nonupdates": 0,
  "modified": [],
  "upsertedIds": [
  "610096a46d643a7c418af043"
  ],
  "permissionErrors": []
 }'

Developers

API /

Enduser

Enduser

Property

Required

Type

Description

Property

Required

Type

Description

Property

Required

Type

Description

Create enduser

Create enduser

Create enduser

Update enduser

Example:

Update enduser

Example:

Update enduser

Example:

Get endusers by ID

Example:

Get endusers by ID

Example:

Get endusers by ID

Example:

Get endusers List

Get endusers List

Get endusers List

Delete endusers

Delete endusers

Delete endusers

Bulk Upsert endusers

Bulk Upsert endusers

Bulk Upsert endusers