Planhat API

https://www.planhat.com/developers/api
Admin
Planhat API is a developer-friendly REST API that enables programmatic interaction with Planhat's...
Tokens:14,829
Snippets:96
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Create User Activity via API

Source: https://www.planhat.com/developers/api/user-activities

This is an example of a POST request to create a user activity event via the API. Refer to the documentation for detailed field descriptions.

```json
{
  "externalId": "user-123",
  "timestamp": "2023-10-27T10:00:00Z",
  "activityType": "custom",
  "activityName": "Logged In",
  "companyExternalId": "company-123",
  "assetExtId": "asset-456",
  "projectExtId": "project-789",
  "value": 1
}
```

--------------------------------

### Get Users List

Source: https://www.planhat.com/developers/api/user

Retrieves a list of users, with options to filter, sort, and select specific fields.

```APIDOC
## GET /users

### Description
Retrieves a list of users. Supports filtering, sorting, and field selection via query parameters.

### Method
GET

### Endpoint
/users

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Limits the number of users returned. Default is 10000, max is 10000.
- **offset** (integer) - Optional - Specifies the starting index for the list.
- **sort** (string) - Optional - Sorts the list based on a property. Prefix with '-' for descending order (e.g., '-createdAt').
- **select** (string) - Optional - Specifies which properties to include in the response, separated by commas (e.g., 'firstName,email').

### Request Example
```bash
curl --location -g --request get 'https://api.planhat.com/users' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
```

### Response
#### Success Response (200)
- **_id** (string) - The user's unique identifier.
- **firstName** (string) - The user's first name.
- **lastName** (string) - The user's last name.
- **nickName** (string) - The user's nickname.
- **email** (string) - The user's email address.
- **externalId** (string) - The user's external identifier.
- **image** (object) - Information about the user's image.
- **isHidden** (boolean) - Indicates if the user is hidden.
- **removed** (boolean) - Indicates if the user is removed.
- **inactive** (boolean) - Indicates if the user is inactive.
- **managers** (array) - List of managers for the user.
- **teams** (array) - List of teams the user belongs to.
- **isExposedAsSenderOption** (boolean) - Indicates if the user is exposed as a sender option.
- **createdAt** (string) - The date the user was created.
- **updatedAt** (string) - The date the user was last updated.
- **tzOffset** (integer) - The user's timezone offset.

#### Response Example
```json
[
    {
        "_id": "564b063a508f068051ee82a5",
        "nickName": "Diego Checa",
        "email": "diego@planhat.com",
        "image": {
            "path": ""
        },
        "radarOneLine": false,
        "taskFilter": "",
        "compressedView": false,
        "isHidden": false,
        "createDate": "2016-02-11T18:07:49.173Z",
        "lastName": "",
        "firstName": "Diego",
        "__v": 13,
        "dailyDigest": true,
        "followerUpdate": true,
        "permissions": {
            "admin": true,
            "changeOwner": true,
            "onlyMyPortfolio": false,
            "developer": true
        },
        "revReportPeriodType": "past x days",
        "inAppNotifications": true,
        "playlistSection": "all",
        "lastDailyDigest": 18830,
        "accountAccess": "all accounts"
    }
]
```
```

--------------------------------

### Get List of Users - cURL

Source: https://www.planhat.com/developers/api/user

This cURL command fetches a list of users. You can use query parameters like 'limit', 'offset', 'sort', and 'select' to customize the results. The 'select' parameter allows you to specify which user fields to return.

```bash
curl --location -g --request get 'https://api.planhat.com/users' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
```

--------------------------------

### Get User by ID

Source: https://www.planhat.com/developers/api/user

Retrieves detailed information for a specific user using their unique ID.

```APIDOC
## GET /users/{id}

### Description
Retrieves detailed information for a specific user.

### Method
GET

### Endpoint
/users/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the user.

### Request Example
```bash
curl --location -g --request get 'https://api.planhat.com/users/564b063a508f068051ee82a5' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
```

### Response
#### Success Response (200)
- **_id** (string) - The user's unique identifier.
- **nickName** (string) - The user's nickname.
- **email** (string) - The user's email address.
- **image** (object) - Information about the user's image.
- **isHidden** (boolean) - Indicates if the user is hidden.
- **createDate** (string) - The date the user was created.
- **firstName** (string) - The user's first name.
- **lastName** (string) - The user's last name.
- **permissions** (object) - User permissions.
- **roles** (array) - List of roles assigned to the user.

#### Response Example
```json
{
    "_id": "564b063a508f068051ee82a5",
    "nickName": "Diego Checa",
    "email": "diego@planhat.com",
    "image": {
        "path": ""
    },
    "radarOneLine": false,
    "taskFilter": "",
    "compressedView": false,
    "isHidden": false,
    "createDate": "2016-02-11T18:07:49.173Z",
    "lastName": "",
    "firstName": "Diego",
    "__v": 13,
    "dailyDigest": true,
    "followerUpdate": true,
    "permissions": {
        "admin": true,
        "changeOwner": true,
        "onlyMyPortfolio": false,
        "developer": true
    },
    "revReportPeriodType": "past x days",
    "inAppNotifications": true,
    "playlistSection": "all",
    "lastDailyDigest": 18830,
    "accountAccess": "all accounts",
    "roles": [
        {
            "_id": "000000010000000000000000",
            "name": "CSM",
            "description": "Access to a few selected views and relevant accounts",
            "__v": 393
        },
        {
            "_id": "000000030000000000000000",
            "name": "Developer",
            "description": "Access to API keys, error pages etc",
            "__v": 4
        },
        {
            "_id": "000000000000000000000000",
            "name": "Administrator",
            "description": "Full access, including ability to edit users and settings",
            "__v": 55
        },
        {
            "_id": "000000020000000000000000",
            "name": "Manager",
            "description": "Access to the entire portfolio, and all functionality",
            "__v": 56
        }
    ],
    "msApi": {
        "accessEnabled": false,
        "syncEnabled": false,
        "syncInitial": false,
        "syncedLabels": []
    },
    "playLogDisabled": true,
    "poc": [
        "Agreement"
    ],
    "emailSignature": {
        "content": "<div>hello<br></div>",
        "enabled": false
    },
    "inactive": false,
    "removed": false,
    "tzOffset": -5,
    "intercomAdminId": "1123812",
    "custom": {},
    "defaultMeetingLength": 60,
    "isExposedAsSenderOption": false,
    "splitLayoutDisabled": false,
    "recentOpenSharedView": "56bccdf554d64d837d01be63",
    "invoicesSort": "-dueDate",
    "type": "user",
    "undefined": null,
    "googleApi": {
        "accessEnabled": false,
        "syncEnabled": false,
        "syncInitial": false,
        "syncedLabels": []
    },
    "googleCalendarApi": {
        "accessEnabled": false,
        "syncEnabled": false,
        "syncInitial": false,
        "syncedCalendars": [],
        "calendarToSave": {}
    },
    "msCalendarApi": {
        "accessEnabled": false,
        "syncEnabled": false,
        "syncInitial": false,
        "syncedCalendars": [],
        "calendarToSave": {}
    }
}
```
```

--------------------------------

### Get Objectives List

Source: https://www.planhat.com/developers/api/objective

Retrieves a list of objectives with options for filtering, limiting, sorting, and selecting fields.

```APIDOC
## Get Objectives List

### Description
Retrieves a list of objectives with options for filtering, limiting, sorting, and selecting fields.

### Method
GET

### Endpoint
/objectives

### Parameters
#### Query Parameters
- **companyId** (string) - Optional - Filter objectives by company ID.
- **limit** (integer) - Optional - Limit the number of results. Default is 100, max is 2000.
- **offset** (integer) - Optional - Specify the starting index for the list.
- **sort** (string) - Optional - Sort the results by a specific property. Prefix with "-" for descending order (e.g., "-name").
- **select** (string) - Optional - Specify which properties to include in the response, separated by commas (e.g., "_id,name,health,companyId").

### Request Example
```curl
curl --location -g --request GET 'https://api.planhat.com/objectives?limit=2&offset=0&sort=-name&select=_id,name,health,companyId' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'
```

### Response
#### Success Response (200)
Returns a list of objective objects, with fields determined by the `select` query parameter.

#### Response Example
(Example response would be a JSON array of objective objects, similar to the 'Get Objective by ID' response, but potentially with fewer fields based on the `select` parameter.)
```

--------------------------------

### Get Objective by ID

Source: https://www.planhat.com/developers/api/objective

Retrieves a specific objective by its _id. Can also use externalId or sourceId.

```APIDOC
## Get Objective by ID

### Description
Retrieves a specific objective by its _id. Can also use externalId or sourceId.

### Method
GET

### Endpoint
/objectives/{objectiveId}

### Parameters
#### Path Parameters
- **objectiveId** (string) - Required - The ID of the objective to retrieve. Can also be prefixed with "extid-" or "srcid-" to use external or source IDs.

### Request Example
```curl
curl --location -g --request GET 'https://api.planhat.com/objectives/5ffcce42ad67267f66741147' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'
```

### Response
#### Success Response (200)
- **_id** (string) - The unique identifier of the objective.
- **companyId** (string) - The ID of the company the objective belongs to.
- **companyName** (string) - The name of the associated company.
- **name** (string) - The name of the objective.
- **health** (integer) - The health score of the objective.
- **__v** (integer) - Version number.
- **custom** (object) - Custom fields associated with the objective.
- **externalId** (string) - An external identifier for the objective.
- **usage** (object) - Usage data related to the objective.

#### Response Example
```json
{
  "_id": "5ffcce42ad67267f66741147",
  "companyId": "56bccdf554d64d837d01be9d",
  "companyName": "Tenet",
  "name": "Gold objective",
  "health": 5,
  "__v": 0,
  "custom": {
  "Comments": "",
  "Main Product": [
  "Recipe Database"
  ],
  "Days in Phase": 0,
  "NRR30": 0,
  "t123": "undefined",
  "Logins": 0,
  "Overall Outlet Health": 4,
  "Kary FF": null
  },
  "externalId": "4467",
  "usage": {
  "6053b728fa96fa0262729a3d": 0,
  "6053ba62ca3eaf023a54d268": 0
  }
 }
```
```

--------------------------------

### Get User by ID

Source: https://www.planhat.com/developers/api/user

Retrieve a specific user's details by including their _id in the request URL. The user's externalId with a prefix can also be used for retrieval.

```bash
curl --location -g --request GET 'https://api.planhat.com/users/61031e2ad414d49dcdb61b22'
```

--------------------------------

### Get Objectives List - Planhat API

Source: https://www.planhat.com/developers/api/objective

Fetch a list of objectives with options to filter by companyId, limit results, set offset, sort by properties, and select specific fields.

```curl
curl --location -g --request GET 'https://api.planhat.com/objectives?limit=2&offset=0&sort=-name&select=_id,name,health,companyId' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'
```

--------------------------------

### Get Objective by ID - Planhat API

Source: https://www.planhat.com/developers/api/objective

Retrieve a specific objective using its _id, externalId, or sourceId. The _id is required in the URL, or use prefixes for externalId/sourceId.

```curl
curl --location -g --request GET 'https://api.planhat.com/objectives/5ffcce42ad67267f66741147' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}'
```

```json
{
  "_id": "5ffcce42ad67267f66741147",
  "companyId": "56bccdf554d64d837d01be9d",
  "companyName": "Tenet",
  "name": "Gold objective",
  "health": 5,
  "__v": 0,
  "custom": {
  "Comments": "",
  "Main Product": [
  "Recipe Database"
  ],
  "Days in Phase": 0,
  "NRR30": 0,
  "t123": "undefined",
  "Logins": 0,
  "Overall Outlet Health": 4,
  "Kary FF": null
  },
  "externalId": "4467",
  "usage": {
  "6053b728fa96fa0262729a3d": 0,
  "6053ba62ca3eaf023a54d268": 0
  }
 }
```

--------------------------------

### Get User by ID

Source: https://www.planhat.com/developers/api/user

Retrieves a specific user by their _id. It's also possible to retrieve a user using their externalId by adding a prefix.

```APIDOC
## Get User by ID

### Description
Retrieves a specific user by their _id. It's also possible to retrieve a user using their externalId by adding a prefix.

### Method
GET

### Endpoint
/users/{userId}

### Parameters
#### Path Parameters
- **userId** (string) - Required - The unique identifier or externalId (prefixed) of the user to retrieve.

### Response
#### Success Response (200)
- **_id** (string) - The unique identifier for the user.
- **email** (string) - The email address of the user.
- **nickName** (string) - The nickname of the user.
- **firstName** (string) - The first name of the user.
- **lastName** (string) - The last name of the user.
- **inactive** (boolean) - Indicates if the user is inactive.
- **roles** (array) - A list of role IDs assigned to the user.

#### Response Example
```json
{
    "_id": "61031e2ad414d49dcdb61b22",
    "skippedGettingStartedSteps": {
        "email": false,
        "linkedin": false,
        "avatar": false,
        "all": false,
        "team": false,
        "customers": false
    },
    "sharedNotificationsPrefs": {
        "enabled": [],
        "disabled": [],
        "disabledEvents": []
    },
    "image": {
        "path": ""
    },
    "firstName": "Bob",
    "lastName": "Marley",
    "isHidden": false,
    "removed": false,
    "inactive": true,
    "compressedView": false,
    "companyFilter": "",
    "taskFilter": "",
    "workflowFilter": "",
    "playLogDisabled": true,
    "radarOneLine": false,
    "expandedFolders": [],
    "usageReportColumnsEnabled": [],
    "companyUsersEnabledColumns": [],
    "revReportPeriodType": "past x days",
    "splitLayoutDisabled": false,
    "dailyDigest": true,
    "followerUpdate": true,
    "inAppNotifications": true,
    "lastVisitedCompanies": [],
    "lastVisitedEndusers": [],
    "roles": [
        "57e2b92ff795575a5b8c4659"
    ],
    "poc": [],
    "isExposedAsSenderOption": false,
    "defaultMeetingLength": 60,
    "collapsedFolders": [],
    "type": "user",
    "email": "bob@test.com",
    "nickName": "Bob",
    "createDate": "2021-07-29T21:31:22.042Z",
    "__v": 0
}
```
```

--------------------------------

### Get Specific User by ID - cURL

Source: https://www.planhat.com/developers/api/user

Use this cURL command to retrieve details for a specific user by their unique ID. Ensure your API token is correctly set in the Authorization header.

```bash
curl --location -g --request get 'https://api.planhat.com/users/564b063a508f068051ee82a5' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
```

--------------------------------

### Initialize Planhat Tracking Script

Source: https://www.planhat.com/developers/api/user-activities

Include this script in your application's HTML, just before the closing head tag, to load the Planhat tracking asynchronously. Replace {{tenantUUID}} with your actual Tenant UUID.

```html
<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://analytics.planhat.com/analytics/{{tenantUUID}}"); 
</script>
```

--------------------------------

### Create User

Source: https://www.planhat.com/developers/api/user

Creates a new user in Planhat. Requires email, firstName, lastName, and nickName in the payload.

```APIDOC
## Create User

### Description
Creates a new user in Planhat. Requires email, firstName, lastName, and nickName in the payload.

### Method
POST

### Endpoint
/users

### Parameters
#### Request Body
- **email** (string) - Required - The email address of the user.
- **firstName** (string) - Required - The first name of the user.
- **lastName** (string) - Required - The last name of the user.
- **nickName** (string) - Required - The nickname of the user.
- **roles** (array) - Optional - A list of role IDs for the user.

### Request Example
```json
{
    "email": "bob@test.com",
    "firstName": "Bob",
    "lastName": "Marley",
    "nickName": "Bob",
    "roles": [
        "57e2b92ff795575a5b8c4659"
    ]
}
```

### Response
#### Success Response (200)
- **_id** (string) - The unique identifier for the user.
- **email** (string) - The email address of the user.
- **nickName** (string) - The nickname of the user.
- **firstName** (string) - The first name of the user.
- **lastName** (string) - The last name of the user.
- **inactive** (boolean) - Indicates if the user is inactive.
- **roles** (array) - A list of role IDs assigned to the user.

#### Response Example
```json
{
    "skippedGettingStartedSteps": {
        "email": false,
        "linkedin": false,
        "avatar": false,
        "all": false,
        "team": false,
        "customers": false
    },
    "sharedNotificationsPrefs": {
        "enabled": [],
        "disabled": [],
        "disabledEvents": []
    },
    "image": {
        "path": ""
    },
    "firstName": "Bob",
    "lastName": "Marley",
    "isHidden": false,
    "removed": false,
    "inactive": true,
    "compressedView": false,
    "companyFilter": "",
    "taskFilter": "",
    "workflowFilter": "",
    "playLogDisabled": true,
    "radarOneLine": false,
    "expandedFolders": [],
    "usageReportColumnsEnabled": [],
    "companyUsersEnabledColumns": [],
    "revReportPeriodType": "past x days",
    "splitLayoutDisabled": false,
    "dailyDigest": true,
    "followerUpdate": true,
    "inAppNotifications": true,
    "lastVisitedCompanies": [],
    "lastVisitedEndusers": [],
    "roles": [
        "57e2b92ff795575a5b8c4659"
    ],
    "apiTokens": [],
    "poc": [],
    "isExposedAsSenderOption": false,
    "defaultMeetingLength": 60,
    "collapsedFolders": [],
    "type": "user",
    "_id": "61031e2ad414d49dcdb61b22",
    "email": "bob@test.com",
    "nickName": "Bob",
    "createDate": "2021-07-29T21:31:22.042Z",
    "__v": 0
}
```
```

--------------------------------

### Create a New User

Source: https://www.planhat.com/developers/api/user

Use this endpoint to create a new user in Planhat. The payload requires email, firstName, lastName, and nickName. Roles can also be specified.

```bash
curl --location -g --request POST 'https://api.planhat.com/users' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{ \
        "email": "bob@test.com", \
        "firstName": "Bob", \
        "lastName": "Marley", \
        "nickName": "Bob", \
        "roles": [ \
            "57e2b92ff795575a5b8c4659" \
        ] \
    }'
```

--------------------------------

### Basic Authentication with Token

Source: https://www.planhat.com/developers/api/authentication-limits

When using basic authentication, remember to include the colon after your token. This method is an alternative to Bearer authentication.

```http
Authorization: {{apiAccessToken}}:
```

--------------------------------

### Create Activity

Source: https://www.planhat.com/developers/api/user-activities

This endpoint allows you to create a user activity event in Planhat. You can send real-time activity data using this method.

```APIDOC
## POST /user-activities

### Description
Allows you to create a user activity event in Planhat in real-time.

### Method
POST

### Endpoint
https://analytics.planhat.com/user-activities

### Request Body
- **event** (string) - Required - The name of the event to track.
- **userId** (string) - Required - The external ID of the end-user.
- **timestamp** (string) - Required - The time the event occurred in ISO 8601 format.
- **properties** (object) - Optional - Additional properties for the event.
  - **propertyName** (any) - Description of the property.
```

--------------------------------

### Create Bulk User Activities

Source: https://www.planhat.com/developers/api/user-activities

This cURL command demonstrates how to send a batch of user activities to the bulk analytics endpoint. The payload is a JSON array of user activity objects. Note the limit of 300 for the 'count' property.

```bash
url --location -g --request POST 'https://analytics.planhat.com/analytics/bulk/{{tenantUUID}}' \
--header 'Content-Type: application/json' \
--data-raw '[ \
    { \
        "name": "Ivars Mucenieks", \
        "email": "ivars@planhat.com", \
        "cId": "abc123", \
        "action": "Logged in", \
        "weight": 1, \
        "count": 1 \
    }, \
    { \
        "name": "Ivars Mucenieks", \
        "email": "ivars@planhat.com", \
        "cId": "abc123", \
        "action": "Sent Invoice", \
        "weight": 1, \
        "count": 1 \
    } \
]



```

--------------------------------

### Bulk Upsert Users

Source: https://www.planhat.com/developers/api/user

Create or update multiple users in a single request. Required fields for creation include nickName, email, firstName, and lastName. For updates, specify _id, externalId, or email. The maximum request size is 5,000 items.

```bash
curl --location -g --request put 'https://api.planhat.com/users' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
        {
            "email": "rob@test.com",
            "firstName": "Robbert",
            "lastName": "Rob",
            "nickName": "Tyler",
            "roles": [
                "57e2b92ff795575a5b8c4659"
            ]
        },
        {
            "email": "liz@test.com",
            "firstName": "Liz",
            "lastName": "Elizabeth",
            "nickName": "Gates",
            "roles": [
                "5d35c292344cb854c0a5af28"
            ]
        }
    ]'
```

--------------------------------

### Create Objective

Source: https://www.planhat.com/developers/api/objective

Creates a new objective. Requires a name and companyId. Can reference company by externalId or sourceId.

```APIDOC
## Create Objective

### Description
Creates a new objective. Requires a name and companyId. Can reference company by externalId or sourceId.

### Method
POST

### Endpoint
/objectives

### Parameters
#### Request Body
- **name** (string) - Required - The name of the objective.
- **health** (integer) - Optional - The health score of the objective.
- **companyId** (string) - Required - The ID of the company the objective belongs to. Can be prefixed with "extid-" or "srcid-" to use external or source IDs.
- **externalId** (string) - Optional - An external identifier for the objective.
- **sourceId** (string) - Optional - A source identifier for the objective.
- **custom** (object) - Optional - A key-value object for custom fields.

### Request Example
```curl
curl --location -g --request POST 'https://api.planhat.com/objectives' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{ \
  "name": "Objective name", \
  "health": 5, \
  "companyId": "60df26bfa259250cba9cf816", \
  "externalId": 1234, \
  "sourceId": "sfc-1234", \
  "custom": { \
  "field": "custom field" \
  } \
 }'
```

### Response
#### Success Response (200)
- **_id** (string) - The unique identifier of the objective.
- **name** (string) - The name of the objective.
- **health** (integer) - The health score of the objective.
- **companyId** (string) - The ID of the company the objective belongs to.
- **externalId** (string) - An external identifier for the objective.
- **sourceId** (string) - A source identifier for the objective.
- **custom** (object) - Custom fields associated with the objective.
- **companyName** (string) - The name of the associated company.

#### Response Example
```json
{
  "_id": "60faeda853b8f717ebe36146",
  "name": "Objective name",
  "health": 5,
  "companyId": "60df26bfa259250cba9cf816",
  "externalId": "1234",
  "sourceId": "sfc-1234",
  "custom": {
  "field": "custom field"
  },
  "companyName": "Test Company"
 }
```
```

--------------------------------

### Create Objective - Planhat API

Source: https://www.planhat.com/developers/api/objective

Use this endpoint to create a new objective for a company. Requires a name and companyId. Company can be referenced by externalId or sourceId.

```curl
curl --location -g --request POST 'https://api.planhat.com/objectives' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '{ \
  "name": "Objective name", \
  "health": 5, \
  "companyId": "60df26bfa259250cba9cf816", \
  "externalId": 1234, \
  "sourceId": "sfc-1234", \
  "custom": { \
  "field": "custom field" \
  } \
 }'
```

```json
{
  "_id": "60faeda853b8f717ebe36146",
  "name": "Objective name",
  "health": 5,
  "companyId": "60df26bfa259250cba9cf816",
  "externalId": "1234",
  "sourceId": "sfc-1234",
  "custom": {
  "field": "custom field"
  },
  "companyName": "Test Company"
 }
```

--------------------------------

### Create Single User Activity

Source: https://www.planhat.com/developers/api/user-activities

Use this cURL command to send a POST request to the analytics endpoint for creating or updating a single user activity. Ensure the tenantUUID is correctly replaced.

```bash
curl --location -g --request POST 'https://analytics.planhat.com/analytics/{{tenantUUID}}' \
--header 'Content-Type: application/json' \
--data-raw '{ \
    "email": "ivars@planhat.com", \
    "action": "Logged in", \
    "externalId": "ojpsoi57pzn", \
    "companyExternalId": "Planhat-81ock9l81wl", \
    "weight": 1, \
    "info": { \
        "index": 20, \
        "theme": "Blue" \
    } \
}'
```

--------------------------------

### Track Event with Planhat Tracking Script

Source: https://www.planhat.com/developers/api/user-activities

Use this function to track a specific user action or event. User information stored in the cookie will be automatically included.

```javascript
plantrack.track("ACTION");
```

--------------------------------

### Track Event with Additional Information

Source: https://www.planhat.com/developers/api/user-activities

To include more details with a tracked event, use the 'info' property within the second argument, which should be a JSON object.

```javascript
plantrack.track("ACTION", {
  "info": {
    "planhatActionType": "custom",
    "customActionName": "Advanced Search",
    "value": 10
  }
});
```

--------------------------------

### General API Base URL

Source: https://www.planhat.com/developers/api/introduction

Use this base URL for general API requests to interact with Planhat data.

```text

```

--------------------------------

### Identify User with Planhat Tracking Script

Source: https://www.planhat.com/developers/api/user-activities

Call this function after the tracking script is loaded to identify a user. USER_ID should be the externalId of the EndUser. If only email is available, pass 'null' for the first argument and specify the email in EXTRA_INFO.

```javascript
plantrack.identify(USER_ID, {
  "email": "user@example.com",
  "name": "John Doe",
  "companyExternalId": "company-123",
  "assetExtId": "asset-456",
  "projectExtId": "project-789"
});
```

--------------------------------

### Bulk Upsert Users

Source: https://www.planhat.com/developers/api/user

Creates new users or updates existing users in bulk. Requires specific fields for creation and keyable fields for updates. Supports up to 5,000 items per request.

```APIDOC
## PUT /users

### Description
Creates new users or updates existing users in bulk. Requires specific fields for creation and keyable fields for updates. Supports up to 5,000 items per request.

### Method
PUT

### Endpoint
/users

### Parameters
#### Request Body
- **Array of User Objects** - Required - Each object can represent a user to be created or updated.
  - **nickName** (string) - Required for creation - The user's nickname.
  - **email** (string) - Required for creation - The user's email address. Also used as a keyable field for updates.
  - **firstName** (string) - Required for creation - The user's first name.
  - **lastName** (string) - Required for creation - The user's last name.
  - **_id** (string) - Optional - Used as a keyable field for updates.
  - **externalId** (string) - Optional - Used as a keyable field for updates.
  - **roles** (array of strings) - Optional - An array of role IDs to assign to the user.

### Request Example
```curl
curl --location -g --request put 'https://api.planhat.com/users' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[{"email": "rob@test.com", "firstName": "Robbert", "lastName": "Rob", "nickName": "Tyler", "roles": ["57e2b92ff795575a5b8c4659"]}, {"email": "liz@test.com", "firstName": "Liz", "lastName": "Elizabeth", "nickName": "Gates", "roles": ["5d35c292344cb854c0a5af28"]}]'
```

### Response
#### Success Response (200)
Returns an object detailing the results of the bulk upsert operation, including counts of created and updated users, and lists of keys for inserts and updates.

#### Response Example
```json
{
    "created": 2,
    "createdErrors": [],
    "insertsKeys": [
        {
            "_id": "61033193e41b0aa81c926c8b",
            "email": "rob@test.com"
        },
        {
            "_id": "61033193e41b0aa81c926c8c",
            "email": "liz@test.com"
        }
    ],
    "updated": 0,
    "updatedErrors": [],
    "updatesKeys": [],
    "nonupdates": 0,
    "modified": [],
    "upsertedIds": [
        "61033193e41b0aa81c926c8b",
        "61033193e41b0aa81c926c8c"
    ],
    "permissionErrors": []
}
```
```

--------------------------------

### Identify User Request

Source: https://www.planhat.com/developers/api/user-activities

Use this cURL command to send an identify request for a user, including their traits and associated company ID. Ensure you replace {{tenantUUID}} with your actual tenant UUID.

```curl
curl --location -g --request POST 'https://analytics.planhat.com/dock/segment' \
-u {{tenantUUID}} \
-k \
--header 'Content-Type: application/json' \
--data-raw '{
    "type": "identify",
    "traits": {
        "name": "Ivars Mucenieks",
        "email": "ivars@planhat.com",
        "companyId": "ABCDE"
    }
}'
```

--------------------------------

### Bulk Upsert Objectives using cURL

Source: https://www.planhat.com/developers/api/objective

This cURL command demonstrates how to create or update multiple objectives in a single request. You can identify objectives for update using _id, sourceId, or externalId. The payload supports custom fields and has a limit of 5,000 items per request.

```bash
curl --location -g --request PUT 'https://api.planhat.com/objectives' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{apiToken}}' \
 --data-raw '[ \
  { \
  "name": "Objective name", \
  "companyId": "60df26bfa259250cba9cf816", \
  "health": 4, \
  "externalId": 1234, \
  "sourceId": "sfc-1234", \
  "custom": { \
  "field": "custom field" \
  } \
  }, \
  { \
  "name": "Objective name 2", \
  "companyId": "60df26bfa259250cba9cf816", \
  "health": 5, \
  "externalId": 1235, \
  "sourceId": "sfc-1235", \
  "custom": { \
  "field": "custom field" \
  } \
  } \
 ]'
```

--------------------------------

### Identify User Response

Source: https://www.planhat.com/developers/api/user-activities

A successful identify request will return a '200 ok' status with an 'OK' response.

```http
200 ok
'OK'
```

--------------------------------

### Identify User

Source: https://www.planhat.com/developers/api/user-activities

This endpoint is used to identify a user and associate them with a company. If a user is not found and cannot be associated with a customer, they will be logged and potentially discarded until they log in again.

```APIDOC
## POST /dock/segment

### Description
Identifies a user and associates them with a company. Handles cases where the user or company association is not immediately clear.

### Method
POST

### Endpoint
https://analytics.planhat.com/dock/segment

### Parameters
#### Request Body
- **type** (string) - Required - The type of event, typically "identify".
- **traits** (object) - Required - User traits including name, email, and companyId.
  - **name** (string) - Optional - The name of the user.
  - **email** (string) - Optional - The email address of the user.
  - **companyId** (string) - Optional - The ID of the company the user belongs to.

### Request Example
```json
{
    "type": "identify",
    "traits": {
        "name": "Ivars Mucenieks",
        "email": "ivars@planhat.com",
        "companyId": "ABCDE"
    }
}
```

### Response
#### Success Response (200)
- **response** (string) - Indicates success, typically 'OK'.

#### Response Example
```
'OK'
```
```

--------------------------------

### Update User

Source: https://www.planhat.com/developers/api/user

Updates an existing user in Planhat. Requires the user's _id in the URL.

```APIDOC
## Update User

### Description
Updates an existing user in Planhat. Requires the user's _id in the URL. It's also possible to update using the user externalId by adding a prefix.

### Method
PUT

### Endpoint
/users/{userId}

### Parameters
#### Path Parameters
- **userId** (string) - Required - The unique identifier or externalId (prefixed) of the user to update.

#### Request Body
- **nickName** (string) - Optional - The updated nickname for the user.

### Request Example
```json
{
    "nickName": "Bob Marley"
}
```

### Response
#### Success Response (200)
- **_id** (string) - The unique identifier for the user.
- **nickName** (string) - The updated nickname of the user.

#### Response Example
```json
{
    "_id": "61031e2ad414d49dcdb61b22",
    "skippedGettingStartedSteps": {
        "email": false,
        "linkedin": false,
        "avatar": false,
        "all": false,
        "team": false,
        "customers": false
    },
    "sharedNotificationsPrefs": {
        "enabled": [],
        "disabled": [],
        "disabledEvents": []
    },
    "image": {
        "path": ""
    },
    "firstName": "Bob",
    "lastName": "Marley",
    "isHidden": false,
    "removed": false,
    "inactive": true,
    "compressedView": false,
    "companyFilter": "",
    "taskFilter": "",
    "workflowFilter": "",
    "playLogDisabled": true,
    "radarOneLine": false,
    "expandedFolders": [],
    "usageReportColumnsEnabled": [],
    "companyUsersEnabledColumns": [],
    "revReportPeriodType": "past x days",
    "splitLayoutDisabled": false,
    "dailyDigest": true,
    "followerUpdate": true,
    "inAppNotifications": true,
    "lastVisitedCompanies": [],
    "lastVisitedEndusers": [],
    "roles": [
        "57e2b92ff795575a5b8c4659"
    ],
    "poc": [],
    "isExposedAsSenderOption": false,
    "defaultMeetingLength": 60,
    "collapsedFolders": [],
    "type": "user",
    "email": "bob@test.com",
    "nickName": "Bob Marley",
    "createDate": "2021-07-29T21:31:22.042Z",
    "__v": 0
}
```
```

--------------------------------

### API Access Token Authentication

Source: https://www.planhat.com/developers/api/authentication-limits

Place your API Access Token in the Authorization header using Bearer authentication. Ensure the token is securely stored after generation.

```http
Authorization: Bearer {{apiAccessToken}}
```
Tokens:
Raw