Developers
Developers
NPS
NPS records in Planhat represent the individual responses to an NPS survey. Typically these are created automatically when running an NPS campaign in Planhat, or in some cases imported from external NPS tools. A single enduser/contact can have multiple records if they responded to different surveys over time.
Based on the NPS records each enduser and company in Planhat also get an NPS score assigned.
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
cId | objectId | Related company id (planhat identifier). | |
Yes | string | Email of the contact that has been surveyed. | |
euId | objectId | Enduser id. (Autogenerated). | |
campaignId | objectId | ID of the campaign associated with the NPS. | |
score | Yes | integer | Feedback score that the user submitted in his/her survey (0-10). |
comment | string | The comment when the user gives a score in survey. | |
sourceId | string | The project id from an integration (Sales Force, Hubspot, etc). | |
dateSent | string | ISO date when the survey was sent. | |
dateAnswered | string | ISO date when the survey was answered. | |
source | string | The name of the system that NPS scores come from. For example: "custom-nps.com". | |
custom | object | Custom object with your custom properties. |
NPS records in Planhat represent the individual responses to an NPS survey. Typically these are created automatically when running an NPS campaign in Planhat, or in some cases imported from external NPS tools. A single enduser/contact can have multiple records if they responded to different surveys over time.
Based on the NPS records each enduser and company in Planhat also get an NPS score assigned.
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
cId | objectId | Related company id (planhat identifier). | |
Yes | string | Email of the contact that has been surveyed. | |
euId | objectId | Enduser id. (Autogenerated). | |
campaignId | objectId | ID of the campaign associated with the NPS. | |
score | Yes | integer | Feedback score that the user submitted in his/her survey (0-10). |
comment | string | The comment when the user gives a score in survey. | |
sourceId | string | The project id from an integration (Sales Force, Hubspot, etc). | |
dateSent | string | ISO date when the survey was sent. | |
dateAnswered | string | ISO date when the survey was answered. | |
source | string | The name of the system that NPS scores come from. For example: "custom-nps.com". | |
custom | object | Custom object with your custom properties. |
NPS records in Planhat represent the individual responses to an NPS survey. Typically these are created automatically when running an NPS campaign in Planhat, or in some cases imported from external NPS tools. A single enduser/contact can have multiple records if they responded to different surveys over time.
Based on the NPS records each enduser and company in Planhat also get an NPS score assigned.
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
cId | objectId | Related company id (planhat identifier). | |
Yes | string | Email of the contact that has been surveyed. | |
euId | objectId | Enduser id. (Autogenerated). | |
campaignId | objectId | ID of the campaign associated with the NPS. | |
score | Yes | integer | Feedback score that the user submitted in his/her survey (0-10). |
comment | string | The comment when the user gives a score in survey. | |
sourceId | string | The project id from an integration (Sales Force, Hubspot, etc). | |
dateSent | string | ISO date when the survey was sent. | |
dateAnswered | string | ISO date when the survey was answered. | |
source | string | The name of the system that NPS scores come from. For example: "custom-nps.com". | |
custom | object | Custom object with your custom properties. |
Create nps
To create an NPS it's required to define an enduser email and a score.
Example Request
curl --location -g --request POST 'https://api.planhat.com/nps' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"email": "jane@test.com",
"score": 7
}'
Example Response
'{
"_id": "61030b0e8084189dcbf0e6da",
"email": "jane@test.com",
"score": 7,
"euId": "610091916d643a7c418aef42",
"cId": "61006bc89a3e0b702ed8ea49",
"scoreType": "passive",
"dateSent": null,
"dateAnswered": "2021-07-29T20:09:50.914Z",
"__v": 0
}'Create nps
To create an NPS it's required to define an enduser email and a score.
Example Request
curl --location -g --request POST 'https://api.planhat.com/nps' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"email": "jane@test.com",
"score": 7
}'
Example Response
'{
"_id": "61030b0e8084189dcbf0e6da",
"email": "jane@test.com",
"score": 7,
"euId": "610091916d643a7c418aef42",
"cId": "61006bc89a3e0b702ed8ea49",
"scoreType": "passive",
"dateSent": null,
"dateAnswered": "2021-07-29T20:09:50.914Z",
"__v": 0
}'Create nps
To create an NPS it's required to define an enduser email and a score.
Example Request
curl --location -g --request POST 'https://api.planhat.com/nps' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"email": "jane@test.com",
"score": 7
}'
Example Response
'{
"_id": "61030b0e8084189dcbf0e6da",
"email": "jane@test.com",
"score": 7,
"euId": "610091916d643a7c418aef42",
"cId": "61006bc89a3e0b702ed8ea49",
"scoreType": "passive",
"dateSent": null,
"dateAnswered": "2021-07-29T20:09:50.914Z",
"__v": 0
}'Update nps
To update an NPS it's required to pass the NPS _id in the request URL as a parameter.
Alternately it’s possible to update using the NPS sourceId adding a prefix.
Example:
Example Request
curl --location -g --request PUT 'https://api.planhat.com/nps/61030b0e8084189dcbf0e6da' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"score": 9,
"comment": "Good product"
}'
Example Response
'{
"_id": "61030b0e8084189dcbf0e6da",
"campaignId": "60915415fc985e73734f5c02",
"email": "jane@test.com",
"score": 9,
"euId": "610091916d643a7c418aef42",
"cId": "61006bc89a3e0b702ed8ea49",
"scoreType": "promoter",
"dateSent": null,
"dateAnswered": "2021-07-29T20:09:50.914Z",
"__v": 0,
"comment": "Good product"
}'Update nps
To update an NPS it's required to pass the NPS _id in the request URL as a parameter.
Alternately it’s possible to update using the NPS sourceId adding a prefix.
Example:
Example Request
curl --location -g --request PUT 'https://api.planhat.com/nps/61030b0e8084189dcbf0e6da' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"score": 9,
"comment": "Good product"
}'
Example Response
'{
"_id": "61030b0e8084189dcbf0e6da",
"campaignId": "60915415fc985e73734f5c02",
"email": "jane@test.com",
"score": 9,
"euId": "610091916d643a7c418aef42",
"cId": "61006bc89a3e0b702ed8ea49",
"scoreType": "promoter",
"dateSent": null,
"dateAnswered": "2021-07-29T20:09:50.914Z",
"__v": 0,
"comment": "Good product"
}'Update nps
To update an NPS it's required to pass the NPS _id in the request URL as a parameter.
Alternately it’s possible to update using the NPS sourceId adding a prefix.
Example:
Example Request
curl --location -g --request PUT 'https://api.planhat.com/nps/61030b0e8084189dcbf0e6da' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"score": 9,
"comment": "Good product"
}'
Example Response
'{
"_id": "61030b0e8084189dcbf0e6da",
"campaignId": "60915415fc985e73734f5c02",
"email": "jane@test.com",
"score": 9,
"euId": "610091916d643a7c418aef42",
"cId": "61006bc89a3e0b702ed8ea49",
"scoreType": "promoter",
"dateSent": null,
"dateAnswered": "2021-07-29T20:09:50.914Z",
"__v": 0,
"comment": "Good product"
}'Get npss by ID
To get a specific NPS it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get an NPS using its sourceId adding a prefix.
Example:
Example Request
curl --location -g --request GET 'https://api.planhat.com/nps/5a2692f13a3f1f4202cf281f' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_id": "5a2692f13a3f1f4202cf281f",
"npsId": "5f3bc3efe8cd350bb6cf715a",
"email": "taco@trello.com",
"npsDate": "2020-09-14T06:20:59.367Z",
"nps": 6,
"npsComment": null,
"npsSent": null,
"scoreType": "detractor",
"cId": "598b76adc488358437484229",
"campaignId": "5c3d0c38b95614b78f100c65",
"dateSent": "2020-08-18T12:10:03.495Z",
"dateReminderSent": null,
"source": "Planhat",
"sourceId": "5f3bc3efe8cd350bb6cf715a",
"custom": null
}'Get npss by ID
To get a specific NPS it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get an NPS using its sourceId adding a prefix.
Example:
Example Request
curl --location -g --request GET 'https://api.planhat.com/nps/5a2692f13a3f1f4202cf281f' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_id": "5a2692f13a3f1f4202cf281f",
"npsId": "5f3bc3efe8cd350bb6cf715a",
"email": "taco@trello.com",
"npsDate": "2020-09-14T06:20:59.367Z",
"nps": 6,
"npsComment": null,
"npsSent": null,
"scoreType": "detractor",
"cId": "598b76adc488358437484229",
"campaignId": "5c3d0c38b95614b78f100c65",
"dateSent": "2020-08-18T12:10:03.495Z",
"dateReminderSent": null,
"source": "Planhat",
"sourceId": "5f3bc3efe8cd350bb6cf715a",
"custom": null
}'Get npss by ID
To get a specific NPS it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get an NPS using its sourceId adding a prefix.
Example:
Example Request
curl --location -g --request GET 'https://api.planhat.com/nps/5a2692f13a3f1f4202cf281f' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_id": "5a2692f13a3f1f4202cf281f",
"npsId": "5f3bc3efe8cd350bb6cf715a",
"email": "taco@trello.com",
"npsDate": "2020-09-14T06:20:59.367Z",
"nps": 6,
"npsComment": null,
"npsSent": null,
"scoreType": "detractor",
"cId": "598b76adc488358437484229",
"campaignId": "5c3d0c38b95614b78f100c65",
"dateSent": "2020-08-18T12:10:03.495Z",
"dateReminderSent": null,
"source": "Planhat",
"sourceId": "5f3bc3efe8cd350bb6cf715a",
"custom": null
}'Get npss List
When fetching multiple NPS 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. 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.
npsExpiryDay: Integer representing the number of days before the current date where the NPS was answered. The default value is 360, meaning that by default you will get NPS answered from 1 year to the current date.
Example Request
curl --location -g --request GET 'https://api.planhat.com/nps?limit=2&offset=0' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "58a161c86ffa1e5706ca4e81",
"npsId": "5f0f2312d8c9ff05273778c5",
"email": "david.lundstrom@sweco.se",
"npsDate": "2020-08-06T00:00:00.000Z",
"nps": 8,
"npsComment": "Good one",
"npsSent": null,
"scoreType": "passive",
"cId": "56bccdf554d64d837d01be55",
"campaignId": null,
"dateSent": "2020-06-06T00:00:00.000Z",
"dateReminderSent": null,
"source": null,
"sourceId": "",
"custom": null
},
{
"_id": "5a2692f13a3f1f4202cf281f",
"npsId": "5f3bc3efe8cd350bb6cf715a",
"email": "taco@trello.com",
"npsDate": "2020-09-14T06:20:59.367Z",
"nps": 6,
"npsComment": null,
"npsSent": null,
"scoreType": "detractor",
"cId": "598b76adc488358437484229",
"campaignId": "5c3d0c38b95614b78f100c65",
"dateSent": "2020-08-18T12:10:03.495Z",
"dateReminderSent": null,
"source": "Planhat",
"sourceId": "5f3bc3efe8cd350bb6cf715a",
"custom": null
}
]'Get npss List
When fetching multiple NPS 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. 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.
npsExpiryDay: Integer representing the number of days before the current date where the NPS was answered. The default value is 360, meaning that by default you will get NPS answered from 1 year to the current date.
Example Request
curl --location -g --request GET 'https://api.planhat.com/nps?limit=2&offset=0' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "58a161c86ffa1e5706ca4e81",
"npsId": "5f0f2312d8c9ff05273778c5",
"email": "david.lundstrom@sweco.se",
"npsDate": "2020-08-06T00:00:00.000Z",
"nps": 8,
"npsComment": "Good one",
"npsSent": null,
"scoreType": "passive",
"cId": "56bccdf554d64d837d01be55",
"campaignId": null,
"dateSent": "2020-06-06T00:00:00.000Z",
"dateReminderSent": null,
"source": null,
"sourceId": "",
"custom": null
},
{
"_id": "5a2692f13a3f1f4202cf281f",
"npsId": "5f3bc3efe8cd350bb6cf715a",
"email": "taco@trello.com",
"npsDate": "2020-09-14T06:20:59.367Z",
"nps": 6,
"npsComment": null,
"npsSent": null,
"scoreType": "detractor",
"cId": "598b76adc488358437484229",
"campaignId": "5c3d0c38b95614b78f100c65",
"dateSent": "2020-08-18T12:10:03.495Z",
"dateReminderSent": null,
"source": "Planhat",
"sourceId": "5f3bc3efe8cd350bb6cf715a",
"custom": null
}
]'Get npss List
When fetching multiple NPS 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. 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.
npsExpiryDay: Integer representing the number of days before the current date where the NPS was answered. The default value is 360, meaning that by default you will get NPS answered from 1 year to the current date.
Example Request
curl --location -g --request GET 'https://api.planhat.com/nps?limit=2&offset=0' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "58a161c86ffa1e5706ca4e81",
"npsId": "5f0f2312d8c9ff05273778c5",
"email": "david.lundstrom@sweco.se",
"npsDate": "2020-08-06T00:00:00.000Z",
"nps": 8,
"npsComment": "Good one",
"npsSent": null,
"scoreType": "passive",
"cId": "56bccdf554d64d837d01be55",
"campaignId": null,
"dateSent": "2020-06-06T00:00:00.000Z",
"dateReminderSent": null,
"source": null,
"sourceId": "",
"custom": null
},
{
"_id": "5a2692f13a3f1f4202cf281f",
"npsId": "5f3bc3efe8cd350bb6cf715a",
"email": "taco@trello.com",
"npsDate": "2020-09-14T06:20:59.367Z",
"nps": 6,
"npsComment": null,
"npsSent": null,
"scoreType": "detractor",
"cId": "598b76adc488358437484229",
"campaignId": "5c3d0c38b95614b78f100c65",
"dateSent": "2020-08-18T12:10:03.495Z",
"dateReminderSent": null,
"source": "Planhat",
"sourceId": "5f3bc3efe8cd350bb6cf715a",
"custom": null
}
]'Delete npss
To delete an NPS 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/nps/61030b0e8084189dcbf0e6da' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'Delete npss
To delete an NPS 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/nps/61030b0e8084189dcbf0e6da' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'Delete npss
To delete an NPS 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/nps/61030b0e8084189dcbf0e6da' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'Bulk Upsert npss
To create an NPS it's required to define an enduser email and a score.
To update an NPS it is required to specify in the payload one of the following keyables, listed in order of priority: _id, sourceId.
Since this is a bulk upsert operation it's possible to create and/or update multiple NPS 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/nps' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"email": "jane@test.com",
"score": 7
},
{
"email": "pepe@test.com",
"score": 10
}
]'
Example Response
'{
"created": 2,
"createdErrors": [],
"insertsKeys": [
{
"_id": "610313dee41b0aa81c926b69"
},
{
"_id": "610313dee41b0aa81c926b6a"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"610313dee41b0aa81c926b69",
"610313dee41b0aa81c926b6a"
],
"permissionErrors": []
}'Bulk Upsert npss
To create an NPS it's required to define an enduser email and a score.
To update an NPS it is required to specify in the payload one of the following keyables, listed in order of priority: _id, sourceId.
Since this is a bulk upsert operation it's possible to create and/or update multiple NPS 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/nps' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"email": "jane@test.com",
"score": 7
},
{
"email": "pepe@test.com",
"score": 10
}
]'
Example Response
'{
"created": 2,
"createdErrors": [],
"insertsKeys": [
{
"_id": "610313dee41b0aa81c926b69"
},
{
"_id": "610313dee41b0aa81c926b6a"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"610313dee41b0aa81c926b69",
"610313dee41b0aa81c926b6a"
],
"permissionErrors": []
}'Bulk Upsert npss
To create an NPS it's required to define an enduser email and a score.
To update an NPS it is required to specify in the payload one of the following keyables, listed in order of priority: _id, sourceId.
Since this is a bulk upsert operation it's possible to create and/or update multiple NPS 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/nps' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"email": "jane@test.com",
"score": 7
},
{
"email": "pepe@test.com",
"score": 10
}
]'
Example Response
'{
"created": 2,
"createdErrors": [],
"insertsKeys": [
{
"_id": "610313dee41b0aa81c926b69"
},
{
"_id": "610313dee41b0aa81c926b6a"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"610313dee41b0aa81c926b69",
"610313dee41b0aa81c926b6a"
],
"permissionErrors": []
}'