REST API

API Endpoints

Retrieving usage statistics

Use this endpoint to retrieve statistics about your account's usage.

Request

GET https://api.upscope.io/v1.3/usage

Response

HTTP 200
{
  "status": "ok",
  "usage": {
      "agents": {
          "last_30_days": 10,
          "today": 0
      },
      "session_counts": {
          "last_30_days": 20,
          "now": 0,
          "today": 0
      },
      "session_seconds": {
          "last_30_days": 5000,
          "today": 0
      },
      "visitors": {
          "last_24_hrs": 50000,
          "online_now": 400
      }
  }
}

Field	Type	Description
`usage.agents.last_30_days`	Integer	Number of Agents who used Upscope in the last 30 days.
`usage.agents.today`	Integer	Number of Agents who used Upscope in the last 24 hours.
`usage.sessioncounts.last_30_days`	Integer	Number of Sessions in the last 30 days.
`usage.session_counts.now`	Integer	Number of Sessions currently ongoing.
`usage.session_counts.today`	Integer	Number of Sessions in the last 24 hours.
`usage.sessionseconds.last_30_days`	Integer	Number of Session seconds in the past 30 days.
`usage.session_seconds.today`	Integer	Number of Session seconds in the past 24 hours.
`usage.visitors.last_24_hrs`	Integer	Number of Visitors in the past 24 hours.
`usage.visitors.online_now`	Integer	Number of Visitors online now.

Searching for a Visitor or retrieving a list of Visitors

Use this endpoint to search for a particular Visitor or to show a list of recently online Visitors.

Know the Visitor's ID?

If you know the Visitor's ID, avoid using the search functionality and instead use the direct endpoint, which will be considerably faster.

Request

GET https://api.upscope.io/v1.3/list

Parameter	Type	Description
`search`	String?	The search query in this format. If left empty, the latest Visitors will be returned.

Response

HTTP 200
{
  "status": "ok",
  "visitors": [
    {
      "short_id": "1234",
      // ...
    }
  ]
}

Field	Type	Description
`visitors`	Visitor[]	List of Visitors matching the query.

Retrieving a Visitor

Use this endpoint to retrieve a particular Visitor.

Request

GET https://api.upscope.io/v1.3/visitors/{visitor_id}

Parameter	Type	Description
`{visitor_id}`	String	The short id of the Visitor.
`with_history`	Boolean	Whether to include pageviews with the Visitor.

Response

HTTP 200
{
  "status": "ok",
  "visitor": {
    "short_id": "1234",
    // ...
  }
}

Field	Type	Description
`visitor`	Visitor	The Visitor.

Errors

Code	Description
404	The Visitor does not exist.

Generating a link to start screen sharing with a visitor

Use this endpoint to generate a Secure watch link that enables whoever opens it to start a co-browsing Session with the Visitor without needing to be logged into Upscope as an Agent.

The link doesn't last long

The link returned by this endpoint doesn't last long and it's not meant to be stored anywhere.
Ideally, the Agent will make a request to an endpoint on your server, which makes this request behind the scenes and redirects the Agent to the watch_url immediately.
Your integration should never rely on storing the Secure watch link anywhere for any length of time.
Learn more here.

Request

POST https://api.upscope.io/v1.3/visitors/{visitor_id}/watch_url
{
  "branding": {
    "naked": true,
  },
  "permissions": {},
  "agent": {
    "id": "123",
    "name": "Joe Smith"
  },
  "metadata": {},
  "webhook_url": "https://example.com"
}

`Parameter`	Type	Description
`{visitor_id}`	String	The short id of the Visitor.
`agent.id`	String	The ID of the Agent (required).
`agent.name`	String	The name of the Agent (required).
`branding.naked`	`false`, `true`, or `"page_only"`	If `true`, the Upscope logo will not be shown on the page. This is ideal if you want to display the page inside an iframe. Defaults to `false`. Can be set to `page_only` to remove everything, including the Agent's UI. You can then control the Session by post-messaging the iframe.
`branding.on_end_url`	String	If set, the agent will be redirected to this url after the Session ends. If not set, the window will be attempted to be closed. Defaults to `null`.
`branding.retry_url`	String	If set, the visitor will be able to click a "Retry now" link that redirects to this url if there are problems. When null, no button is displayed. Defaults to `null`.
`initial_notes`	String	The starting state of the Agent notes for the Session. You can use this to add a template of what they should fill out.
`metadata`	Object	A JSON-encodeable object of metadata to add to the Session object. This can be used when retrieving a list of Sessions to run your own analytics. The object should be flat, meaning values can only be strings, numbers, or booleans.
`permissions.allow_agent_redirect`	Boolean	Whether the agent should have access to remote agent redirect & reload features (defaults to `true`, unless disabled through the Javascript SDK).
`permissions.allow_audio`	Boolean	Whether the agent should have access to audio (defaults to `true`, unless disabled through the Javascript SDK).
`permissions.allow_click`	Boolean	Whether the agent should have access to remote click (defaults to `true`, unless disabled through the Javascript SDK).
`permissions.allow_console`	Boolean	Whether the agent should have access to remote console capabilities (defaults to `false`).
`permissions.allow_draw`	Boolean	Whether the agent should have access to drawing (defaults to `true`, unless disabled through the Javascript SDK).
`permissions.allow_scroll`	Boolean	Whether the agent should have access to remote scroll (defaults to `true`, unless disabled through the Javascript SDK).
`permissions.allow_type`	Boolean	Whether the agent should have access to remote type (defaults to `true`, unless disabled through the Javascript SDK).
`options.audio_muted`	Boolean	Allows video audio to be heard by agent between agent and visitor defaults to `true` (muted).
`viewer.id`	String	The ID of the person viewing the screen (in case this is not the Agent).
`viewer.name`	String	The name of the person viewing the screen (in case this is not the Agent).
`webhook_url`	String	After the session is ended, a POST request will be made to this URL, sending the Session data as JSON.

Response

HTTP 200
{
    "status": "ok",
    "watch_url": "https://api.upscope.io/v1.3/visitors/VISITOR1234/session/a964e00a-c685-4d54-98d4-ea0bcb154d57",
    "expiration": "2022-01-11T18:01:49.700Z"
}

Field	Type	Description
`expiration`	Datetime	Time at which the link is no longer valid.
`watch_url`	String	The Secure watch url.

Errors

Code	Description
404	The Visitor does not exist.
402	This Session would put you over your subscription limits.

Stopping an active Session

Use this endpoint to stop an active Session.

Request

DELETE https://api.upscope.io/v1.3/visitors/{visitor_id}/session

Parameter	Type	Description
`{visitor_id}`	String	The short id of the Visitor.

Response

HTTP 200
ok

Errors

Code	Description
404	The Visitor does not exist.

Deleting a Visitor from Upscope

Use this endpoint to delete a Visitor from Upscope entirely.

You can only delete Visitors who are not currently online.

DELETE https://api.upscope.io/v1.3/visitors/{visitor_id}

Parameter	Type	Description
`{visitor_id}`	String	The short id of the Visitor.

Response

HTTP 200
ok

Errors

Code	Description
404	The Visitor does not exist.
409	The Visitor is online.

Deleting all visitor from Upscope

Use this endpoint to delete all Visitors from your Upscope account.

This will delete only Visitors that are offline.

Request

DELETE https://api.upscope.io/v1.3/visitors?all=true

Parameter	Type	Description
`all`	Boolean	Set to `true` to confirm deleting all Visitors.

Response

HTTP 200
ok

Agent Lookup

Use this endpoint to lookup an agent from your Upscope account.

You must send either the email or the external_id

Using the email it will lookup for users from your account, while using the external_id it will lookup for external agents from your account.
If you use any other parameter rather than email or external_id it will return not found.

Request

GET https://api.upscope.io/v1.3/agents/lookup?email=john@acme.com

Parameter	Type	Description
`email`	String	The Agent email, this will return an User.
`external_id`	String	The External Agent id, this will return an External Agent.

Response

HTTP 200
{
  "agent": {
    "id": "u_4g2bmwek",
    "agent_nickname": "John",
    "created_at": "2022-05-20T14:16:30.622Z",
    "email": "john@acme.com",
    "first_name": "John",
    "from_oauth": false,
    "last_name": "Doe",
    "last_request_at": "2022-05-20T14:16:30.620Z",
    "live_support": true,
    "mfa_enabled": false,
    "name": "John Doe",
    "password": false,
    "phone_number": null,
    "signup_hours_offset": 4,
    "timezone": null,
    "_type": "user",
    "sessions": [
      {
        "id": "s_e5pyoox5",
        "agents": [
          {
            "id": "u_enj38e5x",
            "agent_nickname": "John",
            "email": "john@acme.com",
            "external_id": null,
            "name": "John Doe",
            "on_premise": false,
            "_type": "user"
          }
        ],
        "call_length_seconds": 0,
        "call_name": null,
        "ended_at": "2022-06-21T15:30:26.001Z",
        "features_used": [
          "click",
          "scroll",
          "remote_cursor"
        ],
        "formatted_call_length": "-",
        "formatted_length": "1 minute",
        "length_seconds": 94,
        "on_premise": false,
        "public_video_url": null,
        "quality_feedback": [],
        "session_authorized": true,
        "source": "search",
        "started_at": "2022-06-21T15:28:51.503Z",
        "team": {
          "id": "t_8s3wmyo4",
          "domain": "acme.com",
          "_type": "team"
        },
        "video_status": null,
        "video_url": null,
        "visitor_id": "7NEHLZ0CDZCSQTFBQ",
        "went_live": true,
        "_type": "session"
        }
    ]
  },
  "status": "ok"
}

Field	Type	Description
`agent`	Agent	The Agent who started or joined the Session as an observer
`agent.sessions`	Session[]	The list of the agent's sessions

Errors

Code	Description
404	Agent not found

Creating a new Proxy session

Use this endpoint to create a new Proxy Session through the API.

The link doesn't last long

The link returned by this endpoint doesn't last long and it's not meant to be stored anywhere.
Your integration should never rely on storing the Proxy session link anywhere for any length of time.

Request

POST https://api.upscope.io/v1.3/proxy_sessions
{
  "initial_url": "https://test.com",
  "allowed_domains": ["test.com", "test-corp.com"],
  "branding": {
    "retry_url": null
  }
}

Parameter	Type	Description
`branding.retry_url`	String	If set, the visitor will be able to click a "Retry now" link that redirects to this url if there are problems. When `null`, no button is displayed. Defaults to `null`.
`initial_url`	String	The first URL to send the Visitor to. Defaults to `https://google.com/`.
`allowed_domains`	String[]	An array of domains that the visitor is allowed to go to. Defaults to `["*"]`, meaning all domains .

Response

HTTP 200
{
    "status": "ok",
    "proxy_url": "https://api.upscope.io/v1.3/proxy_sessions/b850f0ba-bf6f-47ea-b4c5-48ec46f0abde"
}

Field	Type	Description
`proxy_url`	String	The url to start the Proxy session.

Errors

Code	Description
402	Universal proxy is not enabled for your account.

Authorizing an on-premise Session

Use this endpoint to authorize an on-premise Session.

Using our Dashboard?

If you have integrated your on-premise version of Upscope to our dashboard, you don't need to use the API. It all just works.

Request

POST https://api.upscope.io/v1.3/onpremise/token
{
  "visitor_id": "VISITOR123",
  "agent": {
    "id": "123",
    "name": "Joe Smith"
  }
}

Parameter	Type	Description
`agent.id`	String	The ID of the Agent (required).
`agent.name`	String	The name of the Agent (required).
`visitor_id`	String	The ID of the Visitor you want to co-browse with.

Response

HTTP 200
{
    "authorized": true,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkw...."
}

Field	Type	Description
`authorized`	Boolean	`true` to indicate the Session was authorized.
`token`	String	The `token` to send to the on-premise version of Upscope.

Errors

Code	Description
402	This session was not authorized.