# Vitally

> Manage Vitally customer success data including accounts, users, organizations, notes, tasks, conversations, projects, NPS responses, and custom objects.

Source: https://cotera.co/docs/reference/tools/individual-tools/vitally

---

**Authentication Type:** API Key (Basic Auth)
**Description:** Manage Vitally customer success data including accounts, users, organizations, notes, tasks, conversations, projects, NPS responses, and custom objects.

***

## Authentication

To authenticate, you'll need your Vitally API credentials:

1. Go to your Vitally workspace settings and navigate to the API section
2. Generate a new API token
3. Note your subdomain (e.g., `yourcompany` from `yourcompany.rest.vitally.io`)

You'll need to provide:

* **apiKey**: Your Vitally API token
* **subdomain**: Your Vitally subdomain (e.g., `yourcompany`)

For more information, visit the [Vitally REST API documentation](https://docs.vitally.io/en/collections/10410457-rest-api).

***

## Accounts

Operations for managing customer accounts in Vitally.

### List Accounts

List accounts from Vitally with pagination support.

**Operation Type:** Query (Read)

**Parameters:**

* **limit** `number` (default: 100): Maximum number of accounts to return
* **from** `string` (nullable): Cursor for pagination

**Returns:**

* **results** `array of objects`: List of accounts
  * **id** `string`: The account ID
  * **name** `string`: The account name
  * **externalId** `string`: The external ID
  * **traits** `object`: Account traits/attributes
* **next** `string` (nullable): Cursor for the next page of results

**Example Usage:**

```json
{
  "limit": 50,
  "from": null
}
```

### Get Account

Retrieve a single account by ID.

**Operation Type:** Query (Read)

**Parameters:**

* **id** `string` (required): Account ID

**Returns:**

* **id** `string`: The account ID
* **name** `string`: The account name
* **externalId** `string`: The external ID
* **traits** `object`: Account traits/attributes
* **createdAt** `string`: Created timestamp
* **updatedAt** `string`: Last updated timestamp

**Example Usage:**

```json
{
  "id": "abc123-def456"
}
```

### Create Account

Create a new account in Vitally.

**Operation Type:** Mutation (Write)

**Parameters:**

* **externalId** `string` (required): External ID for the account
* **name** `string` (required): Account name
* **traits** `object` (nullable): Account traits/attributes

**Returns:**

* **id** `string`: The account ID
* **name** `string`: The account name
* **externalId** `string`: The external ID
* **traits** `object`: Account traits/attributes
* **createdAt** `string`: Created timestamp
* **updatedAt** `string`: Last updated timestamp

**Example Usage:**

```json
{
  "externalId": "acme-corp",
  "name": "Acme Corporation",
  "traits": { "plan": "enterprise", "industry": "SaaS" }
}
```

### Update Account

Update an existing account in Vitally.

**Operation Type:** Mutation (Write)

**Parameters:**

* **id** `string` (required): Account ID
* **name** `string` (nullable): Account name
* **traits** `object` (nullable): Account traits/attributes

**Returns:**

* **id** `string`: The account ID
* **name** `string`: The account name
* **externalId** `string`: The external ID
* **traits** `object`: Account traits/attributes
* **createdAt** `string`: Created timestamp
* **updatedAt** `string`: Last updated timestamp

**Example Usage:**

```json
{
  "id": "abc123-def456",
  "name": "Acme Corporation (Renewed)",
  "traits": { "plan": "enterprise", "renewalDate": "2026-06-01" }
}
```

***

## Users

Operations for managing end users in Vitally.

### List Users

List users from Vitally with pagination support.

**Operation Type:** Query (Read)

**Parameters:**

* **limit** `number` (default: 100): Maximum number of users to return
* **from** `string` (nullable): Cursor for pagination

**Returns:**

* **results** `array of objects`: List of users
  * **id** `string`: The user ID
  * **name** `string`: The user name
  * **email** `string`: The user email
  * **externalId** `string`: The external ID
  * **traits** `object`: User traits/attributes
* **next** `string` (nullable): Cursor for the next page of results

**Example Usage:**

```json
{
  "limit": 100,
  "from": null
}
```

### Get User

Retrieve a single user by ID.

**Operation Type:** Query (Read)

**Parameters:**

* **id** `string` (required): User ID

**Returns:**

* **id** `string`: The user ID
* **name** `string`: The user name
* **email** `string`: The user email
* **externalId** `string`: The external ID
* **traits** `object`: User traits/attributes
* **createdAt** `string`: Created timestamp
* **updatedAt** `string`: Last updated timestamp

**Example Usage:**

```json
{
  "id": "user-abc123"
}
```

### Create User

Create a new user in Vitally.

**Operation Type:** Mutation (Write)

**Parameters:**

* **externalId** `string` (required): External ID for the user
* **name** `string` (nullable): User name
* **email** `string` (nullable): User email
* **accountIds** `string[]` (nullable): Account IDs to associate with user
* **traits** `object` (nullable): User traits/attributes

**Returns:**

* **id** `string`: The user ID
* **name** `string`: The user name
* **email** `string`: The user email
* **externalId** `string`: The external ID
* **traits** `object`: User traits/attributes
* **createdAt** `string`: Created timestamp
* **updatedAt** `string`: Last updated timestamp

**Example Usage:**

```json
{
  "externalId": "user-jane",
  "name": "Jane Smith",
  "email": "jane@acme.com",
  "accountIds": ["abc123-def456"],
  "traits": { "role": "admin" }
}
```

### Update User

Update an existing user in Vitally.

**Operation Type:** Mutation (Write)

**Parameters:**

* **id** `string` (required): User ID
* **name** `string` (nullable): User name
* **email** `string` (nullable): User email
* **accountIds** `string[]` (nullable): Account IDs to associate with user
* **traits** `object` (nullable): User traits/attributes

**Returns:**

* **id** `string`: The user ID
* **name** `string`: The user name
* **email** `string`: The user email
* **externalId** `string`: The external ID
* **traits** `object`: User traits/attributes
* **createdAt** `string`: Created timestamp
* **updatedAt** `string`: Last updated timestamp

**Example Usage:**

```json
{
  "id": "user-abc123",
  "traits": { "role": "super-admin", "lastLogin": "2026-02-20T10:00:00Z" }
}
```

***

## Organizations

Operations for managing organizations in Vitally.

### List Organizations

List organizations from Vitally with pagination support.

**Operation Type:** Query (Read)

**Parameters:**

* **limit** `number` (default: 100): Maximum number of organizations to return
* **from** `string` (nullable): Cursor for pagination

**Returns:**

* **results** `array of objects`: List of organizations
  * **id** `string`: The organization ID
  * **name** `string`: The organization name
  * **externalId** `string`: The external ID
  * **traits** `object`: Organization traits/attributes
* **next** `string` (nullable): Cursor for the next page of results

**Example Usage:**

```json
{
  "limit": 50,
  "from": null
}
```

### Get Organization

Retrieve a single organization by ID.

**Operation Type:** Query (Read)

**Parameters:**

* **id** `string` (required): Organization ID

**Returns:**

* **id** `string`: The organization ID
* **name** `string`: The organization name
* **externalId** `string`: The external ID
* **traits** `object`: Organization traits/attributes
* **createdAt** `string`: Created timestamp
* **updatedAt** `string`: Last updated timestamp

**Example Usage:**

```json
{
  "id": "org-abc123"
}
```

### Create Organization

Create a new organization in Vitally.

**Operation Type:** Mutation (Write)

**Parameters:**

* **externalId** `string` (required): External ID for the organization
* **name** `string` (required): Organization name
* **traits** `object` (nullable): Organization traits/attributes

**Returns:**

* **id** `string`: The organization ID
* **name** `string`: The organization name
* **externalId** `string`: The external ID
* **traits** `object`: Organization traits/attributes
* **createdAt** `string`: Created timestamp
* **updatedAt** `string`: Last updated timestamp

**Example Usage:**

```json
{
  "externalId": "org-acme",
  "name": "Acme Holdings",
  "traits": { "region": "North America" }
}
```

### Update Organization

Update an existing organization in Vitally.

**Operation Type:** Mutation (Write)

**Parameters:**

* **id** `string` (required): Organization ID
* **name** `string` (nullable): Organization name
* **traits** `object` (nullable): Organization traits/attributes

**Returns:**

* **id** `string`: The organization ID
* **name** `string`: The organization name
* **externalId** `string`: The external ID
* **traits** `object`: Organization traits/attributes
* **createdAt** `string`: Created timestamp
* **updatedAt** `string`: Last updated timestamp

**Example Usage:**

```json
{
  "id": "org-abc123",
  "name": "Acme Holdings International",
  "traits": { "region": "Global" }
}
```

***

## Notes

Operations for managing notes in Vitally.

### List Notes

List notes from Vitally with pagination support.

**Operation Type:** Query (Read)

**Parameters:**

* **limit** `number` (default: 100): Maximum number of notes to return
* **from** `string` (nullable): Cursor for pagination

**Returns:**

* **results** `array of objects`: List of notes
  * **id** `string`: The note ID
  * **subject** `string`: The note subject
  * **note** `string`: The note content
  * **accountId** `string` (nullable): Associated account ID
  * **organizationId** `string` (nullable): Associated organization ID
* **next** `string` (nullable): Cursor for the next page of results

**Example Usage:**

```json
{
  "limit": 25,
  "from": null
}
```

### Create Note

Create a new note in Vitally.

**Operation Type:** Mutation (Write)

**Parameters:**

* **subject** `string` (required): Note subject
* **note** `string` (required): Note content (HTML supported)
* **noteDate** `string` (required): Note date (ISO 8601 timestamp)
* **accountId** `string` (nullable): Account ID to associate with note (required if no organizationId)
* **organizationId** `string` (nullable): Organization ID to associate with note (required if no accountId)

**Returns:**

* **id** `string`: The note ID
* **subject** `string`: The note subject
* **note** `string`: The note content
* **accountId** `string` (nullable): Associated account ID
* **organizationId** `string` (nullable): Associated organization ID
* **createdAt** `string`: Created timestamp
* **updatedAt** `string`: Last updated timestamp

**Example Usage:**

```json
{
  "subject": "Q1 Check-in Summary",
  "note": "<p>Customer expressed interest in upgrading to enterprise plan.</p>",
  "noteDate": "2026-02-20T14:00:00Z",
  "accountId": "abc123-def456",
  "organizationId": null
}
```

***

## Tasks

Operations for managing tasks in Vitally.

### List Tasks

List tasks from Vitally with pagination support.

**Operation Type:** Query (Read)

**Parameters:**

* **limit** `number` (default: 100): Maximum number of tasks to return
* **from** `string` (nullable): Cursor for pagination

**Returns:**

* **results** `array of objects`: List of tasks
  * **id** `string`: The task ID
  * **name** `string`: The task name
  * **description** `string` (nullable): Task description
  * **accountId** `string` (nullable): Associated account ID
  * **assignedToId** `string` (nullable): Assigned user ID
  * **dueDate** `string` (nullable): Due date
* **next** `string` (nullable): Cursor for the next page of results

**Example Usage:**

```json
{
  "limit": 50,
  "from": null
}
```

### Create Task

Create a new task in Vitally.

**Operation Type:** Mutation (Write)

**Parameters:**

* **name** `string` (required): Task name
* **accountId** `string` (nullable): Account ID to associate with task
* **externalId** `string` (nullable): External ID for the task
* **description** `string` (nullable): Task description
* **assignedToId** `string` (nullable): User ID to assign the task to
* **dueDate** `string` (nullable): Task due date (ISO 8601 format)

**Returns:**

* **id** `string`: The task ID
* **name** `string`: The task name
* **description** `string` (nullable): Task description
* **accountId** `string` (nullable): Associated account ID
* **assignedToId** `string` (nullable): Assigned user ID
* **dueDate** `string` (nullable): Due date
* **createdAt** `string`: Created timestamp
* **updatedAt** `string`: Last updated timestamp

**Example Usage:**

```json
{
  "name": "Schedule onboarding call",
  "accountId": "abc123-def456",
  "description": "Set up initial onboarding call with the customer success team",
  "dueDate": "2026-03-01T00:00:00Z"
}
```

### Update Task

Update an existing task in Vitally.

**Operation Type:** Mutation (Write)

**Parameters:**

* **id** `string` (required): Task ID
* **name** `string` (nullable): Task name
* **description** `string` (nullable): Task description
* **assignedToId** `string` (nullable): User ID to assign the task to
* **dueDate** `string` (nullable): Task due date (ISO 8601 format)

**Returns:**

* **id** `string`: The task ID
* **name** `string`: The task name
* **description** `string` (nullable): Task description
* **accountId** `string` (nullable): Associated account ID
* **assignedToId** `string` (nullable): Assigned user ID
* **dueDate** `string` (nullable): Due date
* **createdAt** `string`: Created timestamp
* **updatedAt** `string`: Last updated timestamp

**Example Usage:**

```json
{
  "id": "task-abc123",
  "name": "Schedule onboarding call (rescheduled)",
  "dueDate": "2026-03-15T00:00:00Z"
}
```

***

## Conversations

Operations for managing conversations in Vitally.

### List Conversations

List conversations from Vitally with pagination support.

**Operation Type:** Query (Read)

**Parameters:**

* **limit** `number` (default: 100): Maximum number of conversations to return
* **from** `string` (nullable): Cursor for pagination

**Returns:**

* **results** `array of objects`: List of conversations
  * **id** `string`: The conversation ID
  * **externalId** `string`: The external ID
  * **subject** `string` (nullable): Conversation subject
  * **externalUrl** `string` (nullable): External URL
* **next** `string` (nullable): Cursor for the next page of results

**Example Usage:**

```json
{
  "limit": 25,
  "from": null
}
```

### Create Conversation

Create a new conversation in Vitally.

**Operation Type:** Mutation (Write)

**Parameters:**

* **externalId** `string` (required): External ID for the conversation
* **subject** `string` (required): Conversation subject
* **messages** `array of objects` (required): Messages in the conversation (at least one required)
  * **externalId** `string`: External ID for the message
  * **body** `string`: Message body (HTML supported)
  * **userExternalId** `string` (nullable): External ID of the user who sent the message
  * **sentAt** `string` (nullable): When the message was sent (ISO 8601 timestamp)

**Returns:**

* **id** `string`: The conversation ID
* **externalId** `string`: The external ID
* **subject** `string`: The conversation subject
* **createdAt** `string`: Created timestamp
* **updatedAt** `string`: Last updated timestamp

**Example Usage:**

```json
{
  "externalId": "conv-001",
  "subject": "Feature request discussion",
  "messages": [
    {
      "externalId": "msg-001",
      "body": "<p>Customer requested bulk export feature.</p>",
      "userExternalId": "user-jane",
      "sentAt": "2026-02-20T10:30:00Z"
    }
  ]
}
```

***

## NPS Responses

Operations for managing NPS (Net Promoter Score) responses.

### Create NPS Response

Create a new NPS response in Vitally.

**Operation Type:** Mutation (Write)

**Parameters:**

* **externalId** `string` (nullable): External ID for the NPS response
* **userId** `string` (required): User ID who provided the response
* **score** `number` (required): NPS score (0-10)
* **feedback** `string` (nullable): Feedback text
* **respondedAt** `string` (required): When the response was provided (ISO 8601 timestamp)

**Returns:**

* **id** `string`: The NPS response ID
* **externalId** `string`: The external ID
* **userId** `string`: The user ID
* **score** `number`: The NPS score
* **feedback** `string` (nullable): Feedback text
* **respondedAt** `string` (nullable): Response timestamp
* **createdAt** `string`: Created timestamp
* **updatedAt** `string`: Last updated timestamp

**Example Usage:**

```json
{
  "externalId": "nps-001",
  "userId": "user-abc123",
  "score": 9,
  "feedback": "Love the product! Would appreciate more integrations.",
  "respondedAt": "2026-02-20T15:00:00Z"
}
```

***

## Projects

Operations for managing projects in Vitally.

### List Projects

List projects from Vitally with pagination support.

**Operation Type:** Query (Read)

**Parameters:**

* **limit** `number` (default: 100): Maximum number of projects to return
* **from** `string` (nullable): Cursor for pagination

**Returns:**

* **results** `array of objects`: List of projects
  * **id** `string`: The project ID
  * **name** `string`: The project name
  * **description** `string` (nullable): Project description
  * **accountId** `string` (nullable): Associated account ID
* **next** `string` (nullable): Cursor for the next page of results

**Example Usage:**

```json
{
  "limit": 25,
  "from": null
}
```

### Create Project

Create a new project in Vitally from a template.

**Operation Type:** Mutation (Write)

**Parameters:**

* **templateId** `string` (required): Project template ID
* **accountId** `string` (nullable): Account ID (required if no organizationId)
* **organizationId** `string` (nullable): Organization ID (required if no accountId)
* **name** `string` (nullable): Project name (overrides template name)

**Returns:**

* **id** `string`: The project ID
* **name** `string`: The project name
* **accountId** `string` (nullable): Associated account ID
* **createdAt** `string`: Created timestamp
* **updatedAt** `string`: Last updated timestamp

**Example Usage:**

```json
{
  "templateId": "template-onboarding",
  "accountId": "abc123-def456",
  "name": "Acme Corp Onboarding"
}
```

***

## Custom Objects

Operations for managing custom objects in Vitally.

### List Custom Objects

List custom objects from Vitally with pagination support.

**Operation Type:** Query (Read)

**Parameters:**

* **limit** `number` (default: 100): Maximum number of custom objects to return
* **from** `string` (nullable): Cursor for pagination

**Returns:**

* **results** `array of objects`: List of custom objects
  * **id** `string`: The custom object ID
  * **name** `string`: The custom object name
  * **label** `string`: The custom object label
  * **createdAt** `string`: Created timestamp
  * **updatedAt** `string`: Last updated timestamp
* **next** `string` (nullable): Cursor for the next page of results

**Example Usage:**

```json
{
  "limit": 50,
  "from": null
}
```

***

## Common Use Cases

**Customer Success Management:**

* List and monitor customer accounts with health scores and traits
* Create tasks for CSMs to follow up on at-risk accounts
* Log notes from customer check-ins and QBRs
* Track NPS responses to identify promoters and detractors

**Onboarding Automation:**

* Create projects from templates when new accounts sign up
* Create tasks with due dates for onboarding milestones
* Track user adoption through user traits and custom objects
* Log conversations from onboarding calls

**Account Health Monitoring:**

* List accounts and filter by traits to identify at-risk customers
* Create notes documenting escalations and resolutions
* Update account traits with health scores from external systems
* Track conversations across support and success channels