Working with the GraphQL API

UserVitals

UserVitals How It Works Use Cases Help Docs

Search…

UserVitals setup guide

Setup

Single Sign-On (SSO)

Embeddable Widgets

Customer Portal Widget

Changelog Widget

Feedback Widget

GraphQL API

Working with the GraphQL API

Terminology

API Reference

Working with the GraphQL API

Want to create custom workflows with your product? or create internal tools around customer feedback flows with UserVitals? Our API is the best way to do that. Push customer feedback from any platform

UserVitals's public API is built using GraphQL. If you're new to GraphQL, Apollo has resources for beginners. The official documentation is another good starting point.
Endpoint
UserVital's GraphQL endpoint is:
https://api.uservitalshq.com/v1/
It supports introspection so you can query the whole schema.
Authentication
Right now we support API key authentication.
Personal API keys
A Personal API key is the easiest way to access the API. They can be created in Settings -> API. To authenticate your requests, you need to pass the newly created key as an Authorization header:
curl \
  -X POST \
  -H "Content-Type: application/json" \
  -H "authorization: Bearer <Replace this with your API Key>" \
  -H "auth-provider: custom" \
  --data '{"query":"query { me { id name email imageUrl} }"}' \
  https://api.uservitalshq.com/
Getting Started
We recommend using a GraphQL client to introspect and explore the schema.
​Insomnia is a free HTTP client that supports GraphQL. GraphQL Playground from Prisma is a dedicated GraphQL client that also has a desktop app.
Point the GraphQL client to the API endpoint:
https://api.uservitalshq.com/
Once you have your client installed, you can start making queries (read) and mutations (write) to the API.
Query the current user
To get information about the authenticated user, you can use the me query:
query {
  me {
    id
    name
    email
  }
}
Creating an Inbox message
To create a new message, we'll need to create a mutation:
mutation {
  createMessage(input: {
    title: "Mesage from API",
    content: "Some content",
    customerName: "Sarah Lee",
    customerEmail: "[email protected]",
    sourceUrl: "https://secure.helpscout.net/",
    status: UNREVIEWED,
    labels: ["Urgent"]
  }) {
    id
    title
    contact {
      id
      email
      name
    }
    labels {
      label {
        name
      }
    }
    status
    content
  }
}
This mutation will create a new message and return it's requested fields if the call was successful. In this call - it will create a message, assigned to a customer called Sarah Lee, with the status of UNREVIEWED and assign a label called Urgent (A label that was already created from the settings page)
Only a title and content are required fields. If customerName or customerEmail is not provided then the message will be assigned to Anonymous. The status defaults to unreviewed if not specified. You can provide a list of labels that will be assigned to the message, provided the label already exists in your workspace.
Support
If you run into problems or have questions or suggestions, you can join our customer Slack or send us an email at [email protected]. Both options are available through the UserVitals app.

Embeddable Widgets - Previous

Feedback Widget

Next - GraphQL API

Terminology

Last modified 8mo ago

Copy link

On this page

Endpoint

Authentication

Getting Started

Query the current user

Creating an Inbox message

Support