UserView

REST API

Build cobrowsing into your own product

A REST API and a React viewer SDK. Install the SDK on your pages, ask the API for a session from your server, and show the customer's screen in a new tab or inside your own app.

What the API allows

Let anyone see anyone else's screen, safely

The UserView product connects your support agents to your customers. The API removes that limit. Your server decides who watches whom, and hands each viewer a link or token that expires in minutes and carries only the permissions you chose.

Agent to visitor

The classic support session, started from your own tools. An agent clicks a button in your helpdesk or CRM and is looking at the customer's screen.

Peer to peer

The viewer doesn't have to be an agent. A teacher and a student, an advisor and a client, two colleagues: any user of your product can view another user's screen, in either direction.

No UserView login

Viewers never get a UserView account or a password to remember. Your app already knows who they are, so your server asks for a short-lived link on their behalf and sends them straight in.

Several viewers, different permissions

More than one person can join the same screen, each with their own permissions. One can click and type, another can only draw, and a third can watch without the session depending on them.

Your server decides

Every session starts with a call from your backend, signed with a secret key that never reaches a browser.

Links expire in minutes

A watch link lasts 5 minutes by default and a viewer token 60 seconds. Neither is meant to be stored.

Permissions per viewer

Switch remote click, typing, drawing, redirects and calls on or off for each link you hand out.

Masking still applies

Anything you mask in the SDK stays hidden while cobrowsing, whoever is watching. Full-screen and full-device sharing show the raw screen, and you can turn them off.

UserView or the API

How it differs from the UserView product

UserView is a finished support tool: your agents sign in and help your customers. The API is the same cobrowsing engine without the tool around it, for when you decide who connects to whom and where it happens.

UserView, the productThe REST API
Who can watchYour agentsAnyone your app chooses: agents, customers, partners, other users
Who signs inEach agent has a UserView accountNobody. Your app vouches for the viewer
Where a session startsThe UserView dashboard or a helpdesk integrationAnywhere in your own code
What the viewer looks likeThe UserView viewerThe hosted viewer, an unbranded iframe, or your own React UI
What you buildNothing. Paste one snippetThe snippet, plus one server call per viewer

What you can do with it

You don't need the API to use UserView: the standard install is one snippet and our dashboard. Use the API when a session should start somewhere else, such as a tool your agents already use, a product you sell, or an automated process.

Let agents start a session without leaving their tools

Put a “View screen” button in your helpdesk, CRM or internal admin. Your backend asks for a watch link and redirects the agent to it. No second console, no searching for the customer.

POST /visitors/{id}/watch_url

Put cobrowsing inside a product you sell

Render the session in your own UI with the React viewer SDK, or iframe the hosted viewer with our branding switched off. White-label cobrowsing: your toolbar, your layout, no UserView logo.

POST /visitors/{id}/viewer_token@upscopeio/viewer-sdk

Trigger sessions from your own workflows

End a session when the ticket closes. Delete visitor records on your own retention schedule. Pass a webhook_url and we POST the session data to you when it ends.

DELETE /visitors/{id}/sessionDELETE /visitors/{id}

Pull session data into your own reporting

List past sessions with filters and read account usage as JSON, then load it into whatever you already report from.

GET /cobrowsing_sessions/listGET /usage
One session, start to finish

Four calls, from ticket to closed session

The whole lifecycle: find the visitor, open their screen, clean up afterwards.

  1. Step 1

    A ticket comes in

    You already have the customer's email or user ID.

    no API call needed
  2. Step 2

    Find them

    Search by email, name or the ID you set in the SDK. Skip this if you already store the visitor ID.

    GET /list?search=…&max_results=1
  3. Step 3

    Open their screen

    Ask for a watch link to redirect to, or a viewer token to embed.

    POST …/watch_urlPOST …/viewer_token
  4. Step 4

    Close it out

    End the session when the ticket closes, and delete the record when you no longer need it.

    DELETE …/session
Two ways to open a session

Send them a link, or put the screen inside your own app

Same request body, different endpoint. One returns a URL, the other a token.

Two windows

A watch link

Returns a URL that is valid for 5 minutes by default. Redirect the agent to it and the hosted viewer opens in its own tab. The agent doesn't need a UserView login. Set branding.naked to drop our chrome and iframe it.

Your server
POST /v1.4/visitors/{visitor_id}/watch_url{ "viewer": { "id": "123", "name": "Joe Smith" } }// 200{ "watch_url": "https://userview.com/session/a964…",  "expiration": "2026-01-11T18:01:49.700Z" }
One window

Embedded in your own product

Returns a token that lasts 60 seconds by default, so request it right before connecting. Pass it to the React viewer SDK and render the screen wherever you want it. You build the toolbar; hooks give you session state and controls.

Your React app
import { ViewerProvider, Content } from "@upscopeio/viewer-sdk";<ViewerProvider token={token} shortId={shortId} region={region}  idleDisconnectSeconds={600}>  <Content color="red" controlTool="cursor" maxWidth={1200} maxHeight={1200} /></ViewerProvider>

Every endpoint, grouped by job

The same lifecycle, with the calls each stage uses.

Find the right visitor

Search by email, name or your own identifiers, or list who is online now. If you already know the visitor ID, fetch it directly: it is much faster than searching.

GET /listGET /visitors/{id}

Start a session from your own code

Generate a secure watch link and redirect the agent to it. Set permissions per link (remote control, redirect, screen share) and choose how long it stays valid.

POST /visitors/{id}/watch_url

Embed cobrowsing in your product

Issue a viewer token and render the session inside your own application with the viewer SDK. This is the route for white-label and embedded builds.

POST /visitors/{id}/viewer_token

Manage sessions and data

End a live session, list past sessions with filters, look up an agent by email or external ID, and delete visitor records on request.

DELETE /visitors/{id}/sessionGET /cobrowsing_sessions/listGET /agents/lookup

Authentication

Send your secret key in an X-Api-Key header on every request.

Keep it on your server. It is not the public key from the browser snippet, and the dashboard shows it once. If you get api_not_enabled, the API isn’t switched on for your account yet: get in touch.

401Reason
invalid_api_keyKey missing or not found
no_subscriptionSubscription has expired
api_not_enabledPlan doesn't include the API
please_contact_teamAccess restricted

Endpoints

Paths are relative to https://api.upscope.io/v1.4/. Requests and responses are JSON.

MethodPathPurpose
GET/usageAccount usage statistics
GET/listSearch visitors, or list recently active ones
GET/visitors/{visitor_id}Retrieve one visitor's details
POST/visitors/{visitor_id}/watch_urlGenerate a secure link to view their screen
POST/visitors/{visitor_id}/viewer_tokenToken to embed cobrowsing in your own app
DELETE/visitors/{visitor_id}/sessionEnd an active session
DELETE/visitors/{visitor_id}Remove a visitor
DELETE/visitors?all=trueRemove all offline visitors
GET/agents/lookupLook up an agent by email or external ID
GET/cobrowsing_sessions/listList sessions, with filtering
POST/onpremise/tokenAuthorise an on-premise session

Request bodies, object types, search syntax and embedded session control are in the full API documentation.

Transform your customer support

Join hundreds of companies using UserView to deliver faster, more effective customer support experiences.