Developers
Developers
Campaign
Manage campaigns you are running inside companies, e.g., to drive adoption or to deepen stakeholder relations.
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
name | Yes | string | Campaign name. |
campaignPurpose | string | Campaign purpose. | |
companyId | Yes | objectId | Related company id (planhat identifier). |
companyName | string | Company name. (Autogenerated). | |
externalId | string | The campaign id in your own system. | |
sourceId | string | The campaign id from an integration (Sales Force, Hubspot, etc). | |
custom | object | Custom object with your custom properties. |
Manage campaigns you are running inside companies, e.g., to drive adoption or to deepen stakeholder relations.
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
name | Yes | string | Campaign name. |
campaignPurpose | string | Campaign purpose. | |
companyId | Yes | objectId | Related company id (planhat identifier). |
companyName | string | Company name. (Autogenerated). | |
externalId | string | The campaign id in your own system. | |
sourceId | string | The campaign id from an integration (Sales Force, Hubspot, etc). | |
custom | object | Custom object with your custom properties. |
Manage campaigns you are running inside companies, e.g., to drive adoption or to deepen stakeholder relations.
Property | Required | Type | Description |
|---|---|---|---|
_id | objectId | Planhat identifier. | |
name | Yes | string | Campaign name. |
campaignPurpose | string | Campaign purpose. | |
companyId | Yes | objectId | Related company id (planhat identifier). |
companyName | string | Company name. (Autogenerated). | |
externalId | string | The campaign id in your own system. | |
sourceId | string | The campaign id from an integration (Sales Force, Hubspot, etc). | |
custom | object | Custom object with your custom properties. |
Create campaign
To create a campaign it’s required to define a name and a valid companyId.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
Example Request
curl --location -g --request POST 'https://api.planhat.com/campaigns' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Campaign name",
"campaignPurpose": "Campaign purpose",
"companyId": "60df26bfa259250cba9cf816",
"externalId": 1234,
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
}
}'
Example Response
'{
"_id": "60faeda853b8f717ebe36146",
"name": "Campaign name",
"campaignPurpose": "Campaign purpose",
"companyId": "60df26bfa259250cba9cf816",
"externalId": "1234",
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
},
"companyName": "Test Company"
}'Create campaign
To create a campaign it’s required to define a name and a valid companyId.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
Example Request
curl --location -g --request POST 'https://api.planhat.com/campaigns' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Campaign name",
"campaignPurpose": "Campaign purpose",
"companyId": "60df26bfa259250cba9cf816",
"externalId": 1234,
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
}
}'
Example Response
'{
"_id": "60faeda853b8f717ebe36146",
"name": "Campaign name",
"campaignPurpose": "Campaign purpose",
"companyId": "60df26bfa259250cba9cf816",
"externalId": "1234",
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
},
"companyName": "Test Company"
}'Create campaign
To create a campaign it’s required to define a name and a valid companyId.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
Example Request
curl --location -g --request POST 'https://api.planhat.com/campaigns' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Campaign name",
"campaignPurpose": "Campaign purpose",
"companyId": "60df26bfa259250cba9cf816",
"externalId": 1234,
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
}
}'
Example Response
'{
"_id": "60faeda853b8f717ebe36146",
"name": "Campaign name",
"campaignPurpose": "Campaign purpose",
"companyId": "60df26bfa259250cba9cf816",
"externalId": "1234",
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
},
"companyName": "Test Company"
}'Update campaign
To update a campaign it’s required to pass the _id in the request URL as a parameter.
Alternately it’s possible to update using the campaign externalId or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request PUT 'https://api.planhat.com/campaigns/60faeda853b8f717ebe36146' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Campaign name 2"
}'
Example Response
'{
"_id": "60ff061d681a6b4da9248694",
"name": "Campaign name 2",
"campaignPurpose": "Campaign purpose 2",
"companyId": "60df26bfa259250cba9cf816",
"externalId": "12323",
"companyName": "Test Company",
"__v": 0,
"sourceId": "12323"
}'Update campaign
To update a campaign it’s required to pass the _id in the request URL as a parameter.
Alternately it’s possible to update using the campaign externalId or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request PUT 'https://api.planhat.com/campaigns/60faeda853b8f717ebe36146' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Campaign name 2"
}'
Example Response
'{
"_id": "60ff061d681a6b4da9248694",
"name": "Campaign name 2",
"campaignPurpose": "Campaign purpose 2",
"companyId": "60df26bfa259250cba9cf816",
"externalId": "12323",
"companyName": "Test Company",
"__v": 0,
"sourceId": "12323"
}'Update campaign
To update a campaign it’s required to pass the _id in the request URL as a parameter.
Alternately it’s possible to update using the campaign externalId or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request PUT 'https://api.planhat.com/campaigns/60faeda853b8f717ebe36146' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"name": "Campaign name 2"
}'
Example Response
'{
"_id": "60ff061d681a6b4da9248694",
"name": "Campaign name 2",
"campaignPurpose": "Campaign purpose 2",
"companyId": "60df26bfa259250cba9cf816",
"externalId": "12323",
"companyName": "Test Company",
"__v": 0,
"sourceId": "12323"
}'Get campaigns by ID
To get a specific campaign it’s required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get a campaign using its externalId or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request GET 'https://api.planhat.com/campaigns/5ffcce42ad67267f66741147' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_id": "5ffcce42ad67267f66741147",
"companyId": "56bccdf554d64d837d01be9d",
"companyName": "Tenet",
"name": "Gold campaign",
"campaignPurpose": "Campaign purpose",
"__v": 0,
"custom": {
"Comments": "",
"Main Product": [
"Recipe Database"
],
"Days in Phase": 0,
"NRR30": 0,
"t123": "undefined",
"Logins": 0,
"Overall Outlet Health": 4,
"Kary FF": null
},
"externalId": "4467",
"usage": {
"6053b728fa96fa0262729a3d": 0,
"6053ba62ca3eaf023a54d268": 0
}
}'Get campaigns by ID
To get a specific campaign it’s required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get a campaign using its externalId or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request GET 'https://api.planhat.com/campaigns/5ffcce42ad67267f66741147' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_id": "5ffcce42ad67267f66741147",
"companyId": "56bccdf554d64d837d01be9d",
"companyName": "Tenet",
"name": "Gold campaign",
"campaignPurpose": "Campaign purpose",
"__v": 0,
"custom": {
"Comments": "",
"Main Product": [
"Recipe Database"
],
"Days in Phase": 0,
"NRR30": 0,
"t123": "undefined",
"Logins": 0,
"Overall Outlet Health": 4,
"Kary FF": null
},
"externalId": "4467",
"usage": {
"6053b728fa96fa0262729a3d": 0,
"6053ba62ca3eaf023a54d268": 0
}
}'Get campaigns by ID
To get a specific campaign it’s required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get a campaign using its externalId or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request GET 'https://api.planhat.com/campaigns/5ffcce42ad67267f66741147' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"_id": "5ffcce42ad67267f66741147",
"companyId": "56bccdf554d64d837d01be9d",
"companyName": "Tenet",
"name": "Gold campaign",
"campaignPurpose": "Campaign purpose",
"__v": 0,
"custom": {
"Comments": "",
"Main Product": [
"Recipe Database"
],
"Days in Phase": 0,
"NRR30": 0,
"t123": "undefined",
"Logins": 0,
"Overall Outlet Health": 4,
"Kary FF": null
},
"externalId": "4467",
"usage": {
"6053b728fa96fa0262729a3d": 0,
"6053ba62ca3eaf023a54d268": 0
}
}'Get campaigns List
When fetching multiple campaigns there are some options that can be used via query params:
companyId: Filter using company id.
limit: Limit the list length. Default is 100, max. 2000.
offset: Start the list on a specific integer index.
sort: Sort based on a specific property. Prefix the property "-" to change the sort order.
select: Select specific properties. Multiple properties can be specified separating them by commas.
Example Request
curl --location -g --request GET 'https://api.planhat.com/campaigns?limit=2&offset=0&sort=-name&select=_id,name,campaignPurpose,companyId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "60fb0869694ea374023924cb",
"companyId": "56bccdf554d64d837d01be4a",
"name": "ZPA Product",
"campaignPurpose": "Campaign purpose"
},
{
"_id": "601c0a253e5ed41388982528",
"companyId": "6011889f52181c5640bf41ba",
"name": "Trello.io",
"campaignPurpose": "Campaign purpose 2"
}
]
Get campaigns List
When fetching multiple campaigns there are some options that can be used via query params:
companyId: Filter using company id.
limit: Limit the list length. Default is 100, max. 2000.
offset: Start the list on a specific integer index.
sort: Sort based on a specific property. Prefix the property "-" to change the sort order.
select: Select specific properties. Multiple properties can be specified separating them by commas.
Example Request
curl --location -g --request GET 'https://api.planhat.com/campaigns?limit=2&offset=0&sort=-name&select=_id,name,campaignPurpose,companyId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "60fb0869694ea374023924cb",
"companyId": "56bccdf554d64d837d01be4a",
"name": "ZPA Product",
"campaignPurpose": "Campaign purpose"
},
{
"_id": "601c0a253e5ed41388982528",
"companyId": "6011889f52181c5640bf41ba",
"name": "Trello.io",
"campaignPurpose": "Campaign purpose 2"
}
]
Get campaigns List
When fetching multiple campaigns there are some options that can be used via query params:
companyId: Filter using company id.
limit: Limit the list length. Default is 100, max. 2000.
offset: Start the list on a specific integer index.
sort: Sort based on a specific property. Prefix the property "-" to change the sort order.
select: Select specific properties. Multiple properties can be specified separating them by commas.
Example Request
curl --location -g --request GET 'https://api.planhat.com/campaigns?limit=2&offset=0&sort=-name&select=_id,name,campaignPurpose,companyId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'[
{
"_id": "60fb0869694ea374023924cb",
"companyId": "56bccdf554d64d837d01be4a",
"name": "ZPA Product",
"campaignPurpose": "Campaign purpose"
},
{
"_id": "601c0a253e5ed41388982528",
"companyId": "6011889f52181c5640bf41ba",
"name": "Trello.io",
"campaignPurpose": "Campaign purpose 2"
}
]
Delete campaigns
To delete a campaign 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/campaigns/60faeda853b8f717ebe36146' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'Delete campaigns
To delete a campaign 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/campaigns/60faeda853b8f717ebe36146' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'Delete campaigns
To delete a campaign 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/campaigns/60faeda853b8f717ebe36146' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
'{
"n": 1,
"ok": 1,
"deletedCount": 1
}'Bulk Upsert campaigns
To create a campaign it’s required to define a name and a valid companyId.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
To update a campaign it is required to specify in the payload one of the following keyables, listed in order of priority: _id, sourceId, externalId.
Since this is a bulk upsert operation it’s possible to create and/or update multiple campaigns 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/campaigns' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"name": "Campaign name",
"campaignPurpose": "Campaign purpose",
"companyId": "60df26bfa259250cba9cf816",
"externalId": 1234,
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
}
},
{
"name": "Campaign name 2",
"campaignPurpose": "Campaign purpose 2",
"companyId": "60df26bfa259250cba9cf816",
"externalId": 1235,
"sourceId": "sfc-1235",
"custom": {
"field": "custom field"
}
}
]'
Example Response
'{
"created": 2,
"createdErrors": [],
"insertsKeys": [
{
"_id": "60fde9ad57df5b411cf39be5",
"sourceId": "sfc-1234",
"externalId": "1234"
},
{
"_id": "60fde9ad57df5b411cf39be6",
"sourceId": "sfc-1235",
"externalId": "1235"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"60fde9ad57df5b411cf39be5",
"60fde9ad57df5b411cf39be6"
],
"permissionErrors": []
}'Bulk Upsert campaigns
To create a campaign it’s required to define a name and a valid companyId.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
To update a campaign it is required to specify in the payload one of the following keyables, listed in order of priority: _id, sourceId, externalId.
Since this is a bulk upsert operation it’s possible to create and/or update multiple campaigns 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/campaigns' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"name": "Campaign name",
"campaignPurpose": "Campaign purpose",
"companyId": "60df26bfa259250cba9cf816",
"externalId": 1234,
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
}
},
{
"name": "Campaign name 2",
"campaignPurpose": "Campaign purpose 2",
"companyId": "60df26bfa259250cba9cf816",
"externalId": 1235,
"sourceId": "sfc-1235",
"custom": {
"field": "custom field"
}
}
]'
Example Response
'{
"created": 2,
"createdErrors": [],
"insertsKeys": [
{
"_id": "60fde9ad57df5b411cf39be5",
"sourceId": "sfc-1234",
"externalId": "1234"
},
{
"_id": "60fde9ad57df5b411cf39be6",
"sourceId": "sfc-1235",
"externalId": "1235"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"60fde9ad57df5b411cf39be5",
"60fde9ad57df5b411cf39be6"
],
"permissionErrors": []
}'Bulk Upsert campaigns
To create a campaign it’s required to define a name and a valid companyId.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
To update a campaign it is required to specify in the payload one of the following keyables, listed in order of priority: _id, sourceId, externalId.
Since this is a bulk upsert operation it’s possible to create and/or update multiple campaigns 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/campaigns' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"name": "Campaign name",
"campaignPurpose": "Campaign purpose",
"companyId": "60df26bfa259250cba9cf816",
"externalId": 1234,
"sourceId": "sfc-1234",
"custom": {
"field": "custom field"
}
},
{
"name": "Campaign name 2",
"campaignPurpose": "Campaign purpose 2",
"companyId": "60df26bfa259250cba9cf816",
"externalId": 1235,
"sourceId": "sfc-1235",
"custom": {
"field": "custom field"
}
}
]'
Example Response
'{
"created": 2,
"createdErrors": [],
"insertsKeys": [
{
"_id": "60fde9ad57df5b411cf39be5",
"sourceId": "sfc-1234",
"externalId": "1234"
},
{
"_id": "60fde9ad57df5b411cf39be6",
"sourceId": "sfc-1235",
"externalId": "1235"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"60fde9ad57df5b411cf39be5",
"60fde9ad57df5b411cf39be6"
],
"permissionErrors": []
}'