--- title: Planhat API Integration on Truto slug: planhat category: CRM canonical: "https://truto.one/integrations/detail/planhat/" --- # Planhat API Integration on Truto **Category:** CRM **Status:** Beta ## Unified APIs ### Unified CRM API - **Accounts** — The accounts represent a company in a CRM. - **Contacts** — The contacts represent an existing point of contact at a company in a CRM. - **Engagements** — The engagements represent an interaction noted in a CRM. - **Fields** — The fields of entities in a CRM. - **Notes** — The notes represent a note on another object in a CRM. - **Opportunities** — The opportunities represent an opportunity in a CRM. - **Projects** — - **Tasks** — The tasks represent a task in a CRM. - **Users** — The users represent a user in a CRM. ### Unified Ticketing API - **Accounts** — Accounts represent the companies or organizations that you are in contact with. Accounts have one or more Contacts associated with them. - **Collections** — Tickets and contacts can be grouped into Collections. Collection resource usually maps to the various grouping systems used in the underlying product. Some examples are lists, projects, epics, etc. You can differentiate between these grouping systems using the type attribute of a Collection. - **Fields** — Fields represent the attributes defined for various entities in the underlying product. Depending on the underlying product, custom attributes can be defined by a User on various entities like Ticket, Contact, etc. is_user_defined attribute within Field can be used to differentiate between custom and system defined Fields. - **Tickets** — Core resource which represents some work that needs to be carried out. Tickets are usually mapped to issues, tasks, work items, etc. depending on the underlying product. - **Users** — Users represent the people using the underlying ticketing system. They are usually called agents, team members, admins, etc. - **Workspaces** — Workspaces represent the top-level subdivision in a ticketing system. They usually have their own set of settings, tickets, statuses, priorities and users. Some of the usual terminologies used by the products for the top-level subdivision are projects, bases, spaces, workspace, etc. A Workspace could belong to an Organization. ## MCP-ready AI tools Truto exposes 97 tools for Planhat that AI agents can call directly. - **list_all_planhat_campaigns** — List campaigns in Planhat. Returns an array of campaigns including _id, companyId, name, and campaignPurpose fields. Supports filtering, sorting, and pagination. - **get_single_planhat_campaign_by_id** — Get campaign by id in Planhat. Requires id. Returns key fields including _id, companyId, companyName, name, campaignPurpose, externalId, custom, and usage. - **update_a_planhat_campaign_by_id** — Update a specific campaign in Planhat using id. The response returns key fields including _id, name, campaignPurpose, companyId, externalId, companyName, __v, and sourceId. - **create_a_planhat_campaign** — Create a campaign in Planhat. Requires name and companyId. The response includes _id, name, campaignPurpose, companyId, externalId, sourceId, custom fields, and companyName. - **delete_a_planhat_campaign_by_id** — Delete a specific campaign in Planhat. Requires id. Returns fields n, ok, and deletedCount indicating the number of deleted items and operation status. - **list_all_planhat_companies** — List companies in Planhat. Returns key fields including _id, name, status, phase, domains, tags, owner, externalId, and custom metrics. - **get_single_planhat_company_by_id** — Get a specific company in Planhat using id. Returns key fields including _id, name, phase, status, createDate, lastUpdated, owner, domains, custom fields, and sales details for the specified company. - **create_a_planhat_company** — Create a new company in Planhat. Requires the name field. Returns company details including _id, name, status, externalId, phase, domains, and country. - **update_a_planhat_company_by_id** — Update a specific company in Planhat using its id. The response returns details including _id, name, status, externalId, phase, and key financial metrics such as mrrTotal and nrrTotal. - **delete_a_planhat_company_by_id** — Delete a company in Planhat using id. Requires id. Returns fields n, ok, and deletedCount indicating the number of deleted records and success status. - **list_all_planhat_invoices** — List invoices in Planhat. Returns fields such as _id, invoiceNo, amountDue, amountPaid, status, cId, cName, invoiceDate, dueDate, lineItems, amountTotal, and updatedAt for each invoice in the response. - **get_single_planhat_invoice_by_id** — Get a specific invoice by id in Planhat. Returns fields such as _id, invoiceNo, amountDue, amountPaid, status, cName, invoiceDate, dueDate, lineItems, and amountTotal. Requires id as a path parameter. - **create_a_planhat_invoice** — Create an invoice in Planhat. Requires cId. Optionally include invoiceDate and currency for meaningful data. Returns fields such as _id, invoiceNo, amountTotal, status, dueDate, invoiceDate, currency, and lineItems in the response. - **update_a_planhat_invoice_by_id** — Update an existing invoice in Planhat using its id. Returns fields such as _id, invoiceNo, amountTotal, status, dueDate, currency, lineItems, cName, and updatedAt in the response. - **delete_a_planhat_invoice_by_id** — Delete an invoice in Planhat using id. Requires id. Returns n, ok, and deletedCount fields indicating operation success and number of invoices removed. - **list_all_planhat_endusers** — List endusers in Planhat. Returns fields such as _id, companyId, name, email, lastActive, relevance, experience, and custom attributes for each enduser. - **get_single_planhat_enduser_by_id** — Get details of a specific enduser in Planhat using id. Returns key fields such as _id, companyId, companyName, name, email, lastActive, and custom attributes. - **create_a_planhat_enduser** — Create an enduser in Planhat. Requires companyId and at least one of email, externalId, or sourceId. Returns fields such as _id, email, firstName, lastName, companyId, companyName, name, createDate, and updatedAt. - **update_a_planhat_enduser_by_id** — Update an existing enduser in Planhat. Requires id. Returns fields such as _id, email, firstName, lastName, companyId, name, and updatedAt. - **delete_a_planhat_enduser_by_id** — Delete a specific enduser in Planhat using id. Returns confirmation fields n, ok, and deletedCount indicating deletion status. - **list_all_planhat_issues** — Get a list of issues in Planhat. Returns an array of issues with fields _id, companyIds, title, and status. - **get_single_planhat_issue_by_id** — Get a specific issue in Planhat by id. Returns fields such as _id, companyIds, title, status, createdAt, and updatedAt in the response. - **create_a_planhat_issue** — Create a new issue in Planhat. Requires title. Optionally include companyIds or enduserIds. Returns fields such as _id, title, description, status, companyIds, enduserIds, createdAt, and updatedAt. - **update_a_planhat_issue_by_id** — Update an issue in Planhat using id. Requires id. Returns fields such as _id, title, description, status, companies, updatedAt, and createdAt to confirm the update. - **delete_a_planhat_issue_by_id** — Delete an issue in Planhat. Requires id. Returns n, ok, and deletedCount fields indicating the result of the deletion operation. - **list_all_planhat_licenses** — List licenses in Planhat. Returns an array of licenses with fields such as _id, companyId, value, and product. - **get_single_planhat_license_by_id** — Get a specific license in Planhat using id. Returns renewalStatus, renewalDate, mrr, companyName, sourceId, and currency details. Supports id, extid, or srcid as identifiers. - **create_a_planhat_license** — Create a new license in Planhat. Requires companyId. Returns details such as renewalStatus, companyId, product, _currency, mrr, fromDate, toDate, and value. - **update_a_planhat_license_by_id** — Update a specific license in Planhat using id. Returns fields like renewalStatus, companyName, mrr, product, value, and renewalDate representing the updated license details. - **delete_a_planhat_license_by_id** — Delete a specific license in Planhat. Requires id. Returns fields n, ok, and deletedCount indicating deletion result. - **list_all_planhat_opportunities** — List opportunities in Planhat. Returns fields such as _id, title, and status for each opportunity. Supports filtering and sorting. Requires no parameters. - **get_single_planhat_opportunity_by_id** — Get a specific opportunity in Planhat using id. Returns fields such as _id (unique identifier), status (current state), companyId (related company), stageHistory (movement through stages), landingDate, comments, and companyName. - **create_a_planhat_opportunity** — Create an opportunity in Planhat. Requires companyId. Returns fields such as _id, status, salesStage, dealDate, ownerId, _currency, companyId, title, mrr, nrr, and companyName representing the created opportunity details. - **update_a_planhat_opportunity_by_id** — Update an existing opportunity in Planhat using id or externalId. Requires id. Returns fields such as _id, status, salesStage, dealDate, companyId, companyName, mrr, nrr, and closeDate. - **delete_a_planhat_opportunity_by_id** — Delete an opportunity in Planhat by id. Requires id. Returns fields n, ok, and deletedCount indicating the number of deleted records and operation success. - **list_all_planhat_projects** — List projects in Planhat. Returns an array of projects with fields _id (unique project identifier), companyId (ID of associated company), and name (project name). - **get_single_planhat_project_by_id** — Get a specific project in Planhat by id. Returns fields including _id, companyId, companyName, name, startDate, custom attributes (e.g., Product, Renewal in days, Activity Count), and mrr. - **create_a_planhat_project** — Create a new project in Planhat. Requires name and companyId. Returns project details including _id, companyId, name, currency, mrr, startDate, endDate, and companyName. - **update_a_planhat_project_by_id** — Update a project in Planhat using id. Returns project details such as _id, companyId, name, startDate, endDate, currency, mrr, and custom fields. The project id must be provided in the request URL. - **delete_a_planhat_project_by_id** — Delete a specific project in Planhat. Requires id. Returns n, ok, and deletedCount indicating the deletion status and number of projects deleted. - **list_all_planhat_tasks** — Get list of tasks in Planhat. Returns an array of tasks with fields such as _id, mainType, ownerId, companyId, companyName, createdAt, updatedAt, and action. Requires no parameters. - **get_single_planhat_task_by_id** — Get a specific task in Planhat by id. The response includes key fields such as mainType, status, companyName, ownerName, workflowName, and timestamps for createdAt and updatedAt. - **create_a_planhat_task** — Create a new task in Planhat. Requires companyId. Returns fields such as mainType, action, status, companyId, ownerId, and timestamps (createdAt, updatedAt) representing the created task details. - **update_a_planhat_task_by_id** — Update a specific task in Planhat using id. Returns fields such as mainType, status, action, description, ownerId, companyId, createdAt, and updatedAt for the updated task. - **delete_a_planhat_task_by_id** — Delete a specific task in Planhat. Requires id parameter in the request path. Returns n, ok, and deletedCount to confirm the deletion status. - **list_all_planhat_tickets** — List tickets in Planhat. Returns fields such as _id, externalId, subject, snippet, status, email, url, companyId, companyName, createDate, and updateDate in the response. - **delete_a_planhat_ticket_by_id** — Delete a specific ticket in Planhat using id. Requires id in the request URL. Returns key ticket fields such as _id, subject, status, source, and updateDate for confirmation after deletion. - **list_all_planhat_users** — List all users in Planhat. Returns fields such as firstName, lastName, nickName, email, externalId, image, isHidden, removed, inactive, managers, teams, isExposedAsSenderOption, createdAt, updatedAt, and tzOffset. - **get_single_planhat_user_by_id** — Get a specific user in Planhat using id. Returns fields including _id, firstName, lastName, email, permissions, roles, and accountAccess. - **create_a_planhat_user** — Create a new user in Planhat. Requires nickName, email, firstName, and lastName in the payload. Returns user details including firstName, lastName, notification preferences, and visibility flags. - **update_a_planhat_user_by_id** — Update a user in Planhat using id. The response returns fields such as _id, firstName, lastName, email, nickName, roles, and createDate showing the updated user details. - **delete_a_planhat_user_by_id** — Delete a specific user in Planhat using id. Requires the id parameter in the URL. Returns an empty JSON object upon successful deletion. - **list_all_planhat_conversations** — List conversations in Planhat. Returns fields such as date, subject, snippet, companyId, companyName, userIds, and endusers for each conversation. - **get_single_planhat_conversation_by_id** — Get a specific conversation in Planhat using id. Returns key fields such as type, subject, snippet, date, companyName, users, and endusers that describe the conversation content and participants. - **create_a_planhat_conversation** — Create a new conversation in Planhat. Requires companyId. Returns conversation details including id, subject, description, date, companyName, users, and endusers. - **update_a_planhat_conversation_by_id** — Update a specific conversation in Planhat. Requires id. Returns fields such as _id, subject, description, users, endusers, companyId, companyName, date, and createDate with updated conversation details. - **delete_a_planhat_conversation_by_id** — Delete a specific conversation in Planhat. Requires id. Returns conversation details including starred, pinned, isOpen, companyId, subject, description, users, and endusers fields before deletion. - **list_all_planhat_custom_fields** — Get a list of custom fields in Planhat. Returns fields such as _id, name, type, parent, and visibility properties including isFeatured, isHidden, and isLocked. - **get_single_planhat_custom_field_by_id** — Get a specific custom field in Planhat by id. Requires id. Returns _id, isFeatured, listValues, parent, type, isHidden, and name fields with details about the custom field configuration. - **create_a_planhat_custom_field** — Create a custom field in Planhat. Requires name, parent, and type. Returns fields such as _id (unique identifier), name, parent, type, and display flags (isFeatured, isHidden, isLocked) that describe the created custom field. - **update_a_planhat_custom_field_by_id** — Update a specific custom-field in Planhat. Requires id. Returns fields such as _id, isFeatured, isHidden, isShared, parent, type, and name indicating the updated field configuration. - **delete_a_planhat_custom_field_by_id** — Delete a specific custom field in Planhat using id. Returns fields n, ok, and deletedCount in the response indicating the deletion result. - **list_all_planhat_assets** — List assets in Planhat. Returns an array of assets with fields _id, companyId, and name in the response. - **get_single_planhat_asset_by_id** — Get a specific asset in Planhat by id. The response includes fields such as _id (unique identifier), companyId (associated company), companyName (company name), name (asset name), custom (custom fields), externalId (external reference), and usage (usage metrics). - **create_a_planhat_asset** — Create a new asset in Planhat. Requires name and companyId. Returns the created asset with fields such as _id, name, companyId, externalId, sourceId, custom fields, and companyName in the response. - **update_a_planhat_asset_by_id** — Update an asset in Planhat using the required id parameter. Returns _id, name, companyId, externalId, companyName, __v, and sourceId fields in the response. - **delete_a_planhat_asset_by_id** — Delete a specific asset in Planhat. Requires id. Returns n, ok, and deletedCount fields indicating the number of deleted records and operation success. - **list_all_planhat_churn** — List churn records in Planhat. Returns fields such as _id, licenseId, companyId, companyName, churnDate, products, currency, and value for each record. - **get_single_planhat_churn_by_id** — Get a specific churn record in Planhat using id. Requires id in the path. Returns _id, licenseId, companyId, companyName, churnDate, products, currency, value, and reasons. - **create_a_planhat_churn** — Create a churn record in Planhat. Requires companyId and isChurn. Returns fields such as _id (record identifier), churnDate (date of churn), reasons (list of churn reasons), value (monetary impact), currency, comment, companyId, and companyName. - **update_a_planhat_churn_by_id** — Update a specific churn record in Planhat using id. The response returns fields such as _id, snoozed, products, reasons, churnDate, value, currency, comment, companyId, and companyName. - **delete_a_planhat_churn_by_id** — Delete a specific churn record in Planhat. Requires id. Returns fields n, ok, and deletedCount indicating the number of records removed, operation success, and delete count. - **list_all_planhat_nps** — List NPS records in Planhat. Returns fields such as _id, npsId, email, npsDate, nps score, npsComment, scoreType, and company identifiers (cId, campaignId) representing survey responses and their metadata. - **get_single_planhat_np_by_id** — Get a specific NPS in Planhat by id. Returns _id, npsId, email, npsDate, nps, scoreType, cId, campaignId, source, and sourceId fields to identify and track the NPS response. - **create_a_planhat_np** — Create an NPS record in Planhat. Requires email and score. Returns _id, email, score, euId, cId, scoreType, dateSent, dateAnswered, and __v fields in the response. - **update_a_planhat_np_by_id** — Update an NPS record in Planhat by id. Requires id. Returns fields such as _id, campaignId, email, score, euId, cId, scoreType, dateSent, dateAnswered, and comment for the updated record. - **delete_a_planhat_np_by_id** — Delete an NPS record in Planhat by specifying id in the request URL. Returns n (number of matched records), ok (operation status), and deletedCount (number of deleted records) in the response. - **list_all_planhat_objective** — List objectives in Planhat. Returns an array of objectives with fields such as _id (objective identifier), companyId (associated company), name (objective name), and health (status indicator). - **get_single_planhat_objective_by_id** — Get a specific objective in Planhat by id. Requires id. Returns key fields such as _id, companyId, companyName, name, health, externalId, and custom metrics data. - **create_a_planhat_objective** — Create a new objective in Planhat. Requires name and companyId (can reference company externalId or sourceId). Returns fields including _id, name, health, companyId, externalId, sourceId, custom, and companyName. - **update_a_planhat_objective_by_id** — Update an objective in Planhat using id. The response returns fields such as _id, name, health, companyId, externalId, companyName, and sourceId, representing the updated objective details. - **delete_a_planhat_objective_by_id** — Delete an objective in Planhat using the required id. Returns n (number of matched documents), ok (operation success flag), and deletedCount (number of deleted objectives). - **list_all_planhat_sales** — List sales in Planhat. Returns an array of sales objects including _id, product, value, and companyId fields. - **get_single_planhat_sale_by_id** — Get sale by id in Planhat. Requires id. Returns value, product, _currency, salesDate, companyId, and companyName fields in the response. - **create_a_planhat_sale** — Create a sale in Planhat. Requires companyId. Returns id, value, product, _currency, salesDate, companyId, and companyName in the response. - **update_a_planhat_sale_by_id** — Update a specific sale in Planhat using id. The response returns fields such as _id, value, product, _currency, salesDate, companyId, and companyName. Requires id in the request URL. - **delete_a_planhat_sale_by_id** — Delete a specific sale in Planhat. Requires id. Returns n, ok, and deletedCount fields indicating the number of records deleted and operation success. - **list_all_planhat_time_entries** — List time-entries in Planhat. Returns an array of time entries where each entry includes fields _id (unique identifier), hours (number of hours logged), and date (entry date). - **get_single_planhat_time_entry_by_id** — Get a specific time entry in Planhat by id. Requires id. Returns fields such as timesheetStatus (status of the entry), assignedModel (assigned entity type), hours (worked hours), date (entry date), and description (work details). - **create_a_planhat_time_entry** — Create a new time entry in Planhat. Requires date and hours. Hours must be positive, between 0.1 and 24, and can be a decimal. Returns timesheetStatus, _id, hours, date, description, totalBilled, totalCost, createdAt, and updatedAt. - **update_a_planhat_time_entry_by_id** — Update a specific time entry in Planhat using id. Returns fields such as _id, timesheetStatus, assignedModel, hours, date, description, totalBilled, totalCost, createdAt, and updatedAt. - **delete_a_planhat_time_entry_by_id** — Delete a specific time entry in Planhat using the required id parameter. Returns n (number of operations), ok (operation status), and deletedCount (number of deleted documents) in the response. - **list_all_planhat_timesheet** — List timesheets in Planhat. Returns a list of timesheets with fields _id, dateFrom, and dateTo in the response. - **get_single_planhat_timesheet_by_id** — Get a specific timesheet in Planhat by id. Requires id. Returns timeEntries (list of entry IDs), status (submission state), assignedModel and assignedId (owner details), dateFrom and dateTo (date range), and timestamps for tracking creation and updates. - **create_a_planhat_timesheet** — Create a new timesheet in Planhat. The timesheet is created with status 'submitted'. Returns fields such as timeEntries, status, assignedModel, _id, assignedId, dateFrom, dateTo, createdAt, and updatedAt. - **update_a_planhat_timesheet_by_id** — Update a specific timesheet in Planhat using id. Returns _id, timeEntries, status, assignedModel, assignedId, dateFrom, dateTo, createdAt, updatedAt, approvedBy, and dateOfApproval in the response. - **delete_a_planhat_timesheet_by_id** — Delete a specific timesheet in Planhat. Requires id. Returns n (matched records), ok (operation status), and deletedCount (number of records deleted) in the response. ## How it works 1. **Link your customer's Planhat account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Planhat.** The Proxy API is a 1-to-1 mapping of the Planhat API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Sync subscription and billing data into Planhat for real-time revenue visibility** — Billing and subscription management platforms can automatically create and update Licenses, Invoices, Sales, and Churn records in Planhat so CSMs see live MRR, renewal dates, and churn events without leaving their workspace. - **Push NPS and survey responses directly into Planhat health scores** — Customer feedback and survey tools can write NPS scores, comments, and respondent details into Planhat's NPS object immediately after survey completion, driving automated health score adjustments and CSM follow-up tasks. - **Keep onboarding projects and tasks in sync between implementation tools and Planhat** — Client onboarding and project management apps can create and update Projects, Tasks, and Time Entries in Planhat so VPs of Customer Success have accurate time-to-value metrics and implementation progress without manual data entry. - **Surface support ticket context inside Planhat for QBR preparation** — Helpdesk and ticketing platforms can sync open tickets and issues into Planhat, giving CSMs a complete picture of account health and unresolved escalations when preparing for customer reviews. - **Enrich Planhat company and contact records with product usage data** — Product analytics and engagement platforms can update Planhat Companies and Endusers with usage metrics and activity signals, enabling CSMs to identify expansion opportunities and at-risk accounts from a single pane of glass. ## What you can build - **Automated license and renewal sync** — Automatically create and update Planhat Licenses with renewal dates, MRR values, and product details whenever a subscription changes in your platform. - **Real-time NPS score ingestion** — Push survey scores and verbatim feedback into Planhat's NPS object as soon as a respondent submits, triggering downstream health score recalculations. - **Bidirectional project and task tracking** — Sync onboarding milestones and task statuses between your project management tool and Planhat Projects and Tasks, including time entries for billable hour tracking. - **Churn event logging from cancellation flows** — Automatically create Churn records in Planhat with reason codes and lost revenue values when a customer initiates cancellation in your product. - **Two-way ticket and issue sync via Unified Ticketing API** — Map your helpdesk tickets to Planhat Tickets using Truto's Unified Ticketing API, keeping status, priority, and assignment in sync across both systems. - **Custom field mapping for flexible data models** — Read and create Planhat Custom Fields programmatically to ensure your integration adapts to each customer's unique Planhat configuration without hardcoding field names. ## FAQs ### What authentication method does the Planhat integration use? Planhat uses a tenant-level API token (Bearer token) for authentication. Truto handles token storage and injection so your end users simply provide their Planhat API key during the connection flow. ### Which Planhat objects are available through Truto's Unified APIs? Truto maps Planhat to two Unified APIs. The Unified CRM API covers Accounts (Companies), Contacts (Endusers), Opportunities, Projects, Tasks, Notes, Users, and Fields. The Unified Ticketing API covers Tickets, Accounts, Collections, Users, Fields, and Workspaces. All other Planhat-specific objects like Licenses, Invoices, NPS, Churn, Sales, Time Entries, Conversations, Assets, Objectives, Campaigns, Issues, and Timesheets are accessible via dedicated native proxy endpoints. ### Can I read and write custom fields on Planhat objects? Yes. Truto exposes dedicated endpoints to list, get, create, update, and delete Planhat Custom Fields. You can programmatically discover your end user's custom field schema and include custom field values when reading or writing any supported object. ### Does Truto handle pagination and rate limiting for Planhat API calls? Yes. Truto automatically manages cursor-based pagination across list endpoints and handles Planhat's rate limits with appropriate retry logic, so you don't need to implement these yourself. ### What CRUD operations are supported for Planhat objects? Most Planhat objects support full CRUD — list all, get by ID, create, update, and delete. A few exceptions exist: Tickets support list and delete but not individual get, create, or update through the current tool set. Always check the specific endpoint availability for your target object. ### Can I sync financial data like MRR, invoices, and churn records? Yes. Truto provides native endpoints for Licenses (with MRR and renewal data), Invoices, Sales, and Churn objects — all with full create, read, update, and delete support. This lets you build complete revenue lifecycle integrations into Planhat.