# Planhat

> 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.

App · 25 actions. Web page: https://docs.lodol.com/docs/integrations/planhat

## Actions

### 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_id`, text, required): The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.
- Note (`description`, text, required): What happened, in a few sentences.
- Subject (`subject`, text): A title for the note.
- When (`occurred_at`, date and time): When it happened. Defaults to now.
- Touch type (`touch_type`, text): The name of one of your touch types in Planhat, such as Call. Leave empty for a note.
- End user IDs (`enduser_ids`, list): The Planhat ids of the end users it involved.
- External ID (`external_id`, text): The record's id in your own system.
- Custom fields (`custom`, object): Values for the note's custom fields, each by the field's name in Planhat, such as {"Segment": "Enterprise"}.

**Outputs**

- `note` (object): The note

**Example output**

```json
{
  "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 (`companies`, list, required): A list of companies, each with Planhat's field names, such as [{"externalId": "acme-1", "name": "Acme", "phase": "Onboarding"}].

**Outputs**

- `created` (number): How many were created
- `createdErrors` (list): Why each failed create failed
- `insertsKeys` (list): The keys of the new companies
- `modified` (list): The ids of the updated companies
- `nonupdates` (number): How many matched but had nothing to change
- `permissionErrors` (list): Changes the token wasn't allowed
- `updated` (number): How many were updated
- `updatedErrors` (list): Why each failed update failed
- `updatesKeys` (list): The keys of the updated companies
- `upsertedIds` (list): The ids of the new companies

**Example output**

```json
{
  "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 (`name`, text, required): The company's name.
- Status (`status`, text): Where the company is as a customer. One of: `prospect`, `coming` (Coming (signed, not yet live)), `customer`, `canceled`, `lost`.
- Lifecycle phase (`phase`, text): The name of one of your lifecycle phases in Planhat, such as Onboarding.
- Owner (`owner_id`, text): The team member who owns the company (its CSM or account manager).
- External ID (`external_id`, text): The company's id in your own system.
- Domains (`domains`, list): The company's web domains, such as acme.com.
- Description (`description`, text): A description of the company.
- Website (`web`, text): The company's website address.
- Country (`country`, text): The company's country.
- City (`city`, text): The company's city.
- Tags (`tags`, list): Tags for the company.
- Custom fields (`custom`, object): Values for the company's custom fields, each by the field's name in Planhat, such as {"Segment": "Enterprise"}.

**Outputs**

- `company` (object): The company

**Example output**

```json
{
  "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_id`, text, required): The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.
- Email (`email`, text): Their email address. Needed unless you give an External ID.
- First name (`first_name`, text): Their first name.
- Last name (`last_name`, text): Their last name.
- Position (`position`, text): Their role, such as CFO.
- Phone (`phone`, text): Their phone number.
- External ID (`external_id`, text): Their id in your own system.
- Tags (`tags`, list): Tags for the end user.
- Featured contact (`featured`, true/false): Mark them as one of the company's featured contacts.
- Custom fields (`custom`, object): Values for the end user's custom fields, each by the field's name in Planhat, such as {"Segment": "Enterprise"}.

**Outputs**

- `enduser` (object): The end user

**Example output**

```json
{
  "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 (`title`, text, required): A short title for the issue.
- Description (`description`, text): What the issue is.
- Companies (`company_ids`, list): The companies it affects.
- End user IDs (`enduser_ids`, list): The Planhat ids of the end users it affects.
- Status (`status`, text): Its status, such as Open.
- Priority (`priority`, text): Its priority, such as High.
- Link (`source_url`, text): A link to the issue in another tool, such as Jira.
- Custom fields (`custom`, object): Values for the issue's custom fields, each by the field's name in Planhat, such as {"Segment": "Enterprise"}.

**Outputs**

- `issue` (object): The issue

**Example output**

```json
{
  "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_id`, text, required): The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.
- Starts on (`from_date`, date, required): The first day of the license.
- Ends on (`to_date`, date): The last day, for a license with a fixed term.
- Total value (`value`, number): The value for the whole period. Give this or the monthly value. At least 0.
- Monthly value (`mrr`, number): The monthly value, for an ongoing license. At least 0.
- Product (`product`, text): The product the license is for, such as Subscription.
- Currency (`currency`, text): The three-letter currency code, such as EUR. Defaults to USD.
- Fixed term (`fixed_period`, true/false): On for a license with an end date; off for an ongoing one.
- Renews automatically (`auto_renews`, true/false): Let Planhat renew it once its notice period passes.
- Renewal status (`renewal_status`, text): Whether it is ongoing, renewed or lost. One of: `ongoing`, `renewed`, `lost`.
- External ID (`external_id`, text): The record's id in your own system.
- Custom fields (`custom`, object): Values for the license's custom fields, each by the field's name in Planhat, such as {"Segment": "Enterprise"}.

**Outputs**

- `license` (object): The license

**Example output**

```json
{
  "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_id`, text, required): The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.
- Title (`title`, text, required): A name for the opportunity.
- Status (`status`, text): Whether it is open, won or lost. Defaults to active. One of: `active`, `won`, `lost`.
- Sales stage (`sales_stage`, text): Its stage, such as Pitched.
- Owner (`owner_id`, text): The team member who owns it.
- Monthly value (`mrr`, number): The monthly recurring value. At least 0.
- One-off value (`nrr`, number): The value that doesn't recur. At least 0.
- Currency (`currency`, text): The three-letter currency code, such as USD.
- Deal date (`deal_date`, date): When the deal starts.
- Close date (`close_date`, date): When it is expected to close.
- External ID (`external_id`, text): The record's id in your own system.
- Custom fields (`custom`, object): Values for the opportunity's custom fields, each by the field's name in Planhat, such as {"Segment": "Enterprise"}.

**Outputs**

- `opportunity` (object): The opportunity

**Example output**

```json
{
  "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_id`, text, required): The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.
- Title (`title`, text, required): What needs doing, such as Send renewal quote.
- Description (`description`, text): What the task is about.
- Starts (`start_time`, date and time): When the task starts or is due.
- Ends (`end_time`, date and time): When the task ends, for one with a set time.
- Owner (`owner_id`, text): The team member the task is for.
- Repeats (`repeat`, text): How often the task comes back. One of: `daily` (Every day), `weekly` (Every week), `monthly` (Every month), `quarterly` (Every quarter), `yearly` (Every year).
- Status (`status`, text): The name of one of your task statuses in Planhat, such as In-progress.
- Custom fields (`custom`, object): Values for the task's custom fields, each by the field's name in Planhat, such as {"Segment": "Enterprise"}.

**Outputs**

- `task` (object): The task

**Example output**

```json
{
  "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_id`, text, required): The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.

**Outputs**

- `deleted` (true/false): True once Planhat deleted it
- `deleted_count` (number): How many Planhat deleted
- `record_id` (text): The id that was deleted

**Example output**

```json
{
  "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_id`, text, required): 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**

- `deleted` (true/false): True once Planhat deleted it
- `deleted_count` (number): How many Planhat deleted
- `record_id` (text): The id that was deleted

**Example output**

```json
{
  "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_type`, text, required): 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_id`, text, required): The record's Planhat id, from 'List records' or an earlier step, or extid- followed by its id in your own system.

**Outputs**

- `deleted` (true/false): True once Planhat deleted it
- `deleted_count` (number): How many Planhat deleted
- `record_id` (text): The id that was deleted
- `record_type` (text): The kind of record

**Example output**

```json
{
  "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_id`, text, required): The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.

**Outputs**

- `company` (object): The company

**Example output**

```json
{
  "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_id`, text, required): 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**

- `enduser` (object): The end user

**Example output**

```json
{
  "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_id`, text): Only this company's values. Pick one, or give its Planhat id.
- Metric ID (`dimension_id`, text): The metric's id, such as activeusers.
- From (`from_date`, date): The first day to include.
- To (`to_date`, date): The last day to include.
- How many (`limit`, number): How many to return, 1 to 2,000. Planhat decides when left empty. From 1 to 2000.
- Skip (`offset`, number): How many to skip from the start, to get the next page (for 100 a page, 100 gets the second). At least 0.

**Outputs**

- `count` (number): How many came back
- `values` (list): The metric's values

**Example output**

```json
{
  "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_type`, text, required): 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_id`, text, required): The record's Planhat id, from 'List records' or an earlier step, or extid- followed by its id in your own system.

**Outputs**

- `record` (object): The record
- `record_type` (text): The kind of record

**Example output**

```json
{
  "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 (`order`, text): 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 (`limit`, number): How many to return, 1 to 5,000. Planhat's default is 100. From 1 to 5000.
- Skip (`offset`, number): How many to skip from the start, to get the next page (for 100 a page, 100 gets the second). At least 0.

**Outputs**

- `companies` (list): The companies
- `count` (number): How many came back

**Example output**

```json
{
  "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_id`, text): Only this company's end users.
- Email (`email`, text): Only end users with this email address.
- Include archived (`include_archived`, true/false): Include archived end users as well.
- Order (`order`, text): Which come first. One of: `-_id` (Newest first), `_id` (Oldest first).
- How many (`limit`, number): How many to return, 1 to 2,000. Planhat's default is 100. From 1 to 2000.
- Skip (`offset`, number): How many to skip from the start, to get the next page (for 100 a page, 100 gets the second). At least 0.

**Outputs**

- `count` (number): How many came back
- `endusers` (list): The end users

**Example output**

```json
{
  "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_type`, text, required): 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_id`, text): Only this company's records.
- Order (`order`, text): Which come first. One of: `-_id` (Newest first), `_id` (Oldest first).
- How many (`limit`, number): How many to return, 1 to 2,000. Planhat's default is 100 for most. From 1 to 2000.
- Skip (`offset`, number): How many to skip from the start, to get the next page (for 100 a page, 100 gets the second). At least 0.

**Outputs**

- `count` (number): How many came back
- `record_type` (text): The kind of record
- `records` (list): The records

**Example output**

```json
{
  "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 (`limit`, number): How many to return, 1 to 10,000. Planhat returns them all by default. From 1 to 10000.
- Skip (`offset`, number): How many to skip from the start, to get the next page (for 100 a page, 100 gets the second). At least 0.

**Outputs**

- `count` (number): How many came back
- `users` (list): The team members

**Example output**

```json
{
  "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_id`, text, required): The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.
- Churned on (`churn_date`, date): The day they churned. Defaults to today.
- Reasons (`reasons`, list): Why they left, such as Budget cuts. Use your churn reasons in Planhat.
- Value lost (`value`, number): The revenue lost. At least 0.
- Currency (`currency`, text): The three-letter currency code, such as USD.
- Comment (`comment`, text): Anything else to note.
- External ID (`external_id`, text): The record's id in your own system.
- Custom fields (`custom`, object): Values for the churn record's custom fields, each by the field's name in Planhat, such as {"Segment": "Enterprise"}.

**Outputs**

- `churn` (object): The churn record

**Example output**

```json
{
  "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_id`, text, required): The metric's id: letters, digits and _ with no spaces, such as activeusers.
- Value (`value`, number, required): The number to record.
- External ID (`external_id`, text, required): The company's (or other record's) id in your own system. It must be set as its External ID in Planhat.
- Record kind (`model`, text): What the value is about. Defaults to a company. One of: `Company`, `EndUser` (End user), `Asset`, `Project`.
- When (`recorded_at`, date and time): When the value was measured. Defaults to now.

**Outputs**

- `dimensionId` (text): The metric's id
- `errors` (list): Values Planhat refused
- `processed` (number): How many values Planhat took

**Example output**

```json
{
  "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_name`, text, required): What they did, such as Logged in or Created a project.
- Email (`email`, text): The end user's email. Needed unless you give their External ID.
- External ID (`external_id`, text): The end user's id in your own system.
- Name (`name`, text): Their full name, for a new end user.
- Company external ID (`company_external_id`, text): Their company's id in your own system, so a new end user lands on the right company.
- Weight (`weight`, number): How much the activity counts compared with others.
- Passive (`passive`, true/false): Record it without changing when they were last active.
- Details (`info`, object): More about the activity, such as {"plan": "Pro"}.

**Outputs**

- `action` (text): The activity recorded
- `response` (text): What Planhat answered
- `sent` (true/false): True once Planhat took it

**Example output**

```json
{
  "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_id`, text, required): The company. Pick one, or give its Planhat id, or extid- followed by its id in your own system.
- Name (`name`, text): A new name for the company.
- Status (`status`, text): Where the company is as a customer. One of: `prospect`, `coming` (Coming (signed, not yet live)), `customer`, `canceled`, `lost`.
- Lifecycle phase (`phase`, text): The name of one of your lifecycle phases in Planhat, such as Onboarding.
- Owner (`owner_id`, text): The team member who owns the company (its CSM or account manager).
- External ID (`external_id`, text): The company's id in your own system.
- Domains (`domains`, list): The company's web domains, such as acme.com.
- Description (`description`, text): A description of the company.
- Website (`web`, text): The company's website address.
- Country (`country`, text): The company's country.
- City (`city`, text): The company's city.
- Tags (`tags`, list): Tags for the company.
- Custom fields (`custom`, object): Values for the company's custom fields, each by the field's name in Planhat, such as {"Segment": "Enterprise"}.

**Outputs**

- `company` (object): The company

**Example output**

```json
{
  "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_id`, text, required): 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 (`email`, text): A new email address.
- First name (`first_name`, text): Their first name.
- Last name (`last_name`, text): Their last name.
- Position (`position`, text): Their role, such as CFO.
- Phone (`phone`, text): Their phone number.
- External ID (`external_id`, text): Their id in your own system.
- Tags (`tags`, list): Tags for the end user.
- Featured contact (`featured`, true/false): Mark them as one of the company's featured contacts.
- Custom fields (`custom`, object): Values for the end user's custom fields, each by the field's name in Planhat, such as {"Segment": "Enterprise"}.

**Outputs**

- `enduser` (object): The end user

**Example output**

```json
{
  "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_id`, text, required): The task's Planhat id, from 'Create task', 'List records' or the task trigger.
- Title (`title`, text): A new title for the task.
- Description (`description`, text): What the task is about.
- Starts (`start_time`, date and time): When the task starts or is due.
- Ends (`end_time`, date and time): When the task ends, for one with a set time.
- Owner (`owner_id`, text): The team member the task is for.
- Repeats (`repeat`, text): How often the task comes back. One of: `daily` (Every day), `weekly` (Every week), `monthly` (Every month), `quarterly` (Every quarter), `yearly` (Every year).
- Status (`status`, text): The name of one of your task statuses in Planhat, such as In-progress.
- Custom fields (`custom`, object): Values for the task's custom fields, each by the field's name in Planhat, such as {"Segment": "Enterprise"}.
- Done on (`done_at`, date and time): When the task was done, to mark it done.
- Archived (`archived`, true/false): Archive the task (Planhat hides archived tasks).

**Outputs**

- `task` (object): The task

**Example output**

```json
{
  "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"
  }
}
```
