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.

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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