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

ActionWhat it does
Add noteLog a note on a company's timeline, optionally naming the end users it involved.
Bulk upsert companiesCreate or update up to 5,000 companies at once.
Create companyAdd a company (a customer or prospect) to Planhat.
Create end userAdd a contact (end user) to a company.
Create issueLog an issue (a bug or feature request) and link it to the companies and end users it affects.
Create licenseAdd a license (a subscription the company pays for) with its product, dates and value.
Create opportunityAdd a sales opportunity (an upsell or renewal) to a company.
Create taskCreate a task (a to-do) for a company, with a due time and an owner.
Delete companyDelete a company from Planhat.
Delete end userDelete an end user from Planhat.
Delete recordDelete one license, task, note, NPS response or other record by its id.
Get companyGet one company with its owner, status, phase, health score, revenue, renewal date and custom fields.
Get end userGet one end user (a contact at a customer) with their company, position, activity and custom fields.
Get metric valuesRead the values a custom metric has had, for one company or all, between two dates.
Get recordGet one license, task, NPS response, invoice or other record by its id.
List companiesList your Planhat companies (customer accounts) with their status, phase, health and revenue.
List end usersList the contacts (end users) at your customers, for one company or all, or find one by email.
List recordsList licenses, tasks, NPS responses, invoices, issues, churn records, opportunities, projects or another kind of record, for one company or all.
List team membersList the people on your Planhat team (CSMs, managers and admins) with their names and emails, for use as owners.
Record churnRecord that a company churned, when, why and how much revenue was lost.
Send metricSend 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 activityRecord 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 companyChange a company's name, status, phase, owner or other fields.
Update end userChange an end user's name, email, position or other fields.
Update taskChange 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

Companycompany_idtextRequired
The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.
NotedescriptiontextRequired
What happened, in a few sentences.
Subjectsubjecttext
A title for the note.
Whenoccurred_atdate and time
When it happened. Defaults to now.
Touch typetouch_typetext
The name of one of your touch types in Planhat, such as Call. Leave empty for a note.
End user IDsenduser_idslist
The Planhat ids of the end users it involved.
External IDexternal_idtext
The record's id in your own system.
Custom fieldscustomobject
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

CompaniescompanieslistRequired
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

NamenametextRequired
The company's name.
Statusstatustext
Where the company is as a customer.One of: prospect, coming (Coming (signed, not yet live)), customer, canceled, lost.
Lifecycle phasephasetext
The name of one of your lifecycle phases in Planhat, such as Onboarding.
Ownerowner_idtext
The team member who owns the company (its CSM or account manager).
External IDexternal_idtext
The company's id in your own system.
Domainsdomainslist
The company's web domains, such as acme.com.
Descriptiondescriptiontext
A description of the company.
Websitewebtext
The company's website address.
Countrycountrytext
The company's country.
Citycitytext
The company's city.
Tagstagslist
Tags for the company.
Custom fieldscustomobject
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

Companycompany_idtextRequired
The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.
Emailemailtext
Their email address. Needed unless you give an External ID.
First namefirst_nametext
Their first name.
Last namelast_nametext
Their last name.
Positionpositiontext
Their role, such as CFO.
Phonephonetext
Their phone number.
External IDexternal_idtext
Their id in your own system.
Tagstagslist
Tags for the end user.
Featured contactfeaturedtrue/false
Mark them as one of the company's featured contacts.
Custom fieldscustomobject
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

TitletitletextRequired
A short title for the issue.
Descriptiondescriptiontext
What the issue is.
Companiescompany_idslist
The companies it affects.
End user IDsenduser_idslist
The Planhat ids of the end users it affects.
Statusstatustext
Its status, such as Open.
Priorityprioritytext
Its priority, such as High.
Linksource_urltext
A link to the issue in another tool, such as Jira.
Custom fieldscustomobject
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

Companycompany_idtextRequired
The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.
Starts onfrom_datedateRequired
The first day of the license.
Ends onto_datedate
The last day, for a license with a fixed term.
Total valuevaluenumber
The value for the whole period. Give this or the monthly value.At least 0.
Monthly valuemrrnumber
The monthly value, for an ongoing license.At least 0.
Productproducttext
The product the license is for, such as Subscription.
Currencycurrencytext
The three-letter currency code, such as EUR. Defaults to USD.
Fixed termfixed_periodtrue/false
On for a license with an end date; off for an ongoing one.
Renews automaticallyauto_renewstrue/false
Let Planhat renew it once its notice period passes.
Renewal statusrenewal_statustext
Whether it is ongoing, renewed or lost.One of: ongoing, renewed, lost.
External IDexternal_idtext
The record's id in your own system.
Custom fieldscustomobject
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

Companycompany_idtextRequired
The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.
TitletitletextRequired
A name for the opportunity.
Statusstatustext
Whether it is open, won or lost. Defaults to active.One of: active, won, lost.
Sales stagesales_stagetext
Its stage, such as Pitched.
Ownerowner_idtext
The team member who owns it.
Monthly valuemrrnumber
The monthly recurring value.At least 0.
One-off valuenrrnumber
The value that doesn't recur.At least 0.
Currencycurrencytext
The three-letter currency code, such as USD.
Deal datedeal_datedate
When the deal starts.
Close dateclose_datedate
When it is expected to close.
External IDexternal_idtext
The record's id in your own system.
Custom fieldscustomobject
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

Companycompany_idtextRequired
The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.
TitletitletextRequired
What needs doing, such as Send renewal quote.
Descriptiondescriptiontext
What the task is about.
Startsstart_timedate and time
When the task starts or is due.
Endsend_timedate and time
When the task ends, for one with a set time.
Ownerowner_idtext
The team member the task is for.
Repeatsrepeattext
How often the task comes back.One of: daily (Every day), weekly (Every week), monthly (Every month), quarterly (Every quarter), yearly (Every year).
Statusstatustext
The name of one of your task statuses in Planhat, such as In-progress.
Custom fieldscustomobject
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

Companycompany_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 IDenduser_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 typerecord_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 IDrecord_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

Companycompany_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 IDenduser_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

Companycompany_idtext
Only this company's values. Pick one, or give its Planhat id.
Metric IDdimension_idtext
The metric's id, such as activeusers.
Fromfrom_datedate
The first day to include.
Toto_datedate
The last day to include.
How manylimitnumber
How many to return, 1 to 2,000. Planhat decides when left empty.From 1 to 2000.
Skipoffsetnumber
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 typerecord_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 IDrecord_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

Orderordertext
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 manylimitnumber
How many to return, 1 to 5,000. Planhat's default is 100.From 1 to 5000.
Skipoffsetnumber
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

Companycompany_idtext
Only this company's end users.
Emailemailtext
Only end users with this email address.
Include archivedinclude_archivedtrue/false
Include archived end users as well.
Orderordertext
Which come first.One of: -_id (Newest first), _id (Oldest first).
How manylimitnumber
How many to return, 1 to 2,000. Planhat's default is 100.From 1 to 2000.
Skipoffsetnumber
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 typerecord_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.
Companycompany_idtext
Only this company's records.
Orderordertext
Which come first.One of: -_id (Newest first), _id (Oldest first).
How manylimitnumber
How many to return, 1 to 2,000. Planhat's default is 100 for most.From 1 to 2000.
Skipoffsetnumber
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 manylimitnumber
How many to return, 1 to 10,000. Planhat returns them all by default.From 1 to 10000.
Skipoffsetnumber
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

Companycompany_idtextRequired
The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.
Churned onchurn_datedate
The day they churned. Defaults to today.
Reasonsreasonslist
Why they left, such as Budget cuts. Use your churn reasons in Planhat.
Value lostvaluenumber
The revenue lost.At least 0.
Currencycurrencytext
The three-letter currency code, such as USD.
Commentcommenttext
Anything else to note.
External IDexternal_idtext
The record's id in your own system.
Custom fieldscustomobject
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 IDdimension_idtextRequired
The metric's id: letters, digits and _ with no spaces, such as activeusers.
ValuevaluenumberRequired
The number to record.
External IDexternal_idtextRequired
The company's (or other record's) id in your own system. It must be set as its External ID in Planhat.
Record kindmodeltext
What the value is about. Defaults to a company.One of: Company, EndUser (End user), Asset, Project.
Whenrecorded_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

Activityaction_nametextRequired
What they did, such as Logged in or Created a project.
Emailemailtext
The end user's email. Needed unless you give their External ID.
External IDexternal_idtext
The end user's id in your own system.
Namenametext
Their full name, for a new end user.
Company external IDcompany_external_idtext
Their company's id in your own system, so a new end user lands on the right company.
Weightweightnumber
How much the activity counts compared with others.
Passivepassivetrue/false
Record it without changing when they were last active.
Detailsinfoobject
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

Companycompany_idtextRequired
The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.
Namenametext
A new name for the company.
Statusstatustext
Where the company is as a customer.One of: prospect, coming (Coming (signed, not yet live)), customer, canceled, lost.
Lifecycle phasephasetext
The name of one of your lifecycle phases in Planhat, such as Onboarding.
Ownerowner_idtext
The team member who owns the company (its CSM or account manager).
External IDexternal_idtext
The company's id in your own system.
Domainsdomainslist
The company's web domains, such as acme.com.
Descriptiondescriptiontext
A description of the company.
Websitewebtext
The company's website address.
Countrycountrytext
The company's country.
Citycitytext
The company's city.
Tagstagslist
Tags for the company.
Custom fieldscustomobject
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 IDenduser_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.
Emailemailtext
A new email address.
First namefirst_nametext
Their first name.
Last namelast_nametext
Their last name.
Positionpositiontext
Their role, such as CFO.
Phonephonetext
Their phone number.
External IDexternal_idtext
Their id in your own system.
Tagstagslist
Tags for the end user.
Featured contactfeaturedtrue/false
Mark them as one of the company's featured contacts.
Custom fieldscustomobject
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 IDtask_idtextRequired
The task's Planhat id, from 'Create task', 'List records' or the task trigger.
Titletitletext
A new title for the task.
Descriptiondescriptiontext
What the task is about.
Startsstart_timedate and time
When the task starts or is due.
Endsend_timedate and time
When the task ends, for one with a set time.
Ownerowner_idtext
The team member the task is for.
Repeatsrepeattext
How often the task comes back.One of: daily (Every day), weekly (Every week), monthly (Every month), quarterly (Every quarter), yearly (Every year).
Statusstatustext
The name of one of your task statuses in Planhat, such as In-progress.
Custom fieldscustomobject
Values for the task's custom fields, each by the field's name in Planhat, such as {"Segment": "Enterprise"}.
Done ondone_atdate and time
When the task was done, to mark it done.
Archivedarchivedtrue/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"
  }
}

On this page