NAV
shell

Introduction

Welcome to the Planhat API! It will help you interact with Planhat whenever you need something not covered by our standard integration.

The API has a few “open” end point that can be used to push data without the need to authenticate. This is ideal if all you need is to send some server side metrics, user activities, call logs etc. If you need more that that your API keys will give you access to the full API which will let you do almost anything related to you data in Planhat.

There is a default limit of approximately 200 API calls / minute. Should you send more requests you’ll receive a “429 Too many requests” response. The limit of 200 calls is reset every 60-120 seconds, and each response includes information about your limit and how many calls you have left until next reset.

X-Rate-Limit-Limit: 200 X-Rate-Limit-Remaining: 192

If you need more capacity let us know.

In addition to the API, you can upload data in xlsx-format in Planhat. We have prepared a couple of template for this, and you can read more about it Here.

Authentication

# For and-point that require authentication, simply pass the correct header with each request
curl https://api.planhat.com/myprofile
  -H "Authorization: Bearer [PERSONAL_ACCESS_TOKEN]"

Replace [PERSONAL_ACCESS_TOKEN] with your API key.

Most end-points require authentication by a Personal Access Token, managed from the Settings section in Planhat. Personal Access Tokens are static tokens created by you from within the App. Once a token is created, it will last forever. To disable access to a token, simply remove it.

Access tokens are personal, meaning that whatever automatic operation you perform with this token, will appear as if the user in question did it. Consider creating a separate API user and generate tokens for that user to keep things separated.

The Token should be placed in the Authorization header in ONE of the following ways:

Authorization: Bearer [PERSONAL_ACCESS_TOKEN]

OR

Authorization: Basic [base64encode(PERSONAL_ACCESS_TOKEN:)]

Base URL

Depending on where you’re located, the base URL to access the Planhat API may differ.

https://api.planhat.com

OR

https://api-eu.planhat.com

So if you see a resource end-point like this one:

POST: /analytics/[YOUR_TENANT_ID]

It implies the full URL will be either

https://api.planhat.com/analytics/[YOUR_TENANT_ID]

or

https://api-eu.planhat.com/analytics/[YOUR_TENANT_ID]

User Tracking

Keeping track of your end-user activity is an important part of the Customer Success effort. Getting started involves only two steps.

  1. Decide a few events (user actions) that you want to track.
  2. Decide how you want to get that information from your users to Planhat.

What events to track

The most obvious events are probably logins and page-views. Logins tend to be fairly inaccurate since it depends a lot on user behavior, some people login and logout a lot, others keep their sessions open. Page views is likely a better metric. Even though page views have relatively weak correlation with the value created, it does give you a general sense of activity level, and it’s great to understand when a given user/customer was last active.

In addition to page views you can probably find even more meaningful metrics such as “did an advanced search”, “created a campaign”, “added a team-member” etc. The exact metrics will obviously depend on the service you provide but 2-3 such events should be more than enough to get started. Add a weight if you want to indicate that some actions are more important/valuable than others.

How to track

There are 3 different ways of getting your end-user activity into Planhat.

  1. API (real time)
  2. Planhat Tracking Script
  3. Segment
  4. API Bulk
  5. API Stream

1. API (real time)

# With the open end-point no auth required
curl -X POST \
-H "Content-Type: application/json" \
-d '{"email": "ariana.wright_0@daimler.com", "action": "Logged in", "info": {"index": 20, "theme": "Blue"}, "date": "2016-10-13T08:00:00.000Z"}' \
https://api.planhat.com/analytics/[YOUR_TENANT_ID]

Remember to replace the tenant id above with your own.

User activity relevant for your Customer Success strategies will typically involve a call to your servers. Once the activity/event is captured you can simply forward it from your servers to Planhat’s activity end-point:

POST: /analytics/[YOUR_TENANT_ID]

Property Description
name* Full name of the contact/user.
email* The contact’s id (user_id) in your system (required if externalId not specified)
externalId* The contact’s id (user_id) in your system (required if email not specified)
companyExternalId Typically the account/customer id in your system, the same id have to be present as externlId in Planhat.This is required to automatically add new end-users to the correct customer profile in Planhat. If left out, a Customer Success Rep will manually have to assign new end-users to the appropriate customer, or Planhat will make a qualified guess when certain enough it will be correct.
weight optional parameter in case you want to give more RELATIVE importance to certain events, otherwise ignore or set to 1 which is the default.
date Pass any valid JavaScript date string to specify the date of the event. In none is provided we will use the time the request was received.
action Parameter describing the user activity. Typically on the form Action + Object, for example “Sent Invoice”,but it could also be just “Login” or whatever describes the activity event. This parameter is optional, but highly recommended and required if you want the appear in the event stream.
info An optional, valid JSON object where you can add additional information related to the event. If the user activity was “purchased a gift card” then it might make sense to add info about the price, or product category.

2. Planhat Tracking Script

Your second option is adding a a small tracking script that we provide to your application Like any tracking script it’s a tiny snippet (< 1 kb) you place just before the closing tag. The snippet will asynchronously load the tracking script to send data directly from your users to Planhat. Just like Google Analytics or any other tracking script it won’t slow down you app or have any other noticeable impact on your users.

<script type="text/javascript"> var plantrack=plantrack||[];!function(){for(var t=["init","identify","track"], a=function(t){return function(){plantrack.push([t].concat(Array.prototype.slice.call(arguments,0)))}}, n=0;n<t.length;n++)plantrack[t[n]]=a(t[n])}(),plantrack.load=function(t,a){plantrack._endpoint=t,a&&plantrack.init(a); var n=document.createElement("script");n.type="text/javascript",n.async=!0, n.src="https://app.planhat.com/analytics/plantrack.min.js"; var r=document.getElementsByTagName("script")[0];r.parentNode.insertBefore(n,r)}; plantrack.load("https://api.planhat.com/analytics/[YOUR_TENANT_TOKEN]"); </script>

Then in your application, identify users as they login. This information is saved in a cookie (“_plantrack”) and used to identify the user in subsequent requests.

plantrack.identify(USER_ID, { email: USER_EMAIL, name: USER_NAME, companyId: CUSTOMER_ID });

Property Description
USER_ID The User Id in your database, or some other relevant id. Highly recommended and required if no USER_EMAIL is provided.
USER_EMAIL The user’s email, highly recommended and required if no USER_ID is provided.
USER_NAME The full name of this contact / user. If not provided we’ll try to use the email instead.
CUSTOMER_ID The customer id (account id) added in Planhat as “externalId”. Typically this would be the account-id in your own database. If you provide this id then Planhat can automatically map new (or “duplicate”) users to the correct customer profile.

After that, when the event you would like to track happens simply call plantrack.track(ACTION, [EXTRA_INFO]) from your app, for example:

plantrack.track("created a new project", {"weight": 7});

User information stored in the cookie (most importantly USER_ID) will automatically be added to all tracking calls.

Property Description
ACTION Description of the event. Examples could be “Added a team Member”, “Downloaded a Report”.

If you can make the actions somewhat specific it’s typically valuable. For example the action “Viewed a Page” could be further specified like “Viewed Settings Page”, or “Viewed Page ‘path/to/page’” EXTRA_INFO / WEIGHT | Most likely the actions your end-users take in your service are not equally important. Generating a report, adding a comment, creating a project etc perhaps means more than a simple page view. To reflect this a parameter “weight” can optionally be added to each tracking call as a way to indicate the relative importance of different actions. Since it’s relative, the absolute value (baseline) doesn’t matter. But to make it readable in Planhat a guideline is to have an average user accumulate weights of 100 or less over a month.

3. Segment

Sample post to test the end-point without the need to pass through Segment. Note the intentional colon (:) after your access token.

curl -X POST \
--user "[YOUR_TENANT_TOKEN]:"
-H "Content-Type: application/json" \
-d '{"type": "identify", "traits": {"name":  "Peter Gibbons", "email": "peter@initech.com", "companyId": "ABCDE"}}' \
https://api.planhat.com/dock/segment

As a third option, Segment can be used to send User Events (user tracking data) to Planhat. When we receive an event from Segment, we use the “user id” and/or email to to know which Planhat user the event refers to. The events are then displayed in Planhat both on user and company level. When presented in text form, we display it as [user name] + [event]. Preferably use event names on the form “verb + noun”. For example “downloaded a report” is a better event name then “report_dowloaded”.

Note that Segment is a service with it’s own license cost.

Expected data formats

{
  "type": "identify",
  "user_id": "12345",
  "traits" : {
    "name": "Peter Gibbons",
    "email":"peter@initech.com",
    "companyId": "ABCDE"
  }
}
{
  "type": "track",
  "user_id": "12345",
  "event": "downloaded a report",
  "properties" : {}
}

Creating Users Automatically

If we receive a call (Identify or Track) for a user that doesn’t yet exist in Planhat, and the request contains a customer id, then Planhat will automatically create a new user for you. This is highly recommended unless you create users in Planhat automatically through the API. If you’re providing an email address it is also likely that Planhat will be able to map a new end user to the correct customer account with sufficient accuracy to avoid manual confirmation, however most Segment set-ups rely not on email but in user id.

Ignored Events

Events will be completely ignored when any of the following conditions are met

  1. Request is not of type “Identify” or “Track”
  2. Both User Id and Email are missing

Un Assigned Users

If we receive a call (Identify or Track) for a user that doesn’t yet exist in Planhat, and the request does NOT contain information about which customer it relates to, and we have no other way to relate the user to a customer with reasonable confidence, then it will be discarded but added a report in Planhat to help you identify potential issues with the integration. Typically this may happen when users that loggedin (with a persistant session) before the integration was activated. Events from these users will end up in the log, and eventually as the user gets logged out and login again it’ll start working as expected.

4. API Bulk

# With the open end-point no auth required
curl -X POST \
-H "Content-Type: application/json" \
-d '[{"name": "Ariana Wright" "email": "ariana.wright@daimlor.com", "cId": "abc123", ""action": "Logged in", "date": "2016-10-13T08:00:00.000Z", "weight": 1, "count": 1}]' \
https://api.planhat.com/analytics/bulk/[YOUR_TENANT_ID]

Remember to replace the tenant id above with your own.

The body contains an array of events. There is an upper limit on the body size of 10 Mb for each post, which typically corresponds to about 50,000 items. If you need more that that or if your data is on a csv format, the streaming option (see next section) is a better option.

POST: /analytics/bulk/[YOUR_TENANT_ID]

Property Description
name Full name of the contact/user.
email* The contact’s id (user_id) in your system (required if externalId not specified)
id* The contact’s id (user_id) in your system (required if email not specified)
cId Typically the account/customer id in your system, the same id have to be present as externlId in Planhat.This is required to automatically add new end-users to the correct customer profile in Planhat. If left out, a Customer Success Rep will manually have to assign new end-users to the appropriate customer, or Planhat will make a qualified guess when certain enough it will be correct.
weight Weight. optional parameter in case you want to give more RELATIVE importance to certain events, otherwise ignore or set to 1 which is the default.
date Date. Pass any valid JavaScript date string to specify the date of the event. In none is provided we will use the time the request was received.
action Action. Parameter describing the user activity. Typically on the form Action + Object, for example “Sent Invoice”,but it could also be just “Login” or whatever describes the activity event. This parameter is optional, but highly recommended and required if you want the appear in the event stream.
count Indicate if the event happened multiple times, for example if the import cover past 24 hours and a given user logged in twice during this period, you could send it as one row and instead set the count to 2, of course they’d get the exact same date, but mostly this is not an issue. Defaults to one (1).

5. API Stream

// Node Example of streaing a csv file to Planhat
var fs = require('fs');
var request = require('request');
var YOUR_TENANT_ID = 'fb08c97b-41f5-4a22-8888-579a3ce223ae';
var endPoint = 'https://api.planhat.com/analytics/stream/csv/'+YOUR_TENANT_ID;

fs.createReadStream('sampleData.csv').pipe(request.put(endPoint));

PUT: /analytics/stream/csv/[YOUR_TENANT_ID]

The csv file should have the following header: cId, id, name, email, weight, action, date, count

Property Description
name Full name of the contact/user.
email* The contact’s id (user_id) in your system (required if externalId not specified)
id* The contact’s id (user_id) in your system (required if email not specified)
cId Typically the account/customer id in your system, the same id have to be present as externlId in Planhat.This is required to automatically add new end-users to the correct customer profile in Planhat. If left out, a Customer Success Rep will manually have to assign new end-users to the appropriate customer, or Planhat will make a qualified guess when certain enough it will be correct.
weight Weight. optional parameter in case you want to give more RELATIVE importance to certain events, otherwise ignore or set to 1 which is the default.
date Date. Pass any valid JavaScript date string to specify the date of the event. In none is provided we will use the time the request was received.
action Action. Parameter describing the user activity. Typically on the form Action + Object, for example “Sent Invoice”,but it could also be just “Login” or whatever describes the activity event. This parameter is optional, but highly recommended and required if you want the appear in the event stream.
count Indicate if the event happened multiple times, for example if the import cover past 24 hours and a given user logged in twice during this period, you could send it as one row and instead set the count to 2, of course they’d get the exact same date, but mostly this is not an issue. Defaults to one (1).

Metrics

curl -X POST \
-H "Content-Type: application/json" \
-d '[{"dimensionId": "flightTime", "value": 1, "companyExternalId": "airbus"}, {"dimensionId": "debtRatio", "value": 5.2, "companyExternalId": "boing"}]' \
https://api.planhat.com/[YOUR_TENANT_TOKEN]/dimensiondata

While User Activity says a lot about user engagement, it doesn’t neccesarily reflect the value created. Dimension Data is a set of metrics to understand how well you customers are doing, and the value they get out of your service.

Depending on what metrics you pick you might either want to send it as it happens or once a day. Number of user logins for example. You could either send an post everytime a user logs in, or you could save logins at your end and once a day send the total count for the day to planhat. Typically the more granular data you send to planhat, the more options you’ll have to later crunch that data.

Note: The end point accepts either a single object or an array, which can be useful if you run a batch update with some intervall, or if you initially would like to load historical data.

POST: /[YOUR_TENANT_TOKEN]/dimensiondata

Property Description
dimensionId* Any string without spaces or special characters. If you’re sending “Share of Active Users” a good dimensionId might be “activeusershare”. It’s not displayed in Planhat but will be used when building Health Metrics in Planhat.
value* The raw (number) value you would like to set.
companyExternalId This is the company id in your systems. For this to work the profiles in Planhat will need to have this externalId set.
date Pass any valid JavaScript date string to specify the date of the event. In none is provided we will use the time the request was received.
assetExtId Most likely you should leave this out, let us know if you need details about how to work with multiple assets.

Companies

curl -X POST \
--user "[PERSONAL_ACCESS_TOKEN]"
-H "Content-Type: application/json" \
-d '{"name": "Google", "externalId": "12345abcd", "phase": "onboarding", "tags": ["Gold", "East Coast"], "custom": {"referenceOk": true}}' \
https://api.planhat.com/companies

Replace [PERSONAL_ACCESS_TOKEN] with your API key.

Companies, sometimes referred to as “Accounts”, are your customers. It also covers companies that previously were your customer and potentially new customers (prospects). Whatever the status of the company it’s the same object and end-point.

POST: /companies

GET: /companies/:id

PUT: /companies/:id

DELETE: /companies/:id

Properties

Property Description
name* Name of the Customer.
slug Provide a custom slug in case you plan on adding multiple customers with the exact same name. Could be our own customer id, or an increasing counter, anything as long as it’s unique. If your customer names are unique then you don’t have to provide this, Planhat will create one for you.
owner The the planhat user id of the Account Manager / Success Manager to whom this customer belongs. See section [Team (Planhat Users)] below for info about how to get the user ids.
coOwner A potential co-pilot, in case a single owner isn’t enough. See section [Team (Planhat Users)] below for info about how to get the user ids.
externalId The customer id in your own system (will help us match other data you send over such as user activities, custom metrics etc). Not strictly required but if you’ve read this far it’s most likely something you need.
phase Each customer can be assigned a lifecycle phase in Planhat. It’s a text string that should match the name of one of the phases in Planhat. If the name doesn’t match any of the phases in Planhat it will still save.
tags Array of strings to tag your customers. There is no separate end-point for tags so if you’re going to update some of the tags for a given customer you’d have to update the whole array.
custom A flexible object with custom data, one level. Add any custom data points on the form. Use short and human friendly names as keys. For example “Plan” or “Subscription Plan” is better than “SUBSCRIPTION_PLAN”, as this is how it will be displayed in Planhat. Date, Strings, Boolean, Number are allowed types.

Company lookup

When you need a lightweight list of all companies in Planhat to match against your own id’s etc. For each company profile in Planhat you’ll get back the Planhat Id, External Id, Source ID (eg Salesforce) as well as the name and slug. If you want the mapping for a specific company you can specify “externalId” or “sourceId”.

GET: /leancompanies?externalId=yourid123

Revenue - Monthly

If each of your customers only has one subscription plan at a time, and renewing monthly, then this is the easiest way to manage your subscription/license data through the API. A single end-point to handle new subscriptions, upgrades, downgrades and churn.

# You call also use the authenticated end point to create calls
curl -X PUT \
--user "[PERSONAL_ACCESS_TOKEN]"
-H "Content-Type: application/json" \
-d '{"action": "newMrr", "data": [{"cId": "customer24", "value": 200, "currency": "SEK", "date": "2017-03-02T14:00:00.000Z"}]}' \
https://api.planhat.com/licenses/actions

Replace [PERSONAL_ACCESS_TOKEN] with your API key.

PUT: /licenses/actions

Properties

Property Type Description
action* String You should set this value to: “newMrr”
data* String This must be an array of updates (even if it’s only one), each element containing the four properties below
data.element cId* String External id of the company.
data.element date* Date ISO date indication when the the new mrr takes effect (at the latest)
data.element currency* String 3 letter currency code, e.g, “EUR” or “USD”
data.element value* Number the new mrr value

Typically you’ll have some automated process to charge the subscription fee from your customer’s credit cards. So when a customer pays for the first time you send the value and the date when the subscription started, mostly it will be the current date.

From this point on you don’t need to make any updates to planhat unless there is a chance. Planhat will automatically renew the subscription for another month at the end of each period.

When there is an update, send the new mrr value and a date that either matches the exact start date of the period with the new value, or any other date within that period. For each of the updates received, Planhat will look for (and update) the first subscription period that has an end-date less than (but not equal to) the date provided. When the value of a subscription period is updated, all the subsequent periods (if any exist) will also be updated with the same value.

To cancel a subscription, send a value of 0, that will remove the first subscription that has an end-date less than (but not equal to) the date provided. The preceding subscription period will keep it’s value but get the status “lost”.

Revenue - Mixed

If you’re customers can have multiple (potentially) parallel licenses, and you need to manage notice periods, auto renewal Yes/No etc. Then you’ll likely need to handle each subscription period individually. A number of important metrics such as the customer’s MRR and lifecycle phase are calculated based on the license data.

POST: /companies/:companyId/licenses

GET: /companies/:companyId/licenses/:id

PUT: /companies/:companyId/licenses/:id

DELETE: /companies/:companyId/licenses/:id

Properties

Property Type Description
externalId String License id in your system, in SalesForce or in some other external system you’re using to manage you licenses.
product String Name of the license product. Not required but highly recommended. Even if you only have one product we suggest adding it as “License Fee” or “Subscription”.
_currency* String The currency code, for example “USD”. There is a “soft” mapping to the id’s in your list of currencies. Technically we accept any string but we recommend using standard currency codes as Ids. Since the mapping is soft you can add licenses with a currency code not yet available in your list fo currencies.
fromDate* Date Start of the license period.
toDate Date End of the license period
fixedPeriod Boolean Boolean to indicate if this is an ongoing license (no defined end date) or license with a fixed term. Non fixed-term licenses require an mrr value specified, whereas fixed-term licenses specify the value over the whole period.
mrr* Number The monthly license value (required if fixedPeriod is false)
value* Number The total license value for the whole subscription period, must be positive (required if fixedPeriod is true and no mrr value)
renewalStatus String Can take one of the following values: ‘ongoing’, 'renewed’, 'lost’
autoRenews Boolean If set to true Planhat can automatically renew the subscription for you once the notice period is passed.
renewalPeriod Number Defines the length of the next license period if the subscription should be renewed. Defaults to 1, which would mean the license renews with a new 1-month period, regardless of the length of the current license period. If the renewalPeriod is not set, it will be assumed that the contract renews on the same period as previous. If the license isn’t set to autorenew the renewalPeriod will only serve as guidance for the manual input.
noticePeriod Number Number of days before subscription end date that the license would have to be canceled not to automatically renew. Only makes sense if autoRenews is set to true. Defaults to 0.
custom Object A flexible object with custom data, one level. Add any custom data points on the form. Use short and human friendly names as keys. For example “Plan” or “Subscription Plan” is better than “SUBSCRIPTION_PLAN”, as this is how it will be displayed in Planhat. Date, Strings, Boolean, Number are allowed types.

Contacts

These are people working at your customers, business contacts as well as your actual end users.

POST: /endusers

GET: /endusers/:id

PUT: /endusers/:id

DELETE: /endusers/:id

The GET request can be filtered to only list users at a specific company.

/endusers?c=55242d576b8275de65f567e8

Property Description
companyId* Planhat company id to decide which company profile a certain end-user belongs to.
companyName Name of the company the user belongs to. Only used to display which company a certain user belongs to in the aggregated contact/end-user lists. There is no validation that this name actually matches the company name of the companyId provided. To link a user to a certain company profile, only the companyId parameter will be considered.
createDate Date the contact was created, defaults to time of creation if not specified.
externalId The user id in your own database, or some other external system
name The user’s full name
position The role or position of this contact/user. e.g, “CFO”
phone You pick the telephone number format, any string will do.
email Email address of the user/contact
featured Boolean marker to single out contacts of special importance, typically set this to true if this is a user your sales team sometimes speak with, have the phone number to etc. Set to false if this is “just another user”.
tags Array of Strings to tag each contact

Calls

# With the open end-point no auth required
curl -X POST \
-H "Content-Type: application/json" \
-d '{"nr": "+4670123456", "userId": "max123", "agentId": "987qwe", "start": "2016-10-17T14:00:00.000Z", "end": "2016-10-17T14:02:00.000Z", "waiting": 10}' \
https://api.planhat.com/199627f7-0d65-52cd-89b9-45b5ff561bem/calls

Remember to replace the sample tenant id above 199627f7-0d65-52cd-89b9-45b5ff561bem with your own.

# You call also use the authenticated end point to create calls
curl -X POST \
--user "[PERSONAL_ACCESS_TOKEN]"
-H "Content-Type: application/json" \
-d '{"nr": "+4670123456", "userId": "max123", "agentId": "987qwe", "start": "2016-10-17T14:00:00.000Z", "end": "2016-10-17T14:02:00.000Z", "waiting": 10}' \
https://api.planhat.com/calls

Replace [PERSONAL_ACCESS_TOKEN] with your API key.

When you’re looking for a custom connection of your VOIP/phone solution to Planhat this is the end point.

POST: /calls

POST: /[YOUR_TENANT_ID]/calls (open, no auth header)

GET: /calls/:id

PUT: /calls/:id

DELETE: /calls/:id

Property Description
nr* Phone number of the contact you called, this can be used to match against customer and enduser in Planhat if the userId of the contact is not provided.
userId* Identify the user (contact) to whom you were talking by the userId in you'r own system (externaId)
phUserId* Identify the user (contact) to whom you were talking by the userId in in Planhat
agentId* The agent’s (your team member’s) user id in your on system, used to find a matching “agent” / team member
phAgentId* The agent’s (your team member’s) user id in Planhat, used to find a matching “agent” / team member
companyId The company Id in your own system. Can be used to identify the company if no contact is provided or can be found
phCompanyId The Planhat companyId. Can be used to identify the company if no contact is provided or can be found
agentName Name of the user who called, useful if the agent (user within your organization) is not a Planhat user
start When call started
end When the call ended
waiting In seconds, the waiting time before the “talk” started (waiting + talk_duration = end - start)
direction “in” for inbound or “out” for outbound
record link/uri to recording, if available

Preferably identify the customer contact by id (userId or phUserId), relying on the phone number is slightly less robust but will also work.

Tickets

This end point doesn’t have the normal GET, POST, PUT, DELETE. Create and update operations are combined into an “upsert” (PUT) request. The PUT body can contain either a single JSON object, or an array of objects (tickets)

sourceId is used to determine if this is an update or create operation.


curl -X PUT \
--user "[PERSONAL_ACCESS_TOKEN]"
-H "Content-Type: application/json" \
-d '{"source": "HomeGrownSupport", "sourceId": "123", "email": "max@customer.com", "createdAt": "2016-10-17T14:00:00.000Z", "updatedAt": "2016-10-17T14:02:00.000Z", "status": "resolved"}' \
https://api.planhat.com/tickets

Replace [PERSONAL_ACCESS_TOKEN] with your API key.

PUT: /tickets

GET: /tickets

DELETE: /tickets/:id

Property Description
source The name of the system this ticket originates from. Typically “Zendesk”, “Desk” etc, but since you’re reading these docs you may the tickets in some other tool.
sourceId* Required. Id of the ticket in the source system
email* Required. Email of the person who submitted the ticket. Items without email will be silently dropped.
companyExternalId The External Company Id, see the section “Company lookup” for a way to convert between different customer id’s. Not required but can help automatically create a new user if it doesn’t already exist, or if there is no external user related to the ticket but you still want it linked to a customer.
title If the ticket has a title or main subject.
description Description of the ticket
url Url to where more information can be found about this ticket.
tags Array of Strings
type the type of the ticket. Use as you like, but typically it could be: “bug”, “feature request”, “training” etc.
severity String describing the severity, no restrictions on the scale apart from that.
product Name of the product to which the ticket relates
timeSpent Time spend on this ticket, measured in number of minutes, can be a decimal.
createdAt Date
updatedAt Date
status String, you pick any status options you like. Typically “new”, “penidng”, “open”, “resolved”, “closed” or something similar.

NPS

# You call also use the authenticated end point to create calls
curl -X PUT \
--user "[PERSONAL_ACCESS_TOKEN]"
-H "Content-Type: application/json" \
-d '{"email": "john.smith@gmail.com", "score": 9, "comment": "Excellent UX", "dateSent": "2017-06-07T04:36:44Z", "dateAnswered": "2017-06-08T15:25:44Z", "source": "custom-nps.com", "sourceId": "4651"}' \
https://api.planhat.com/nps

Replace [PERSONAL_ACCESS_TOKEN] with your API key.

A contact in Planhat can be linked to multiple NPS survey responses, but only the last one will be used to get a score on company level.

GET: /nps

PUT: /nps

DELETE: /nps/:id

Properties

Property Type Description
email* String Email of the contact that has been surveyed
score* Number Feedback score that the user submit in his/her survey (0-10)
comment Sting The comment when the user gives an score in survey
dateSent Date ISO date when the survey was sent
dateAnswered Date ISO date when the survey was answered
source String The name of the system that NPS scores come from. For example: “custom-nps.com”.
sourceId String The id of the NPS score (response) in your system. This id is used as a matching key for update if already there’s an score with this sourceId

Team

If you would like to add the owner property while creating new companies and you have the user’s email but not the planhat id, then this end-point will help:

GET: /users?email=yourcolleaguesname@yourcompany.com

Other end-points

There are plenty of end-points to do pretty much anything you’d like. Let us know what you need and will provide you with the relevant details.