Planhat
App · 25 actions
Work with your Planhat customer data: companies, end users, notes, tasks, licenses, issues, churn, opportunities and other records, send user activity and metrics, and start workflows when records are added or change.
Actions
| Action | What it does |
|---|---|
| Add note | Log a note on a company's timeline, optionally naming the end users it involved. |
| Bulk upsert companies | Create or update up to 5,000 companies at once. |
| Create company | Add a company (a customer or prospect) to Planhat. |
| Create end user | Add a contact (end user) to a company. |
| Create issue | Log an issue (a bug or feature request) and link it to the companies and end users it affects. |
| Create license | Add a license (a subscription the company pays for) with its product, dates and value. |
| Create opportunity | Add a sales opportunity (an upsell or renewal) to a company. |
| Create task | Create a task (a to-do) for a company, with a due time and an owner. |
| Delete company | Delete a company from Planhat. |
| Delete end user | Delete an end user from Planhat. |
| Delete record | Delete one license, task, note, NPS response or other record by its id. |
| Get company | Get one company with its owner, status, phase, health score, revenue, renewal date and custom fields. |
| Get end user | Get one end user (a contact at a customer) with their company, position, activity and custom fields. |
| Get metric values | Read the values a custom metric has had, for one company or all, between two dates. |
| Get record | Get one license, task, NPS response, invoice or other record by its id. |
| List companies | List your Planhat companies (customer accounts) with their status, phase, health and revenue. |
| List end users | List the contacts (end users) at your customers, for one company or all, or find one by email. |
| List records | List licenses, tasks, NPS responses, invoices, issues, churn records, opportunities, projects or another kind of record, for one company or all. |
| List team members | List the people on your Planhat team (CSMs, managers and admins) with their names and emails, for use as owners. |
| Record churn | Record that a company churned, when, why and how much revenue was lost. |
| Send metric | Send one value of a custom metric (dimension data), such as active users, for a company, end user, asset or project, to use in health scores. |
| Track user activity | Record that an end user did something in your product, such as Logged in or Sent invoice, so it counts towards their activity and health in Planhat. |
| Update company | Change a company's name, status, phase, owner or other fields. |
| Update end user | Change an end user's name, email, position or other fields. |
| Update task | Change a task's title, time, owner or status, mark it done, or archive it. |
Add note
Log a note on a company's timeline, optionally naming the end users it involved. Give a touch type to log a call, meeting or other kind of conversation instead.
Inputs
- Company
company_idtextRequired - The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.
- Note
descriptiontextRequired - What happened, in a few sentences.
- Subject
subjecttext - A title for the note.
- When
occurred_atdate and time - When it happened. Defaults to now.
- Touch type
touch_typetext - The name of one of your touch types in Planhat, such as Call. Leave empty for a note.
- End user IDs
enduser_idslist - The Planhat ids of the end users it involved.
- External ID
external_idtext - The record's id in your own system.
- Custom fields
customobject - Values for the note's custom fields, each by the field's name in Planhat, such as {"Segment": "Enterprise"}.
Outputs
noteobject- The note
Example output
{
"note": {
"_id": "6102e3b08084189dcbf0e3f0",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"createDate": "2021-07-29T17:21:52.347Z",
"custom": {},
"date": "2021-07-29T15:29:34.330Z",
"description": "Walked through adoption with the team.",
"endusers": [
{
"id": "610091916d643a7c418aef42",
"name": "Jane Doe"
}
],
"externalId": "",
"snippet": "Walked through adoption with the team.",
"subject": "Quarterly review",
"type": "note",
"users": [
{
"id": "58e231b14246fc73139f29e8",
"isOwner": true,
"name": "Alex"
}
]
}
}Bulk upsert companies
Create or update up to 5,000 companies at once. Each one with an _id, sourceId or externalId that matches is updated; the rest are created and need a name.
Inputs
- Companies
companieslistRequired - A list of companies, each with Planhat's field names, such as [{"externalId": "acme-1", "name": "Acme", "phase": "Onboarding"}].
Outputs
creatednumber- How many were created
createdErrorslist- Why each failed create failed
insertsKeyslist- The keys of the new companies
modifiedlist- The ids of the updated companies
nonupdatesnumber- How many matched but had nothing to change
permissionErrorslist- Changes the token wasn't allowed
updatednumber- How many were updated
updatedErrorslist- Why each failed update failed
updatesKeyslist- The keys of the updated companies
upsertedIdslist- The ids of the new companies
Example output
{
"created": 1,
"createdErrors": [],
"insertsKeys": [
{
"_id": "6100512d9a3e0b702ed8e9c8",
"externalId": "",
"sourceId": "sfc-1235"
}
],
"modified": [
"6011889f52181c5640bf41bb"
],
"nonupdates": 0,
"permissionErrors": [],
"updated": 1,
"updatedErrors": [],
"updatesKeys": [
{
"_id": "6011889f52181c5640bf41bb",
"externalId": "1234",
"sourceId": "0012000001U28SYAAZ"
}
],
"upsertedIds": [
"6100512d9a3e0b702ed8e9c8"
]
}Create company
Add a company (a customer or prospect) to Planhat.
Inputs
- Name
nametextRequired - The company's name.
- Status
statustext - Where the company is as a customer.One of:
prospect,coming(Coming (signed, not yet live)),customer,canceled,lost. - Lifecycle phase
phasetext - The name of one of your lifecycle phases in Planhat, such as Onboarding.
- Owner
owner_idtext - The team member who owns the company (its CSM or account manager).
- External ID
external_idtext - The company's id in your own system.
- Domains
domainslist - The company's web domains, such as acme.com.
- Description
descriptiontext - A description of the company.
- Website
webtext - The company's website address.
- Country
countrytext - The company's country.
- City
citytext - The company's city.
- Tags
tagslist - Tags for the company.
- Custom fields
customobject - Values for the company's custom fields, each by the field's name in Planhat, such as {"Segment": "Enterprise"}.
Outputs
companyobject- The company
Example output
{
"company": {
"_id": "61006bc89a3e0b702ed8ea49",
"arr": 15000,
"city": "Riga",
"coOwner": "",
"country": "Latvia",
"createDate": "2021-07-27T20:25:44.430Z",
"csmScore": 4,
"custom": {
"Days in Phase": 0
},
"customerFrom": "2021-07-27T00:00:00.000Z",
"customerTo": "2022-07-27T00:00:00.000Z",
"description": "Up and coming tech company",
"domains": [
"tenet.com"
],
"externalId": "tenet-123",
"h": 3,
"lastActive": "2021-08-10T12:00:00.000Z",
"lastUpdated": "2021-08-11T16:12:41.657Z",
"mr": 15000,
"mrr": 1250,
"name": "Tenet",
"nrr30": 0,
"owner": "60ccb1c5965cc9e0f3848075",
"phase": "Onboarding",
"renewalDate": "2022-07-27T00:00:00.000Z",
"renewalDaysFromNow": 363,
"sourceId": "119",
"status": "customer",
"tags": [
"enterprise"
],
"updatedAt": "2021-08-09T16:54:17.298Z",
"web": "https://tenet.com"
}
}Create end user
Add a contact (end user) to a company. Give their email, or their id in your own system.
Inputs
- Company
company_idtextRequired - The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.
- Email
emailtext - Their email address. Needed unless you give an External ID.
- First name
first_nametext - Their first name.
- Last name
last_nametext - Their last name.
- Position
positiontext - Their role, such as CFO.
- Phone
phonetext - Their phone number.
- External ID
external_idtext - Their id in your own system.
- Tags
tagslist - Tags for the end user.
- Featured contact
featuredtrue/false - Mark them as one of the company's featured contacts.
- Custom fields
customobject - Values for the end user's custom fields, each by the field's name in Planhat, such as {"Segment": "Enterprise"}.
Outputs
enduserobject- The end user
Example output
{
"enduser": {
"_id": "610091916d643a7c418aef42",
"archived": false,
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"createDate": "2021-07-27T23:06:57.083Z",
"custom": {},
"email": "jane@example.com",
"externalId": "jane-1",
"featured": true,
"firstName": "Jane",
"lastActive": "2021-08-10T12:00:00.000Z",
"lastName": "Doe",
"name": "Jane Doe",
"phone": "+1 555 0100",
"position": "CFO",
"sourceId": "",
"tags": [],
"updatedAt": "2021-07-27T23:06:57.086Z"
}
}Create issue
Log an issue (a bug or feature request) and link it to the companies and end users it affects.
Inputs
- Title
titletextRequired - A short title for the issue.
- Description
descriptiontext - What the issue is.
- Companies
company_idslist - The companies it affects.
- End user IDs
enduser_idslist - The Planhat ids of the end users it affects.
- Status
statustext - Its status, such as Open.
- Priority
prioritytext - Its priority, such as High.
- Link
source_urltext - A link to the issue in another tool, such as Jira.
- Custom fields
customobject - Values for the issue's custom fields, each by the field's name in Planhat, such as {"Segment": "Enterprise"}.
Outputs
issueobject- The issue
Example output
{
"issue": {
"_id": "610411d5b046afb2109df12c",
"archived": false,
"companies": [
{
"id": "61006bc89a3e0b702ed8ea49",
"name": "Tenet"
}
],
"companyIds": [
"61006bc89a3e0b702ed8ea49"
],
"createdAt": "2021-07-30T14:51:01.691Z",
"custom": {},
"description": "Some users can't sync.",
"enduserIds": [
"610091916d643a7c418aef42"
],
"priority": "High",
"status": "Open",
"title": "Problem with integration",
"updatedAt": "2021-07-30T14:51:01.691Z"
}
}Create license
Add a license (a subscription the company pays for) with its product, dates and value. Planhat works out the company's revenue from it.
Inputs
- Company
company_idtextRequired - The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.
- Starts on
from_datedateRequired - The first day of the license.
- Ends on
to_datedate - The last day, for a license with a fixed term.
- Total value
valuenumber - The value for the whole period. Give this or the monthly value.At least 0.
- Monthly value
mrrnumber - The monthly value, for an ongoing license.At least 0.
- Product
producttext - The product the license is for, such as Subscription.
- Currency
currencytext - The three-letter currency code, such as EUR. Defaults to USD.
- Fixed term
fixed_periodtrue/false - On for a license with an end date; off for an ongoing one.
- Renews automatically
auto_renewstrue/false - Let Planhat renew it once its notice period passes.
- Renewal status
renewal_statustext - Whether it is ongoing, renewed or lost.One of:
ongoing,renewed,lost. - External ID
external_idtext - The record's id in your own system.
- Custom fields
customobject - Values for the license's custom fields, each by the field's name in Planhat, such as {"Segment": "Enterprise"}.
Outputs
licenseobject- The license
Example output
{
"license": {
"_currency": "USD",
"_id": "61006fbf1df7fa77a20d9d0a",
"autoRenews": false,
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"custom": {},
"externalId": "",
"fixedPeriod": true,
"fromDate": "2021-07-27T00:00:00.000Z",
"length": 12,
"mrr": 83.33,
"product": "Large License",
"renewalDate": "2022-07-27T00:00:00.000Z",
"renewalStatus": "ongoing",
"toDate": "2022-07-27T00:00:00.000Z",
"value": 1000
}
}Create opportunity
Add a sales opportunity (an upsell or renewal) to a company.
Inputs
- Company
company_idtextRequired - The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.
- Title
titletextRequired - A name for the opportunity.
- Status
statustext - Whether it is open, won or lost. Defaults to active.One of:
active,won,lost. - Sales stage
sales_stagetext - Its stage, such as Pitched.
- Owner
owner_idtext - The team member who owns it.
- Monthly value
mrrnumber - The monthly recurring value.At least 0.
- One-off value
nrrnumber - The value that doesn't recur.At least 0.
- Currency
currencytext - The three-letter currency code, such as USD.
- Deal date
deal_datedate - When the deal starts.
- Close date
close_datedate - When it is expected to close.
- External ID
external_idtext - The record's id in your own system.
- Custom fields
customobject - Values for the opportunity's custom fields, each by the field's name in Planhat, such as {"Segment": "Enterprise"}.
Outputs
opportunityobject- The opportunity
Example output
{
"opportunity": {
"_currency": "USD",
"_id": "6101e99b72c0e0884d5e9139",
"closeDate": "2021-09-30T00:00:00.000Z",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"custom": {},
"dealDate": "2021-08-03T00:00:00.000Z",
"externalId": "",
"landingDate": "2021-07-28T23:34:51.636Z",
"mrr": 250,
"nrr": 500,
"ownerId": "60ccb1c5965cc9e0f3848075",
"salesStage": "Pitched",
"status": "active",
"title": "Seat expansion"
}
}Create task
Create a task (a to-do) for a company, with a due time and an owner.
Inputs
- Company
company_idtextRequired - The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.
- Title
titletextRequired - What needs doing, such as Send renewal quote.
- Description
descriptiontext - What the task is about.
- Starts
start_timedate and time - When the task starts or is due.
- Ends
end_timedate and time - When the task ends, for one with a set time.
- Owner
owner_idtext - The team member the task is for.
- Repeats
repeattext - How often the task comes back.One of:
daily(Every day),weekly(Every week),monthly(Every month),quarterly(Every quarter),yearly(Every year). - Status
statustext - The name of one of your task statuses in Planhat, such as In-progress.
- Custom fields
customobject - Values for the task's custom fields, each by the field's name in Planhat, such as {"Segment": "Enterprise"}.
Outputs
taskobject- The task
Example output
{
"task": {
"_id": "6102c9748084189dcbf0df60",
"action": "Send renewal quote",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"createdAt": "2022-07-05T09:51:52.818Z",
"custom": {},
"dateDone": "",
"description": "<p>Call the client.</p>",
"endTime": "2021-07-29T01:00:00.000Z",
"isArchived": false,
"mainType": "task",
"ownerId": "58e231b14246fc73139f29e8",
"ownerName": "Alex",
"repeat": "",
"startTime": "2021-07-29T00:00:00.000Z",
"status": "In-progress",
"updatedAt": "2022-07-05T09:51:52.818Z"
}
}Delete company
Delete a company from Planhat. This can't be undone.
Inputs
- Company
company_idtextRequired - The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.
Outputs
deletedtrue/false- True once Planhat deleted it
deleted_countnumber- How many Planhat deleted
record_idtext- The id that was deleted
Example output
{
"deleted": true,
"deleted_count": 1,
"record_id": "61006bc89a3e0b702ed8ea49"
}Delete end user
Delete an end user from Planhat. This can't be undone.
Inputs
- End user ID
enduser_idtextRequired - The end user's Planhat id, from 'List end users' or an earlier step, or extid- followed by their id in your own system.
Outputs
deletedtrue/false- True once Planhat deleted it
deleted_countnumber- How many Planhat deleted
record_idtext- The id that was deleted
Example output
{
"deleted": true,
"deleted_count": 1,
"record_id": "610091916d643a7c418aef42"
}Delete record
Delete one license, task, note, NPS response or other record by its id. This can't be undone.
Inputs
- Record type
record_typetextRequired - Which kind of Planhat record.One of:
licenses,conversations(Conversations and notes),tasks,issues,churn(Churn records),nps(NPS responses),invoices,opportunities,projects,sales, and 3 more. - Record ID
record_idtextRequired - The record's Planhat id, from 'List records' or an earlier step, or extid- followed by its id in your own system.
Outputs
deletedtrue/false- True once Planhat deleted it
deleted_countnumber- How many Planhat deleted
record_idtext- The id that was deleted
record_typetext- The kind of record
Example output
{
"deleted": true,
"deleted_count": 1,
"record_id": "61006fbf1df7fa77a20d9d0a",
"record_type": "licenses"
}Get company
Get one company with its owner, status, phase, health score, revenue, renewal date and custom fields.
Inputs
- Company
company_idtextRequired - The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.
Outputs
companyobject- The company
Example output
{
"company": {
"_id": "61006bc89a3e0b702ed8ea49",
"arr": 15000,
"city": "Riga",
"coOwner": "",
"country": "Latvia",
"createDate": "2021-07-27T20:25:44.430Z",
"csmScore": 4,
"custom": {
"Days in Phase": 0
},
"customerFrom": "2021-07-27T00:00:00.000Z",
"customerTo": "2022-07-27T00:00:00.000Z",
"description": "Up and coming tech company",
"domains": [
"tenet.com"
],
"externalId": "tenet-123",
"h": 3,
"lastActive": "2021-08-10T12:00:00.000Z",
"lastUpdated": "2021-08-11T16:12:41.657Z",
"mr": 15000,
"mrr": 1250,
"name": "Tenet",
"nrr30": 0,
"owner": "60ccb1c5965cc9e0f3848075",
"phase": "Onboarding",
"renewalDate": "2022-07-27T00:00:00.000Z",
"renewalDaysFromNow": 363,
"sourceId": "119",
"status": "customer",
"tags": [
"enterprise"
],
"updatedAt": "2021-08-09T16:54:17.298Z",
"web": "https://tenet.com"
}
}Get end user
Get one end user (a contact at a customer) with their company, position, activity and custom fields.
Inputs
- End user ID
enduser_idtextRequired - The end user's Planhat id, from 'List end users' or an earlier step, or extid- followed by their id in your own system.
Outputs
enduserobject- The end user
Example output
{
"enduser": {
"_id": "610091916d643a7c418aef42",
"archived": false,
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"createDate": "2021-07-27T23:06:57.083Z",
"custom": {},
"email": "jane@example.com",
"externalId": "jane-1",
"featured": true,
"firstName": "Jane",
"lastActive": "2021-08-10T12:00:00.000Z",
"lastName": "Doe",
"name": "Jane Doe",
"phone": "+1 555 0100",
"position": "CFO",
"sourceId": "",
"tags": [],
"updatedAt": "2021-07-27T23:06:57.086Z"
}
}Get metric values
Read the values a custom metric has had, for one company or all, between two dates.
Inputs
- Company
company_idtext - Only this company's values. Pick one, or give its Planhat id.
- Metric ID
dimension_idtext - The metric's id, such as activeusers.
- From
from_datedate - The first day to include.
- To
to_datedate - The last day to include.
- How many
limitnumber - How many to return, 1 to 2,000. Planhat decides when left empty.From 1 to 2000.
- Skip
offsetnumber - How many to skip from the start, to get the next page (for 100 a page, 100 gets the second).At least 0.
Outputs
countnumber- How many came back
valueslist- The metric's values
Example output
{
"count": 1,
"values": [
{
"_id": "611ef080ff18a32f886e40ae",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"dimensionId": "activeusers",
"model": "Company",
"parentId": "61006bc89a3e0b702ed8ea49",
"time": "2021-08-20T00:00:00.000Z",
"value": 5
}
]
}Get record
Get one license, task, NPS response, invoice or other record by its id.
Inputs
- Record type
record_typetextRequired - Which kind of Planhat record.One of:
licenses,conversations(Conversations and notes),tasks,issues,churn(Churn records),nps(NPS responses),invoices,opportunities,projects,sales, and 3 more. - Record ID
record_idtextRequired - The record's Planhat id, from 'List records' or an earlier step, or extid- followed by its id in your own system.
Outputs
recordobject- The record
record_typetext- The kind of record
Example output
{
"record": {
"_id": "61006fbf1df7fa77a20d9d0a",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"custom": {},
"externalId": "",
"name": "",
"sourceId": "",
"status": "",
"title": ""
},
"record_type": "licenses"
}List companies
List your Planhat companies (customer accounts) with their status, phase, health and revenue. Gets one page; to see more, run it again skipping the ones you have.
Inputs
- Order
ordertext - Which come first. Planhat's default is by name.One of:
name(Name, A to Z),-name(Name, Z to A),-_id(Newest first),_id(Oldest first),-updatedAt(Most recently changed first). - How many
limitnumber - How many to return, 1 to 5,000. Planhat's default is 100.From 1 to 5000.
- Skip
offsetnumber - How many to skip from the start, to get the next page (for 100 a page, 100 gets the second).At least 0.
Outputs
companieslist- The companies
countnumber- How many came back
Example output
{
"companies": [
{
"_id": "61006bc89a3e0b702ed8ea49",
"arr": 15000,
"city": "Riga",
"coOwner": "",
"country": "Latvia",
"createDate": "2021-07-27T20:25:44.430Z",
"csmScore": 4,
"custom": {
"Days in Phase": 0
},
"customerFrom": "2021-07-27T00:00:00.000Z",
"customerTo": "2022-07-27T00:00:00.000Z",
"description": "Up and coming tech company",
"domains": [
"tenet.com"
],
"externalId": "tenet-123",
"h": 3,
"lastActive": "2021-08-10T12:00:00.000Z",
"lastUpdated": "2021-08-11T16:12:41.657Z",
"mr": 15000,
"mrr": 1250,
"name": "Tenet",
"nrr30": 0,
"owner": "60ccb1c5965cc9e0f3848075",
"phase": "Onboarding",
"renewalDate": "2022-07-27T00:00:00.000Z",
"renewalDaysFromNow": 363,
"sourceId": "119",
"status": "customer",
"tags": [
"enterprise"
],
"updatedAt": "2021-08-09T16:54:17.298Z",
"web": "https://tenet.com"
}
],
"count": 1
}List end users
List the contacts (end users) at your customers, for one company or all, or find one by email. Gets one page; to see more, run it again skipping the ones you have.
Inputs
- Company
company_idtext - Only this company's end users.
- Email
emailtext - Only end users with this email address.
- Include archived
include_archivedtrue/false - Include archived end users as well.
- Order
ordertext - Which come first.One of:
-_id(Newest first),_id(Oldest first). - How many
limitnumber - How many to return, 1 to 2,000. Planhat's default is 100.From 1 to 2000.
- Skip
offsetnumber - How many to skip from the start, to get the next page (for 100 a page, 100 gets the second).At least 0.
Outputs
countnumber- How many came back
enduserslist- The end users
Example output
{
"count": 1,
"endusers": [
{
"_id": "610091916d643a7c418aef42",
"archived": false,
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"createDate": "2021-07-27T23:06:57.083Z",
"custom": {},
"email": "jane@example.com",
"externalId": "jane-1",
"featured": true,
"firstName": "Jane",
"lastActive": "2021-08-10T12:00:00.000Z",
"lastName": "Doe",
"name": "Jane Doe",
"phone": "+1 555 0100",
"position": "CFO",
"sourceId": "",
"tags": [],
"updatedAt": "2021-07-27T23:06:57.086Z"
}
]
}List records
List licenses, tasks, NPS responses, invoices, issues, churn records, opportunities, projects or another kind of record, for one company or all. Gets one page; to see more, run it again skipping the ones you have.
Inputs
- Record type
record_typetextRequired - Which kind of Planhat record.One of:
licenses,conversations(Conversations and notes),tasks,issues,churn(Churn records),nps(NPS responses),invoices,opportunities,projects,sales, and 3 more. - Company
company_idtext - Only this company's records.
- Order
ordertext - Which come first.One of:
-_id(Newest first),_id(Oldest first). - How many
limitnumber - How many to return, 1 to 2,000. Planhat's default is 100 for most.From 1 to 2000.
- Skip
offsetnumber - How many to skip from the start, to get the next page (for 100 a page, 100 gets the second).At least 0.
Outputs
countnumber- How many came back
record_typetext- The kind of record
recordslist- The records
Example output
{
"count": 1,
"record_type": "licenses",
"records": [
{
"_id": "61006fbf1df7fa77a20d9d0a",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"custom": {},
"externalId": "",
"name": "",
"sourceId": "",
"status": "",
"title": ""
}
]
}List team members
List the people on your Planhat team (CSMs, managers and admins) with their names and emails, for use as owners.
Inputs
- How many
limitnumber - How many to return, 1 to 10,000. Planhat returns them all by default.From 1 to 10000.
- Skip
offsetnumber - How many to skip from the start, to get the next page (for 100 a page, 100 gets the second).At least 0.
Outputs
countnumber- How many came back
userslist- The team members
Example output
{
"count": 1,
"users": [
{
"_id": "564b063a508f068051ee82a5",
"createdAt": "2016-02-11T18:07:49.173Z",
"email": "diego@example.com",
"externalId": "",
"firstName": "Diego",
"inactive": false,
"isHidden": false,
"lastName": "Checa",
"nickName": "Diego Checa",
"removed": false,
"updatedAt": "2021-08-11T16:12:41.657Z"
}
]
}Record churn
Record that a company churned, when, why and how much revenue was lost.
Inputs
- Company
company_idtextRequired - The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.
- Churned on
churn_datedate - The day they churned. Defaults to today.
- Reasons
reasonslist - Why they left, such as Budget cuts. Use your churn reasons in Planhat.
- Value lost
valuenumber - The revenue lost.At least 0.
- Currency
currencytext - The three-letter currency code, such as USD.
- Comment
commenttext - Anything else to note.
- External ID
external_idtext - The record's id in your own system.
- Custom fields
customobject - Values for the churn record's custom fields, each by the field's name in Planhat, such as {"Segment": "Enterprise"}.
Outputs
churnobject- The churn record
Example output
{
"churn": {
"_id": "6101d1f072c0e0884d5e8f57",
"churnDate": "2021-07-28T00:00:00.000Z",
"comment": "This account could return in the future",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"currency": "USD",
"custom": {},
"externalId": "",
"reasons": [
"Change in leadership",
"Budget cuts"
],
"value": 2000
}
}Send metric
Send one value of a custom metric (dimension data), such as active users, for a company, end user, asset or project, to use in health scores. Needs the Tenant token on the connection.
Inputs
- Metric ID
dimension_idtextRequired - The metric's id: letters, digits and _ with no spaces, such as activeusers.
- Value
valuenumberRequired - The number to record.
- External ID
external_idtextRequired - The company's (or other record's) id in your own system. It must be set as its External ID in Planhat.
- Record kind
modeltext - What the value is about. Defaults to a company.One of:
Company,EndUser(End user),Asset,Project. - When
recorded_atdate and time - When the value was measured. Defaults to now.
Outputs
dimensionIdtext- The metric's id
errorslist- Values Planhat refused
processednumber- How many values Planhat took
Example output
{
"dimensionId": "activeusers",
"errors": [],
"processed": 1
}Track user activity
Record that an end user did something in your product, such as Logged in or Sent invoice, so it counts towards their activity and health in Planhat. Needs the Tenant token on the connection.
Inputs
- Activity
action_nametextRequired - What they did, such as Logged in or Created a project.
- Email
emailtext - The end user's email. Needed unless you give their External ID.
- External ID
external_idtext - The end user's id in your own system.
- Name
nametext - Their full name, for a new end user.
- Company external ID
company_external_idtext - Their company's id in your own system, so a new end user lands on the right company.
- Weight
weightnumber - How much the activity counts compared with others.
- Passive
passivetrue/false - Record it without changing when they were last active.
- Details
infoobject - More about the activity, such as {"plan": "Pro"}.
Outputs
actiontext- The activity recorded
responsetext- What Planhat answered
senttrue/false- True once Planhat took it
Example output
{
"action": "Logged in",
"response": "OK",
"sent": true
}Update company
Change a company's name, status, phase, owner or other fields. Only the fields given change.
Inputs
- Company
company_idtextRequired - The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.
- Name
nametext - A new name for the company.
- Status
statustext - Where the company is as a customer.One of:
prospect,coming(Coming (signed, not yet live)),customer,canceled,lost. - Lifecycle phase
phasetext - The name of one of your lifecycle phases in Planhat, such as Onboarding.
- Owner
owner_idtext - The team member who owns the company (its CSM or account manager).
- External ID
external_idtext - The company's id in your own system.
- Domains
domainslist - The company's web domains, such as acme.com.
- Description
descriptiontext - A description of the company.
- Website
webtext - The company's website address.
- Country
countrytext - The company's country.
- City
citytext - The company's city.
- Tags
tagslist - Tags for the company.
- Custom fields
customobject - Values for the company's custom fields, each by the field's name in Planhat, such as {"Segment": "Enterprise"}.
Outputs
companyobject- The company
Example output
{
"company": {
"_id": "61006bc89a3e0b702ed8ea49",
"arr": 15000,
"city": "Riga",
"coOwner": "",
"country": "Latvia",
"createDate": "2021-07-27T20:25:44.430Z",
"csmScore": 4,
"custom": {
"Days in Phase": 0
},
"customerFrom": "2021-07-27T00:00:00.000Z",
"customerTo": "2022-07-27T00:00:00.000Z",
"description": "Up and coming tech company",
"domains": [
"tenet.com"
],
"externalId": "tenet-123",
"h": 3,
"lastActive": "2021-08-10T12:00:00.000Z",
"lastUpdated": "2021-08-11T16:12:41.657Z",
"mr": 15000,
"mrr": 1250,
"name": "Tenet",
"nrr30": 0,
"owner": "60ccb1c5965cc9e0f3848075",
"phase": "Onboarding",
"renewalDate": "2022-07-27T00:00:00.000Z",
"renewalDaysFromNow": 363,
"sourceId": "119",
"status": "customer",
"tags": [
"enterprise"
],
"updatedAt": "2021-08-09T16:54:17.298Z",
"web": "https://tenet.com"
}
}Update end user
Change an end user's name, email, position or other fields. Only the fields given change.
Inputs
- End user ID
enduser_idtextRequired - The end user's Planhat id, from 'List end users' or an earlier step, or extid- followed by their id in your own system.
- Email
emailtext - A new email address.
- First name
first_nametext - Their first name.
- Last name
last_nametext - Their last name.
- Position
positiontext - Their role, such as CFO.
- Phone
phonetext - Their phone number.
- External ID
external_idtext - Their id in your own system.
- Tags
tagslist - Tags for the end user.
- Featured contact
featuredtrue/false - Mark them as one of the company's featured contacts.
- Custom fields
customobject - Values for the end user's custom fields, each by the field's name in Planhat, such as {"Segment": "Enterprise"}.
Outputs
enduserobject- The end user
Example output
{
"enduser": {
"_id": "610091916d643a7c418aef42",
"archived": false,
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"createDate": "2021-07-27T23:06:57.083Z",
"custom": {},
"email": "jane@example.com",
"externalId": "jane-1",
"featured": true,
"firstName": "Jane",
"lastActive": "2021-08-10T12:00:00.000Z",
"lastName": "Doe",
"name": "Jane Doe",
"phone": "+1 555 0100",
"position": "CFO",
"sourceId": "",
"tags": [],
"updatedAt": "2021-07-27T23:06:57.086Z"
}
}Update task
Change a task's title, time, owner or status, mark it done, or archive it. Only the fields given change.
Inputs
- Task ID
task_idtextRequired - The task's Planhat id, from 'Create task', 'List records' or the task trigger.
- Title
titletext - A new title for the task.
- Description
descriptiontext - What the task is about.
- Starts
start_timedate and time - When the task starts or is due.
- Ends
end_timedate and time - When the task ends, for one with a set time.
- Owner
owner_idtext - The team member the task is for.
- Repeats
repeattext - How often the task comes back.One of:
daily(Every day),weekly(Every week),monthly(Every month),quarterly(Every quarter),yearly(Every year). - Status
statustext - The name of one of your task statuses in Planhat, such as In-progress.
- Custom fields
customobject - Values for the task's custom fields, each by the field's name in Planhat, such as {"Segment": "Enterprise"}.
- Done on
done_atdate and time - When the task was done, to mark it done.
- Archived
archivedtrue/false - Archive the task (Planhat hides archived tasks).
Outputs
taskobject- The task
Example output
{
"task": {
"_id": "6102c9748084189dcbf0df60",
"action": "Send renewal quote",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Tenet",
"createdAt": "2022-07-05T09:51:52.818Z",
"custom": {},
"dateDone": "2022-07-06T09:00:00.000Z",
"description": "<p>Call the client.</p>",
"endTime": "2021-07-29T01:00:00.000Z",
"isArchived": false,
"mainType": "task",
"ownerId": "58e231b14246fc73139f29e8",
"ownerName": "Alex",
"repeat": "",
"startTime": "2021-07-29T00:00:00.000Z",
"status": "In-progress",
"updatedAt": "2022-07-05T09:51:52.818Z"
}
}