API Documentation

API Endpoint

REST API Reference

By using the REST API, you can integrate our Co-browsing technology into your own application or build a thin layer around our technology. You can completely customize Surfly and automate the management of client and agent creation through the REST API.


The Surfly REST API allows you to integrate the functionality of our dashboard in a programmatic manner. With our API you can do the following things:

  • Agents - Manage your agents

  • Sessions - Get an overview of all your sessions

  • Screenshots - Create screenshots of your co-browsing sessions

  • Clients - Create new clients (reseller only)

  • Servers - Get a list of all available Surfly public cloud servers

  • History - Get an overview of sessions history

  • Webhooks - Manage your webhooks


Below you can find detailed code examples illustrating how to make the REST calls. You will need your REST API key (which can be found in the integration panel, just below the widget code).


Note: The rate limit for making REST API calls is 100 req/min/IP address


Agents

Agents Collection

GET /agents/?api_key=3b57bd2db21c46d2875508b982968d26
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "agent_id": 1,
    "agent_name": "Peter Pan",
    "agent_email": "peter@neverland.net",
    "last_login": "2020-02-03T11:03:39.323310Z",
    "role": "agent",
    "available": true
  }
]

List all agents
GET/agents/?api_key={API_KEY}

List all AGENTS

cURL example:

curl --include \
'https://surfly.com/v2/agents/?api_key=API_KEY&free=true'

Response Body:

A list of objects containing the following parameters:

Name Description Example
agent_id ID of the agent 1
agent_name name of the agent Peter Pan
agent_email email address of the agent peter@neverland.net
last_login date and time when user logged in or agent token has been generated 2020-02-03T11:03:39.323310Z
role agent role. Possible roles: admin, manager and agent agent
available agent availability status (boolean: true or false) true
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
free
boolean (optional) Example: true

agents that are ready to take a call. Depends on available field value and online status. Takes true or false.

POST /agents/?api_key=3b57bd2db21c46d2875508b982968d26
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "username": "Peter Pan",
  "agent_email": "peter@neverland.net",
  "password": "Pass@123",
  "role": "admin"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "agent_id": "1"
}

Create a new agent
POST/agents/?api_key={API_KEY}

Create a new AGENT

cURL example:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --data-binary "{
    \"username\": \"Peter Pan\",
    \"agent_email\": \"peter@neverland.net\",
    \"password\": \"Pass@123\"
}" \
'https://surfly.com/v2/agents/?api_key=API_KEY'

Request Body:

Name Description Example
username username of the agent Peter Pan
agent_email email address of the agent peter@neverland.net
password password Pass@123
role role of the agent, defaults to None which will create a regular agent. Other available roles: admin, manager. admin

Response Body:

Name Description Example
agent_id ID of the agent 1
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
free
boolean (optional) Example: true

agents that are ready to take a call. Depends on available field value and online status. Takes true or false.

Agent information

GET /agents/2/?api_key=3b57bd2db21c46d2875508b982968d26
Responses200
Headers
Content-Type: application/json
Body
{
  "agent_id": 2,
  "agent_name": "John Doe",
  "agent_email": "john.doe@example.com",
  "last_login": "2020-02-03T11:03:39.323310Z",
  "role": "agent",
  "available": true
}

Get Agent Information
GET/agents/{AGENT_ID}/?api_key={API_KEY}

Get information about a certain AGENT by AGENT_ID

cURL example:

curl --include \
'https://surfly.com/v2/agents/AGENT_ID/?api_key=API_KEY'

Response Body:

Name Description Example
agent_id ID of the agent 2
agent_name name of the agent John Doe
agent_email email address of the agent john.doe@example.com
last_login date and time when user logged in or agent token has been generated 2020-02-03T11:03:39.323310Z
role agent role. Possible roles: admin, manager and agent agent
available agent availability status (boolean: true or false) true
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
AGENT_ID
string (required) Example: 2
PUT /agents/2/?api_key=3b57bd2db21c46d2875508b982968d26
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "username": "Peter",
  "agent_email": "peter@neverland.com",
  "role": "admin",
  "available": true
}
Responses200
Headers
Content-Type: application/json
Body
{
  "agent_name": "Peter",
  "agent_id": 2,
  "agent_email": "peter@neverland.com",
  "role": "admin",
  "available": true
}

Update an agent
PUT/agents/{AGENT_ID}/?api_key={API_KEY}

Update an AGENT by AGENT_ID

cURL example:

curl --include \
     --request PUT \
     --header "Content-Type: application/json" \
     --data-binary "{
    \"username\": \"Peter\",
    \"agent_email\": \"peter@neverland.com\"
}" \
'https://surfly.com/v2/agents/AGENT_ID/?api_key=API_KEY'

Request Body:

Name Description Example
username (optional) username of the agent Peter Pan
agent_email (optional) email address of the agent peter@neverland.net
role (optional) string agent’s role. If specified, must be one of “agent”, “manager”, or “admin”. By default, “agent” is assumed.
available (optional) agent availability status (boolean: true or false) false

Response Body:

Name Description Example
agent_name name of the agent Peter
agent_id ID of the agent 2
agent_email email address of the agent peter@neverland.net
role agent’s role. admin
available agent availability status (boolean: true or false) true
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
AGENT_ID
string (required) Example: 2
DELETE /agents/2/?api_key=3b57bd2db21c46d2875508b982968d26
Responses200
Headers
Content-Type: application/json
Body
{
  "response": "Agent has been removed successfully"
}

Delete an agent
DELETE/agents/{AGENT_ID}/?api_key={API_KEY}

Remove an AGENT by AGENT_ID

cURL example:

curl --include \
     --request DELETE \
'https://surfly.com/v2/agents/AGENT_ID/?api_key=API_KEY'
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
AGENT_ID
string (required) Example: 2

Embed Access Tokens

POST /agents/access-token/?api_key=3b57bd2db21c46d2875508b982968d26
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "email": "agent@neverland.net",
  "name": "Ethan Hunt",
  "role": "agent"
}
Responses200404
Headers
Content-Type: application/json
Body
{
  "user_created": true,
  "agent_token": "t0aae2b2454c64b9a87b83ec09647dd9e",
  "expires_in": 86400,
  "agent_id": 1337,
  "agent_role": "agent"
}
Headers
Content-Type: application/json
Body
{
  "errors": {
    "agent_id": [
      "Agent was not found"
    ]
  }
}

Generate an access token
POST/agents/access-token/?api_key={API_KEY}

Generate a temporary access token for a given agent. Surfly generates a unique access token for the specified user and returns it in a response. The token expires automatically 24 hours after it is first created. Within that period, it can be used to construct Embed API links, but after that a new token has to be generated. Note that unless force_new parameter is set, Surfly will try to return an existing token. If the existing token is due to expire in less than 5 minutes, the new token will be generated even if force_new is set to false.

Note that 24 hours expiration time is mainly for performance optimization: the integrating app doesn’t have to generate a token on each page load. Instead, it can generate it (for example) when user logs in, and cache it for a day.

cURL example:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --data-binary "{
    \"email\": \"agent@neverland.net\",
    \"name\": \"Ethan Hunt\",
    \"role\": \"agent\"
}" \
'https://surfly.com/v2/agents/access-token/?api_key=API_KEY'

Request Body:

Name Type Description Required or optional
agent_id integer ID of an existing agent, if it was created before Optional
email string agent email Required when agent_id is not provided
name string agent name Required when agent_id is not provided
role string agent’s role. If specified, must be one of “agent”, “manager”, or “admin”. By default, “agent” is assumed. Optional
force_new boolean Force generating a new token, even if the old one is not yet expired. Note that a user can only have one active access token at a time, previous token associated with the user will be invalidated Optional

Response Body:

Name Type Description
user_created boolean indicates whether a new user object was created
agent_token string the generated access token
expires_in integer seconds before the agent_token expires
agent_id integer ID of the agent, useful when the call creates a new agent
agent_role string agent role
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26

Sessions

Sessions Collection

GET /sessions/?api_key=3b57bd2db21c46d2875508b982968d26
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": "fvFkrL4saf52nuFh4GP9oQw",
    "session_id": "fvFkrL4saf52nuFh4GP9oQw",
    "formatted_id": "123-123-123",
    "agent_id": null,
    "follower_link": "https://surfly.com/123-123-123",
    "cobro_server_name": "session.surfly.com",
    "start_time": "2017-04-21T13:55:08.251918Z",
    "duration": null,
    "participant_num": 0,
    "end_time": null,
    "successful_start": null,
    "queue_id": 0,
    "pin": null,
    "queued": false,
    "waiting_time": null,
    "start_url": "https://surfly.com.com/test/widget/?widget_key=3b57bd2db21c46d2875508b982968d26&autohide_button=false&hide_until_agent_joins=false",
    "meta": "{}",
    "tags": [],
    "opentok_archive_id": null,
    "space": null,
    "options": {
      "enable_sounds": true,
      "videochat": true,
      "allowlist": "[]",
      "agent_can_end_session": false,
      "auto_restore": true,
      "cookie_transfer_enabled": true,
      "cookie_transfer_scopes": [],
      "agent_can_request_control": false,
      "widget_key": 0,
      "cookie_transfer_proxying": false,
      "store_chat_logs": false,
      "allow_control_switching": true,
      "start_muted": false,
      "format_session_id": true,
      "disable_end_redirect": false,
      "agent_can_take_control": false,
      "cookie_transfer_urls": [],
      "splash": true,
      "theme_font_size": 14,
      "theme_font_color": "#FFFFFF",
      "verbose_console": false,
      "newurl": true,
      "end_of_session_popup_url": "",
      "start_docked": false,
      "autohide_button": false,
      "white_label": false,
      "blocklist": "[]",
      "position": "bottomleft",
      "filesharing": true,
      "hide_until_agent_joins": false,
      "hidden": false,
      "allow_original_file_download": false,
      "docked_only": false,
      "ui_off": false,
      "sharing_button": true,
      "auto_start": false,
      "theme_font_background": "#cc0000",
      "block_until_agent_joins": false,
      "follower_redirect_url": "",
      "only_embedded_sessions": false,
      "stealth_mode": true,
      "leader_redirect_url": ""
    }
  }
]

List all Sessions
GET/sessions/?api_key={API_KEY}

List all sessions

cURL example:

curl --include \
'https://surfly.com/v2/sessions/?api_key=API_KEY'

Response Body:

A list of objects containing the following parameters:

Name Description Example
session_id unique ID of the session fOBg4dXAPTHSoil6LywgfYA
formatted_id unique formatted ID of the session 123-456-789
agent_id ID of the agent 2
follower_link the link that must be opened in a follower browser https://surfly.com/123-456-789
start_time time the session started 2016-06-17T14:30:44.026111Z
duration length of the session (in seconds) 123
participant_num number of session participants 3
end_time time the session finished 2016-06-17T15:30:44.026111Z
successful_start Whether the session was technically successful or not true
pin 4-digit PIN code that can be used to join the session 3927
queued Whether the session has been put in a waiting queue false
waiting_time time the session waited to start when it was in queue. will be null if it’s never been in queue 00:00:56
start_url page the session started from https://example.com/
meta additional data attached to joining user {}
tags array of attached session tags [“tag1”, “tag2”]
options options the session was created with {“ui_off”: false, “block_until_agent_joins”: true}
cobro_server_name server name for multi-server installations session12.surfly.com
opentok_archive_id Opentok archive ID b40ef09b-3811-4726-b508-e41a0f96c68f
space Space link https://surfly.com/s/space/
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
POST /sessions/?api_key=3b57bd2db21c46d2875508b982968d26
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "url": "http://www.surfly.com/",
  "tags": [
    "tag1",
    "tag2"
  ]
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": "fvFkrL4saf52nuFh4GP9oQw",
  "session_id": "fvFkrL4saf52nuFh4GP9oQw",
  "formatted_id": "123-123-123",
  "agent_id": null,
  "follower_link": "https://surfly.com/123-123-123",
  "leader_link": "https://surfly.com/mUBRJyslQStVXPEwUwFyQ",
  "cobro_server_name": "session.surfly.com",
  "start_time": "2017-04-21T13:55:08.251918Z",
  "duration": null,
  "end_time": null,
  "queue_id": 0,
  "pin": null,
  "queued": false,
  "waiting_time": null,
  "start_url": "https://example.com",
  "meta": "{}",
  "tags": [],
  "options": {
    "enable_sounds": true,
    "videochat": true,
    "allowlist": "[]",
    "agent_can_end_session": false,
    "auto_restore": true,
    "cookie_transfer_enabled": true,
    "cookie_transfer_scopes": [],
    "agent_can_request_control": false,
    "widget_key": 0,
    "cookie_transfer_proxying": false,
    "store_chat_logs": false,
    "allow_control_switching": true,
    "start_muted": false,
    "format_session_id": true,
    "disable_end_redirect": false,
    "agent_can_take_control": false,
    "cookie_transfer_urls": [],
    "splash": true,
    "theme_font_size": 14,
    "theme_font_color": "#FFFFFF",
    "verbose_console": false,
    "newurl": true,
    "end_of_session_popup_url": "",
    "start_docked": false,
    "autohide_button": false,
    "white_label": false,
    "blocklist": "[]",
    "position": "bottomleft",
    "filesharing": true,
    "hide_until_agent_joins": false,
    "hidden": false,
    "allow_original_file_download": false,
    "docked_only": false,
    "ui_off": false,
    "sharing_button": true,
    "auto_start": false,
    "theme_font_background": "#cc0000",
    "block_until_agent_joins": false,
    "follower_redirect_url": "",
    "only_embedded_sessions": false,
    "stealth_mode": true,
    "leader_redirect_url": ""
  }
}

Create a session
POST/sessions/?api_key={API_KEY}

Create a new session

cURL example:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --data-binary "{
    \"url\": \"http://www.surfly.com/\",
    \"tags\": [\"tag1\", \"tag2\"],
    \"ui_off\": true
}" \
'https://surfly.com/v2/sessions/?api_key=API_KEY'

Request Body: You can also pass any session option(s) in the request body. Note that ui_off above is just an example.

Name Description Example
url url to co-browse http://www.google.com
agent_id (optional) ID of the agent 2
tags (optional) session tags tag1, tag2
skip_queue (optional) Prevents queueing the session when using a widget key (false by default) false
ui_off (optional) Pass ANY option when creating the session (ui_off is an example) true

Response Body:

Response will contain a JSON object with the same fields as in list endpoint, and the following extra fields:

Name Description Example
leader_link the link that must be opened in a leader (controlling) browser. It has a 2 minute time out attached to it, if not used within that time, the session will be closed. https://surfly.com/mUBRJyslQStVXPEwUwFyQ
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26

Filtering Sessions Collection

GET /sessions/?api_key=3b57bd2db21c46d2875508b982968d26&active_session=true&agent_id=1&year=2020&month=10&pin=1234&tags=tag1,tag2
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": "fvFkrL4saf52nuFh4GP9oQw",
    "session_id": "fvFkrL4saf52nuFh4GP9oQw",
    "formatted_id": "123-123-123",
    "agent_id": null,
    "follower_link": "https://surfly.com/123-123-123",
    "cobro_server_name": "session.surfly.com",
    "start_time": "2017-04-21T13:55:08.251918Z",
    "duration": null,
    "participant_num": 0,
    "end_time": null,
    "successful_start": null,
    "queue_id": 0,
    "pin": null,
    "queued": false,
    "waiting_time": null,
    "start_url": "https://example.com",
    "meta": "{}",
    "tags": [],
    "opentok_archive_id": null,
    "options": {
      "enable_sounds": true,
      "videochat": true,
      "allowlist": "[]",
      "agent_can_end_session": false,
      "auto_restore": true,
      "cookie_transfer_enabled": true,
      "cookie_transfer_scopes": [],
      "agent_can_request_control": false,
      "widget_key": 0,
      "cookie_transfer_proxying": false,
      "store_chat_logs": false,
      "allow_control_switching": true,
      "start_muted": false,
      "format_session_id": true,
      "disable_end_redirect": false,
      "agent_can_take_control": false,
      "cookie_transfer_urls": [],
      "splash": true,
      "theme_font_size": 14,
      "theme_font_color": "#FFFFFF",
      "verbose_console": false,
      "newurl": true,
      "end_of_session_popup_url": "",
      "start_docked": false,
      "autohide_button": false,
      "white_label": false,
      "blocklist": "[]",
      "position": "bottomleft",
      "filesharing": true,
      "hide_until_agent_joins": false,
      "hidden": false,
      "allow_original_file_download": false,
      "docked_only": false,
      "ui_off": false,
      "sharing_button": true,
      "auto_start": false,
      "theme_font_background": "#cc0000",
      "block_until_agent_joins": false,
      "follower_redirect_url": "",
      "only_embedded_sessions": false,
      "stealth_mode": true,
      "leader_redirect_url": ""
    }
  }
]

Filter sessions
GET/sessions/?api_key={api_key}&active_session={active_session}&agent_id={agent_id}&year={year}&month={month}&pin={pin}&tags={tags}

For example, list all active sessions

cURL example:

curl 'https://surfly.com/v2/sessions/?api_key=API_KEY&active_session=true'
URI Parameters
HideShow
api_key
string (required) Example: 3b57bd2db21c46d2875508b982968d26

REST API key of a company

active_session
boolean (optional) Example: true

Filter active or inactive sessions

agent_id
number (optional) Example: 1

Filter by ID of the agent who joined/started a session

year
number (optional) Example: 2020

Filter by year

month
number (optional) Example: 10

Filter by month

pin
number (optional) Example: 1234

Filter by PIN number (useful in combination with active_session)

tags
string (optional) Example: tag1,tag2

Filter by tag. Supports multiple comma separated tags at once

Session Information

GET /sessions/fuSHr0sRQ1usugvheahwQ/?api_key=3b57bd2db21c46d2875508b982968d26
Responses200
Headers
Content-Type: application/json
Body
{
  "id": "fvFkrL4saf52nuFh4GP9oQw",
  "session_id": "fvFkrL4saf52nuFh4GP9oQw",
  "formatted_id": "123-123-123",
  "agent_id": 1,
  "follower_link": "https://surfly.com/123-123-123",
  "cobro_server_name": "session.surfly.com",
  "start_time": "2017-04-21T13:55:08.251918Z",
  "duration": null,
  "participant_num": 3,
  "end_time": null,
  "successful_start": null,
  "queue_id": 0,
  "pin": null,
  "queued": false,
  "waiting_time": null,
  "start_url": "https://example.com",
  "meta": "{}",
  "tags": [],
  "opentok_archive_id": null,
  "options": {
    "enable_sounds": true,
    "videochat": true,
    "allowlist": "[]",
    "agent_can_end_session": false,
    "auto_restore": true,
    "cookie_transfer_enabled": true,
    "cookie_transfer_scopes": [],
    "agent_can_request_control": false,
    "widget_key": 0,
    "cookie_transfer_proxying": false,
    "store_chat_logs": false,
    "allow_control_switching": true,
    "start_muted": false,
    "format_session_id": true,
    "disable_end_redirect": false,
    "agent_can_take_control": false,
    "cookie_transfer_urls": [],
    "splash": true,
    "theme_font_size": 14,
    "theme_font_color": "#FFFFFF",
    "verbose_console": false,
    "newurl": true,
    "end_of_session_popup_url": "",
    "start_docked": false,
    "autohide_button": false,
    "white_label": false,
    "blocklist": "[]",
    "position": "bottomleft",
    "filesharing": true,
    "hide_until_agent_joins": false,
    "hidden": false,
    "allow_original_file_download": false,
    "docked_only": false,
    "ui_off": false,
    "sharing_button": true,
    "auto_start": false,
    "theme_font_background": "#cc0000",
    "block_until_agent_joins": false,
    "follower_redirect_url": "",
    "only_embedded_sessions": false,
    "stealth_mode": true,
    "leader_redirect_url": ""
  }
}

Get session information
GET/sessions/{ID}/?api_key={API_KEY}

Get information about a session by ID. ID can be a formatted ID (e.g. 123-123-123), or an unformatted ID (e.g. fuSHr0sRQ1usugvheahwQ)

cURL example:

curl --include \
'https://surfly.com/v2/sessions/ID/?api_key=API_KEY'

Response Body:

Name Description Example
session_id unique ID of the session fOBg4dXAPTHSoil6LywgfYA
formatted_id unique formatted ID of the session 123-456-789
agent_id ID of the agent 2
follower_link the link that must be opened in a follower browser https://surfly.com/123-456-789
start_time time the session started 2016-06-17T14:30:44.026111Z
duration length of the session (in seconds) 123
participant_num number of session participants 3
end_time time the session finished 2016-06-17T15:30:44.026111Z
successful_start Whether the session was technically successful or not true
pin 4-digit PIN code that can be used to join the session 3927
queued Whether the session has been put in a waiting queue false
waiting_time time the session waited to start when it was in queue. will be null if it’s never been in queue 00:00:56
start_url page the session started from https://example.com/
meta additional data attached to joining user {}
tags array of attached session tags [“tag1”, “tag2”]
options options the session was created with {“ui_off”: false, “block_until_agent_joins”: true}
cobro_server_name server name for multi-server installations session12.surfly.com
opentok_archive_id Opentok archive ID b40ef09b-3811-4726-b508-e41a0f96c68f
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
ID
string (required) Example: fuSHr0sRQ1usugvheahwQ

End session

POST /sessions/fuSHr0sRQ1usugvheahwQ/end/?api_key=3b57bd2db21c46d2875508b982968d26
Responses200
Headers
Content-Type: application/json
Body
{
  "id": "fvFkrL4saf52nuFh4GP9oQw",
  "session_id": "fvFkrL4saf52nuFh4GP9oQw",
  "formatted_id": "123-123-123",
  "agent_id": 1,
  "follower_link": "https://surfly.com/123-123-123",
  "cobro_server_name": "session.surfly.com",
  "start_time": "2017-04-21T13:55:08.251918Z",
  "duration": 10,
  "participant_num": 3,
  "end_time": "2017-04-21T13:55:18.251918Z",
  "successful_start": false,
  "queue_id": 0,
  "pin": null,
  "queued": false,
  "waiting_time": null,
  "start_url": "https://example.com",
  "meta": "{}",
  "tags": [],
  "opentok_archive_id": null,
  "options": {
    "enable_sounds": true,
    "videochat": true,
    "allowlist": "[]",
    "agent_can_end_session": false,
    "auto_restore": true,
    "cookie_transfer_enabled": true,
    "cookie_transfer_scopes": [],
    "agent_can_request_control": false,
    "widget_key": 0,
    "cookie_transfer_proxying": false,
    "store_chat_logs": false,
    "allow_control_switching": true,
    "start_muted": false,
    "enable_native_dialogs": 0,
    "format_session_id": true,
    "disable_end_redirect": false,
    "agent_can_take_control": false,
    "cookie_transfer_urls": [],
    "splash": true,
    "theme_font_size": 14,
    "theme_font_color": "#FFFFFF",
    "verbose_console": false,
    "newurl": true,
    "end_of_session_popup_url": "",
    "start_docked": false,
    "autohide_button": false,
    "white_label": false,
    "blocklist": "[]",
    "position": "bottomleft",
    "filesharing": true,
    "hide_until_agent_joins": false,
    "hidden": false,
    "allow_original_file_download": false,
    "docked_only": false,
    "ui_off": false,
    "sharing_button": true,
    "auto_start": false,
    "confirm_session_start": 0,
    "theme_font_background": "#cc0000",
    "block_until_agent_joins": false,
    "follower_redirect_url": "",
    "only_embedded_sessions": false,
    "stealth_mode": true,
    "leader_redirect_url": ""
  }
}

End session
POST/sessions/{ID}/end/?api_key={API_KEY}

End session

cURL example:

curl --data '' --include \
'https://surfly.com/v2/sessions/ID/end/?api_key=API_KEY'

Response Body:

Name Description Example
session_id unique ID of the session fOBg4dXAPTHSoil6LywgfYA
formatted_id unique formatted ID of the session 123-456-789
agent_id ID of the agent 2
follower_link the link that must be opened in a follower browser https://surfly.com/123-456-789
start_time time the session started 2016-06-17T14:30:44.026111Z
duration length of the session (in seconds) 123
participant_num number of session participants 3
end_time time the session finished 2016-06-17T15:30:44.026111Z
successful_start Whether the session was technically successful or not true
pin 4-digit PIN code that can be used to join the session 3927
queued Whether the session has been put in a waiting queue false
waiting_time time the session waited to start when it was in queue. will be null if it’s never been in queue 00:00:56
start_url page the session started from https://example.com/
meta additional data attached to joining user {}
tags array of attached session tags [“tag1”, “tag2”]
options options the session was created with {“ui_off”: false, “block_until_agent_joins”: true}
cobro_server_name server name for multi-server installations session12.surfly.com
opentok_archive_id Opentok archive ID b40ef09b-3811-4726-b508-e41a0f96c68f
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
ID
string (required) Example: fuSHr0sRQ1usugvheahwQ

Company

Default session options

List of all available options is available here

GET /company/options/?api_key=3b57bd2db21c46d2875508b982968d26
Responses200
Headers
Content-Type: application/json
Body
{
  "enable_sounds": true,
  "videochat": true,
  "allowlist": "[]"
}

Retrieve default options
GET/company/options/?api_key={api_key}

Returns an object with default session options. Plan limitations are taken into account

Also available with the widget key

cURL example:

curl 'https://surfly.com/v2/company/options/?api_key=API_KEY'
URI Parameters
HideShow
api_key
string (required) Example: 3b57bd2db21c46d2875508b982968d26

REST API key of a company

POST /company/options/?api_key=3b57bd2db21c46d2875508b982968d26
Responses200
Headers
Content-Type: application/json
Body
{
  "enable_sounds": true,
  "videochat": true,
  "allowlist": "[]"
}

Set default options
POST/company/options/?api_key={api_key}

Sets new default options. If any option is missing in the request body, its value is reset to default. If you need to update only certain options and leave the other intact, consider the PATCH method instead.

cURL example:

curl -X POST -d '{"start_docked": true}' 'https://surfly.com/v2/company/options/?api_key=API_KEY'
URI Parameters
HideShow
api_key
string (required) Example: 3b57bd2db21c46d2875508b982968d26

REST API key of a company

PATCH /company/options/?api_key=3b57bd2db21c46d2875508b982968d26
Responses200
Headers
Content-Type: application/json
Body
{
  "enable_sounds": true,
  "videochat": true,
  "allowlist": "[]"
}

Update default options
PATCH/company/options/?api_key={api_key}

Updates values of options specified in the request body. Other options are left intact

curl -X PATCH --header "Content-Type: application/json" -d '{"start_docked": true}' 'https://surfly.com/v2/company/options/?api_key=API_KEY'
URI Parameters
HideShow
api_key
string (required) Example: 3b57bd2db21c46d2875508b982968d26

REST API key of a company

DELETE /company/options/?api_key=3b57bd2db21c46d2875508b982968d26
Responses200
This response has no content.

Reset default options
DELETE/company/options/?api_key={api_key}

Resets all session options to their default values

cURL example:

curl -X DELETE 'https://surfly.com/v2/company/options/?api_key=API_KEY'
URI Parameters
HideShow
api_key
string (required) Example: 3b57bd2db21c46d2875508b982968d26

REST API key of a company

Screenshots

Latest Screenshot

GET /sessions/fuSHr0sRQ1usugvheahwQ/screenshots/latest/?api_key=3b57bd2db21c46d2875508b982968d26
Responses200
Headers
Content-Type: application/json
Body
{
  "url": "http://surfly-screenshots.s3.amazonaws.com/screenshot-ID.webp"
}

Latest Screenshot
GET/sessions/{ID}/screenshots/latest/?api_key={API_KEY}

Get latest screenshot for session by its ID.

cURL example:

curl --include \
'https://surfly.com/v2/sessions/ID/screenshots/latest/?api_key=API_KEY'

Response body

Name Description Example
url address of the latest image http://surfly-screenshots.s3.amazonaws.com/screenshot-ID.webp
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
ID
string (required) Example: fuSHr0sRQ1usugvheahwQ

Create Screenshot

POST /sessions/fEapBPiwxSouiLcAgb2OXQ1/screenshots/create/?api_key=3b57bd2db21c46d2875508b982968d26
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "size": 1024,
  "interval": 30
}
Responses200
Headers
Content-Type: text/plain
Body
"GENERATION-STARTED"

Create Screenshot
POST/sessions/{ID}/screenshots/create/?api_key={API_KEY}

Start generation of screenshots. The screenshots will be created as long as you keep getting the latest screenshots using the get latest screenshot API, that is to stop the creation of screenshot you just have to stop requesting the latest screenshot. There will be a new screenshot after a set interval second. The interval will be adjusted if the given value is lower than 5 secs. The max size of the screenshot will be adjusted in case the requested size is more than the window size.

cURL example:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
    --data-binary "{
        \"size\": 1920,
        \"interval\": 30
    }" \
'https://surfly.com/v2/sessions/ID/screenshots/create/?api_key=API_KEY'

Request Body:

Name Description Example
size width of the screenshot 1920
interval rate in second, at which screenshot will be generated 60

Response Body:

MESSAGE Description
GENERATION-STARTED screenshot generation process started
ALREADY-RUNNING screenshot generation process already running
FAILED-INTERNALLY screenshot generation process failed internally
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
ID
string (required) Example: fEapBPiwxSouiLcAgb2OXQ1

Clients

(2018-03-19) RESELLER_KEY is deprecated. In order to make old API calls compatible, we replaced the placeholder with the keyword all

Clients Collection

GET /clients/all/?api_key=3b57bd2db21c46d2875508b982968d26
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "company_name": "Neverland",
    "company_plan_name": "pro",
    "client_key": "AOEUaoeuntsPDe",
    "agent_count": 15,
    "widget_key": "24d1414c71a94cbf9f205ed4fc4999b5",
    "rest_key": "3b57bd2db21c46d2875508b982968d26",
    "domains": "example.com, *.example.com"
  },
  {
    "company_name": "DefaultCompany",
    "company_plan_name": "free",
    "client_key": "b05b45b8d4df42ba96",
    "agent_count": 2,
    "widget_key": "c6a1333308a843cc9fb6aee2e42941d6",
    "rest_key": "767dd31a038c4ee798c72abb4b568ade",
    "domains": "*"
  }
]

Lists all your clients
GET/clients/all/?api_key={API_KEY}

Return all clients of a reseller account

cURL example:

curl --include \
'https://surfly.com/v2/clients/all/?api_key=API_KEY'

Response Body:

A list of objects containing the following parameters:

Name Description Example
company_name name of company Neverland
company_plan_name name of the company’s plan pro
client_key client key AOEUaoeuntsPDe
agent_count maximum number of agents 15
widget_key widget key 24d1414c71a94cbf9f205ed4fc4999b5
rest_key REST API key 3b57bd2db21c46d2875508b982968d26
domains comma-separated list of domains example.com, *.example.com
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
POST /clients/all/?api_key=3b57bd2db21c46d2875508b982968d26
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "company_name": "Neverland",
  "domains": "*",
  "agent_email": "peter@mail.com",
  "agent_name": "Peter Pan"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "company_name": "Neverland",
  "client_key": "fOBg4dXAPTHSoil6LywgfYA",
  "rest_key": "22c0f77e5ca54d8fa6748f7cec4732c5",
  "widget_key": "92cdd920f4e345768f6717b02f15dae8"
}

Create a new client
POST/clients/all/?api_key={API_KEY}

Add a new client

cURL example:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --data-binary "{
    \"company_name\": \"Neverland\",
    \"domains\": \"*\",
    \"agent_email\": \"peter@mail.com\",
    \"agent_name\": \"Peter Pan\"
}" \
'https://surfly.com/v2/clients/all/?api_key=API_KEY'

Request Body:

Name Description Example
company_name name of new company Neverland
domains (optional) comma-separated list of domains *
agent_email (optional) email of a company admin peter@mail.com
agent_name (optional) name of a company admin Peter Pan
agent_password (optional) password for an agent account Password123!

Response Body:

Name Description Example
company_name name of company Neverland
client_key client key fOBg4dXAPTHSoil6LywgfYA
rest_key REST API key 22c0f77e5ca54d8fa6748f7cec4732c5
widget_key widget key 92cdd920f4e345768f6717b02f15dae8
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26

Client Information

GET /clients/all/63668234b4aa19dd436e6a76ab8ae000/?api_key=3b57bd2db21c46d2875508b982968d26
Responses200
Headers
Content-Type: application/json
Body
{
  "company_name": "Neverland",
  "company_plan_name": "pro",
  "client_key": "AOEUaoeuntsPDe",
  "agent_count": 15,
  "widget_key": "24d1414c71a94cbf9f205ed4fc4999b5",
  "rest_key": "3b57bd2db21c46d2875508b982968d26",
  "domains": "example.com, *.example.com"
}

Get Client Information
GET/clients/all/{CLIENT_KEY}/?api_key={API_KEY}

Get information about a specific client by CLIENT_KEY

cURL example:

curl --include \
'https://surfly.com/v2/clients/all/CLIENT_KEY/?api_key=API_KEY'

Response Body:

Name Description Example
company_name name of company Neverland
company_plan_name name of the company’s plan pro
client_key client key AOEUaoeuntsPDe
agent_count maximum number of agents 15
widget_key widget key 24d1414c71a94cbf9f205ed4fc4999b5
rest_key REST API key 3b57bd2db21c46d2875508b982968d26
domains comma-separated list of domains example.com, *.example.com
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
CLIENT_KEY
string (required) Example: 63668234b4aa19dd436e6a76ab8ae000
POST /clients/all/63668234b4aa19dd436e6a76ab8ae000/?api_key=3b57bd2db21c46d2875508b982968d26
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "domains": "example.com, *.example.com"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "domains": "example.com, *.example.com"
}

Set Client Domain List
POST/clients/all/{CLIENT_KEY}/?api_key={API_KEY}

cURL example:

curl --include \
'https://surfly.com/v2/clients/all/CLIENT_KEY/?api_key=API_KEY'

Request Body:

Name Description Example
domains comma-separated list of domains example.com, *.example.com

Response Body:

Name Description Example
domains comma-separated list of domains example.com, *.example.com
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
CLIENT_KEY
string (required) Example: 63668234b4aa19dd436e6a76ab8ae000
PUT /clients/all/63668234b4aa19dd436e6a76ab8ae000/?api_key=3b57bd2db21c46d2875508b982968d26
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "company_name": "Peter Pan"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "agent_count": 15,
  "company_name": "Peter Pan",
  "client_key": "AOEUaoeuntsPDe"
}

Update a client
PUT/clients/all/{CLIENT_KEY}/?api_key={API_KEY}

Update a client

cURL example:

curl --include \
     --request PUT \
     --header "Content-Type: application/json" \
     --data-binary "{
    \"company_name\": \"Peter Pan\"
}" \
'https://surfly.com/v2/clients/all/CLIENT_KEY/?api_key=API_KEY'

Request Body:

Name Description Example
company_name new name of company Peter Pan

Response Body:

Name Description Example
agent_count maximum number of agents 15
company_name name of company Peter Pan
client_key client key AOEUaoeuntsPDe
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
CLIENT_KEY
string (required) Example: 63668234b4aa19dd436e6a76ab8ae000
DELETE /clients/all/63668234b4aa19dd436e6a76ab8ae000/?api_key=3b57bd2db21c46d2875508b982968d26
Responses200
Headers
Content-Type: application/json
Body
{
  "response": "Client has been removed Successfully"
}

Delete a Client
DELETE/clients/all/{CLIENT_KEY}/?api_key={API_KEY}

cURL example:

curl --include \
     --request DELETE \
'https://surfly.com/v2/clients/all/CLIENT_KEY/?api_key=API_KEY'
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
CLIENT_KEY
string (required) Example: 63668234b4aa19dd436e6a76ab8ae000

Reseller Sessions Collection

GET /sessions/?api_key=3b57bd2db21c46d2875508b982968d26&clientkey=00063668234b4aa19dd436e6a76ab8ae&active_session=true&year=2015&month=01
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "session_id": "fOBg4dXAPTHSoil6LywgfYA",
    "agent_id": 2,
    "follower_link": "https://session.surfly.com/fwqcOuuMwTty7ii3kcA8Q",
    "start_time": "2016-08-11T13:44:58.025358Z",
    "duration": 123
  }
]

List Active Sessions for Reseller's Client
GET/sessions/?api_key={API_KEY}&clientkey={CLIENT_KEY}&active_session=true&year=2015&month=01

List all ACTIVE sessions for a certain CLIENT, year, month

active_session, year and month are optional

cURL example:

curl --include \
'https://surfly.com/v2/sessions/?api_key=API_KEY&clientkey=CLIENT_KEY&active_session=true&year=2015&month=01'

Response Body:

A list of objects containing the following parameters:

Name Description Example
session_id unique ID of the session fOBg4dXAPTHSoil6LywgfYA
agent_id ID of the agent 2
follower_link the link that must be opened in a viewer browser https://session.surfly.com/fHrD6TMmRrurMevgidxyw
start_time time the session started 2016-08-11T13:44:58.025358Z
duration length of the session (in seconds) 123
URI Parameters
HideShow
CLIENT_KEY
string (required) Example: 00063668234b4aa19dd436e6a76ab8ae
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26

Servers

Servers Collection

GET /servers/
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": "10",
    "region": "eu",
    "description": "Germany, Nuremberg"
  }
]

List all servers
GET/servers/

Return a list of available servers

cURL example:

curl --include \
'https://surfly.com/v2/servers/'

Response body

A list of objects containing the following parameters:

Name Description Example
id Server’s ID “10”
region Server’s location “eu”
description Description “Germany, Nuremberg”
ips List of IP addresses which are assigned to the server “1.1.1.1, 2.2.2.2”

History

History View

GET /history/?api_key=3b57bd2db21c46d2875508b982968d26
Responses200
Headers
Content-Type: application/json
Body
{
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "fvFkrL4saf52nuFh4GP9oQw",
      "session_id": "fvFkrL4saf52nuFh4GP9oQw",
      "formatted_id": "123-123-123",
      "cobro_server_name": "session.sitesupport.net",
      "agent_id": null,
      "follower_link": "https://sitesupport.net/fvFkrL4saf52nuFh4GP9oQw",
      "start_time": "2020-05-06T06:58:15.957711Z",
      "duration": null,
      "end_time": null,
      "successful_start": null,
      "queue_id": 0,
      "pin": null,
      "queued": false,
      "start_url": "http://www.surfly.com/",
      "meta": "{}",
      "tags": [
        "tag1",
        "tag2"
      ],
      "participant_num": 0,
      "options": {
        "enable_sounds": true,
        "store_session_logs": false,
        "videochat": true,
        "share_downloads": true,
        "stealth_mode": true,
        "orphan_redirect_url": "",
        "follower_drawing_selector": "",
        "hide_selector": "",
        "auto_restore": true,
        "s3_log_bucket": "",
        "branding_primary_color": "#e54747",
        "cookie_transfer_enabled": true,
        "cookie_transfer_scopes": [],
        "allow_pause": false,
        "agent_can_request_control": false,
        "branding_primary_fg_color": "#ffffff",
        "show_loading_screen": true,
        "show_cursors": true,
        "store_chat_logs": false,
        "hide_until_agent_joins": false,
        "allow_control_switching": true,
        "start_muted": false,
        "format_session_id": false,
        "require_password": false,
        "soft_end_filter": [],
        "proxy_only": false,
        "agent_can_take_control": false,
        "cookie_transfer_urls": [],
        "splash": false,
        "theme_font_size": 14,
        "shake_to_start": false,
        "chat_integration": "disabled",
        "hidden": false,
        "cookie_transfer_proxying": false,
        "verbose_console": false,
        "newurl": true,
        "disable_end_redirect": false,
        "end_of_session_popup_url": "",
        "start_docked": true,
        "widget_key": "",
        "white_label": false,
        "blocklist": "[]",
        "allowlist": "[]",
        "branding_secondary_fg_color": "#ffffff",
        "agent_can_end_session": false,
        "block_until_agent_joins": true,
        "native_selects": true,
        "filesharing": true,
        "autohide_button": false,
        "soft_session_end": false,
        "auto_start": false,
        "allow_original_file_download": false,
        "docked_only": false,
        "language": "en",
        "confirm_session_start": false,
        "branding_secondary_color": "#6e2222",
        "theme_font_background": "#cc0000",
        "ui_off": false,
        "url_mangling": false,
        "theme_font_color": "#FFFFFF",
        "enable_native_dialogs": false,
        "sharing_button": true,
        "leader_redirect_url": "",
        "private_session": false,
        "videochat_autostart": false,
        "position": "bottomleft",
        "follower_redirect_url": "",
        "only_embedded_sessions": false,
        "region": "",
        "selected_regions": []
      }
    },
    {
      "id": "fuSHr0sRQ1usugvheahwQ",
      "session_id": "fuSHr0sRQ1usugvheahwQ",
      "formatted_id": "266-974-529",
      "cobro_server_name": "session.sitesupport174.net",
      "agent_id": null,
      "follower_link": "https://sitesupport174.net/fuSHr0sRQ1usugvheahwQ",
      "start_time": "2020-05-06T06:58:14.234421Z",
      "duration": 648,
      "end_time": null,
      "successful_start": false,
      "queue_id": 1579,
      "pin": "1579",
      "queued": false,
      "start_url": "http://www.glover.org/",
      "meta": "{}",
      "tags": [],
      "participant_num": 0,
      "options": {
        "enable_sounds": true,
        "store_session_logs": false,
        "require_password": false,
        "videochat": true,
        "share_downloads": true,
        "allowlist": "[]",
        "orphan_redirect_url": "",
        "position": "bottomleft",
        "follower_drawing_selector": "",
        "hide_selector": "",
        "auto_restore": true,
        "s3_log_bucket": "",
        "branding_primary_color": "#e54747",
        "cookie_transfer_enabled": true,
        "cookie_transfer_scopes": [],
        "allow_pause": false,
        "agent_can_request_control": false,
        "widget_key": "",
        "branding_primary_fg_color": "#ffffff",
        "show_loading_screen": true,
        "show_cursors": true,
        "store_chat_logs": false,
        "allow_control_switching": true,
        "branding_logo_url": "",
        "start_muted": false,
        "format_session_id": false,
        "private_session": false,
        "soft_end_filter": [],
        "proxy_only": false,
        "agent_can_take_control": false,
        "splash": false,
        "theme_font_size": 14,
        "branding_logo_link": "",
        "chat_integration": "disabled",
        "hidden": false,
        "cookie_transfer_proxying": false,
        "theme_font_color": "#FFFFFF",
        "verbose_console": false,
        "end_of_session_popup_url": "",
        "newurl": true,
        "disable_end_redirect": false,
        "cookie_transfer_urls": [],
        "start_docked": true,
        "autohide_button": false,
        "agent_can_end_session": false,
        "white_label": false,
        "blocklist": "[]",
        "branding_secondary_fg_color": "#ffffff",
        "dashboard_background_url": "",
        "filesharing": true,
        "hide_until_agent_joins": false,
        "soft_session_end": false,
        "auto_start": false,
        "allow_original_file_download": false,
        "docked_only": false,
        "language": "en",
        "confirm_session_start": false,
        "branding_secondary_color": "#6e2222",
        "theme_font_background": "#cc0000",
        "ui_off": false,
        "url_mangling": false,
        "shake_to_start": false,
        "enable_native_dialogs": false,
        "sharing_button": true,
        "videochat_autostart": false,
        "region": "",
        "selected_regions": [],
        "block_until_agent_joins": true,
        "follower_redirect_url": "",
        "only_embedded_sessions": false,
        "stealth_mode": true,
        "native_selects": true,
        "leader_redirect_url": ""
      }
    },
    {
      "id": "fEapBPiwxSouiLcAgb2OXQ",
      "session_id": "fEapBPiwxSouiLcAgb2OXQ",
      "formatted_id": "596-185-458",
      "cobro_server_name": "session.sitesupport174.net",
      "agent_id": 3,
      "follower_link": "https://sitesupport174.net/fEapBPiwxSouiLcAgb2OXQ",
      "start_time": "2020-05-06T06:58:14.135584Z",
      "duration": null,
      "end_time": null,
      "successful_start": null,
      "queue_id": 0,
      "pin": null,
      "queued": false,
      "start_url": "http://wolffweissnat.net/",
      "meta": "{}",
      "tags": [],
      "participant_num": 0,
      "options": {
        "enable_sounds": true,
        "store_session_logs": false,
        "require_password": false,
        "videochat": true,
        "share_downloads": true,
        "allowlist": "[]",
        "orphan_redirect_url": "",
        "position": "bottomleft",
        "follower_drawing_selector": "",
        "hide_selector": "",
        "auto_restore": true,
        "s3_log_bucket": "",
        "branding_primary_color": "#e54747",
        "cookie_transfer_enabled": true,
        "cookie_transfer_scopes": [],
        "allow_pause": false,
        "agent_can_request_control": false,
        "widget_key": "",
        "branding_primary_fg_color": "#ffffff",
        "show_loading_screen": true,
        "show_cursors": true,
        "store_chat_logs": false,
        "allow_control_switching": true,
        "branding_logo_url": "",
        "start_muted": false,
        "format_session_id": false,
        "private_session": false,
        "soft_end_filter": [],
        "proxy_only": false,
        "agent_can_take_control": false,
        "splash": false,
        "theme_font_size": 14,
        "branding_logo_link": "",
        "chat_integration": "disabled",
        "hidden": false,
        "cookie_transfer_proxying": false,
        "theme_font_color": "#FFFFFF",
        "verbose_console": false,
        "end_of_session_popup_url": "",
        "newurl": true,
        "disable_end_redirect": false,
        "cookie_transfer_urls": [],
        "start_docked": true,
        "autohide_button": false,
        "agent_can_end_session": false,
        "white_label": false,
        "blocklist": "[]",
        "branding_secondary_fg_color": "#ffffff",
        "dashboard_background_url": "",
        "filesharing": true,
        "hide_until_agent_joins": false,
        "soft_session_end": false,
        "auto_start": false,
        "allow_original_file_download": false,
        "docked_only": false,
        "language": "en",
        "confirm_session_start": false,
        "branding_secondary_color": "#6e2222",
        "theme_font_background": "#cc0000",
        "ui_off": false,
        "url_mangling": false,
        "shake_to_start": false,
        "enable_native_dialogs": false,
        "sharing_button": true,
        "videochat_autostart": false,
        "region": "",
        "selected_regions": [],
        "block_until_agent_joins": true,
        "follower_redirect_url": "",
        "only_embedded_sessions": false,
        "stealth_mode": true,
        "native_selects": true,
        "leader_redirect_url": ""
      }
    }
  ]
}

List session history
GET/history/?api_key={API_KEY}

List history of all sessions

cURL example:

curl --include \
'https://surfly.com/v2/history/?api_key=API_KEY'

Response Body:

An object containing the following parameters:

Name Description Example
next link to the next page https://app.surfly.com/v2/history/?api_key=3b57bd2db21c46d2875508b982968d26&page=3
previous link to the previous page https://app.surfly.com/v2/history/?api_key=3b57bd2db21c46d2875508b982968d26&page=1
results a list of objects

Results:

Parameter results is a list of objects containing the following parameters:

Name Description Example
session_id unique ID of the session fOBg4dXAPTHSoil6LywgfYA
formatted_id unique formatted ID of the session 123-456-789
agent_id ID of the agent 2
follower_link the link that must be opened in a follower browser https://surfly.com/123-456-789
start_time time the session started 2016-06-17T14:30:44.026111Z
duration length of the session (in seconds) 123
participant_num number of session participants 3
end_time time the session finished 2016-06-17T15:30:44.026111Z
successful_start Whether the session was technically successful or not true
pin 4-digit PIN code that can be used to join the session 3927
queued Whether the session has been put in a waiting queue false
start_url page the session started from https://example.com/
meta additional data attached to joining user {}
tags array of attached session tags [“tag1”, “tag2”]
options options the session was created with {“ui_off”: false, “block_until_agent_joins”: true}
cobro_server_name server name for multi-server installations session12.surfly.com
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26

Filtering History

GET /history/?api_key=3b57bd2db21c46d2875508b982968d26&active_session=false&agent_id=null&pin=1234&tags=tag1&min_duration=120&max_duration=120&min_date=2020-05-06T00:00:00.000000Z&max_date=2020-05-06T00:00:00.000000Z
Responses200
Headers
Content-Type: application/json
Body
{
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "fuSHr0sRQ1usugvheahwQ",
      "session_id": "fuSHr0sRQ1usugvheahwQ",
      "formatted_id": "737-464-923",
      "cobro_server_name": "session.sitesupport.net",
      "agent_id": null,
      "follower_link": "https://sitesupport.net/fuSHr0sRQ1usugvheahwQ",
      "start_time": "2020-05-06T10:42:44.940708Z",
      "duration": 120,
      "end_time": null,
      "successful_start": false,
      "queue_id": 8359,
      "pin": "8359",
      "queued": false,
      "start_url": "http://www.surfly.com/",
      "meta": "{}",
      "tags": [
        "tag1"
      ],
      "participant_num": 0,
      "options": {
        "enable_sounds": true,
        "store_session_logs": false,
        "require_password": false,
        "videochat": true,
        "share_downloads": true,
        "allowlist": "[]",
        "orphan_redirect_url": "",
        "position": "bottomleft",
        "follower_drawing_selector": "",
        "hide_selector": "",
        "auto_restore": true,
        "s3_log_bucket": "",
        "branding_primary_color": "#e54747",
        "cookie_transfer_enabled": true,
        "cookie_transfer_scopes": [],
        "allow_pause": false,
        "agent_can_request_control": false,
        "widget_key": "",
        "branding_primary_fg_color": "#ffffff",
        "show_loading_screen": true,
        "show_cursors": true,
        "store_chat_logs": false,
        "allow_control_switching": true,
        "branding_logo_url": "",
        "start_muted": false,
        "format_session_id": false,
        "private_session": false,
        "soft_end_filter": [],
        "proxy_only": false,
        "agent_can_take_control": false,
        "splash": false,
        "theme_font_size": 14,
        "branding_logo_link": "",
        "chat_integration": "disabled",
        "hidden": false,
        "cookie_transfer_proxying": false,
        "theme_font_color": "#FFFFFF",
        "verbose_console": false,
        "end_of_session_popup_url": "",
        "newurl": true,
        "disable_end_redirect": false,
        "cookie_transfer_urls": [],
        "start_docked": true,
        "autohide_button": false,
        "agent_can_end_session": false,
        "white_label": false,
        "blocklist": "[]",
        "branding_secondary_fg_color": "#ffffff",
        "dashboard_background_url": "",
        "filesharing": true,
        "hide_until_agent_joins": false,
        "soft_session_end": false,
        "auto_start": false,
        "allow_original_file_download": false,
        "docked_only": false,
        "language": "en",
        "confirm_session_start": false,
        "branding_secondary_color": "#6e2222",
        "theme_font_background": "#cc0000",
        "ui_off": false,
        "url_mangling": false,
        "shake_to_start": false,
        "enable_native_dialogs": false,
        "sharing_button": true,
        "videochat_autostart": false,
        "region": "",
        "selected_regions": [],
        "block_until_agent_joins": true,
        "follower_redirect_url": "",
        "only_embedded_sessions": false,
        "stealth_mode": true,
        "native_selects": true,
        "leader_redirect_url": ""
      }
    }
  ]
}

Filter session history
GET/history/?api_key={api_key}&active_session={active_session}&agent_id={agent_id}&pin={pin}&tags={tags}&min_duration={min_duration}&max_duration={max_duration}&min_date={min_date}&max_date={max_date}

Results:

All filters are stackable like this:

https://app.surfly.com/v2/history/?api_key=3b57bd2db21c46d2875508b982968d26&&tags=tag1&tags=null

When filtering by pin, you might want to filter on active sessions by adding &active_session=true. Pins are generated to be unique for active sessions, so in case you are looking for a running session via pin, please use active_session filter as well:

https://app.surfly.com/v2/history/?api_key=3b57bd2db21c46d2875508b982968d26&pin=1234&active_session=true

Range of min_date and max_date is [min, max). So to get results from 2020-04-21:

https://app.surfly.com/v2/history/?api_key=3b57bd2db21c46d2875508b982968d26&min_date=2020-04-21T12:30-02:00&max_date=2020-04-22T12:30-02:00

cURL example:

curl --include \
'https://surfly.com/v2/history/?api_key=3b57bd2db21c46d2875508b982968d26&tags=tag1'
URI Parameters
HideShow
api_key
string (required) Example: 3b57bd2db21c46d2875508b982968d26

REST API key of a company

active_session
boolean (optional) Example: false

Filter active or inactive sessions. Takes true or false.

agent_id
string (optional) Example: null

Filter by ID of the agent who joined/started a session. Can take null as a value.

pin
string (optional) Example: 1234

Filter by session pin. Can take null as a value.

tags
string (optional) Example: tag1

Filter by session tag. Can take null as a value.

min_duration
number (optional) Example: 120

Filter by minimum duration of a session.

max_duration
number (optional) Example: 120

Filter by maximum duration of a session.

min_date
string (optional) Example: 2020-05-06T00:00:00.000000Z

Filter by earlist start date/time. Accepts a timestamp in iso8601 format. Make sure to take the timezone into account

max_date
string (optional) Example: 2020-05-06T00:00:00.000000Z

Filter by latest start date/time. Accepts a timestamp in iso8601 format. Make sure to take the timezone into account

Webhooks

Webhooks Collection

GET /webhooks/?api_key=3b57bd2db21c46d2875508b982968d26
Responses200
Headers
Content-Type: application/json
Body
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 538,
      "url": "https://dev.mycompany.com/webhooks/",
      "category": "session.started",
      "enabled": true,
      "ssl_verification": true,
      "company_id": 94906
    },
    {
      "id": 537,
      "url": "https://mycompany.com/webhooks/",
      "category": "session.started",
      "enabled": true,
      "ssl_verification": true,
      "company_id": 94906
    }
  ]
}

List all Webhooks
GET/webhooks/?api_key={API_KEY}

List all Webhooks

cURL example:

curl --include \
'https://surfly.com/v2/webhooks/?api_key=API_KEY'

Response Body:

An object containing the following parameters:

Name Description Example
count the total number of objects, across all pages
next link to the next page https://app.surfly.com/v2/webhooks/?api_key=3b57bd2db21c46d2875508b982968d26&page=3
previous link to the previous page https://app.surfly.com/v2/webhooks/?api_key=3b57bd2db21c46d2875508b982968d26&page=1
results a list of objects

Results:

Parameter results is a list of objects containing the following parameters:

Name Description Example
id webhook ID 538
url webhook url https://dev.mycompany.com/webhooks/
category webhook category session.started
enabled whether the webhook is enabled or nor true
ssl_verification whether to verify the server’s TLS certificate or not true
company_id company ID 94906
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
POST /webhooks/?api_key=3b57bd2db21c46d2875508b982968d26
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "url": "https://mycompany.com/webhooks/",
  "category": "session.started",
  "enabled": true,
  "ssl_verification": true
}
Responses201
Headers
Content-Type: application/json
Body
{
  "id": 539,
  "url": "https://mycompany.com/webhooks/",
  "category": "session.started",
  "enabled": true,
  "ssl_verification": true,
  "company_id": 94906
}

Create a Webhook
POST/webhooks/?api_key={API_KEY}

Create an Webhook

cURL example:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --data-binary "{
    \"url\": \"https://mycompany.com/webhooks/\",
    \"category\": \"session.started\",
    \"enabled\": true,
    \"ssl_verification\": true
}" \
'https://surfly.com/v2/webhooks/?api_key=API_KEY'

Request Body:

Name Description Example
url webhook url https://mycompany.com/webhooks/
category webhook category session.started
enabled whether the webhook is enabled or nor true
ssl_verification whether to verify the server’s TLS certificate or not true

Response Body:

Name Description Example
id webhook ID 538
url webhook url https://mycompany.com/webhooks/
category webhook category session.started
enabled whether the webhook is enabled or nor true
ssl_verification whether to verify the server’s TLS certificate or not true
company_id company ID 94906
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26

Webhook Information

GET /webhooks/1/?api_key=3b57bd2db21c46d2875508b982968d26
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 539,
  "url": "https://mycompany.com/webhooks/",
  "category": "session.started",
  "enabled": true,
  "ssl_verification": true,
  "company_id": 94906
}

Get Webhook Information
GET/webhooks/{WEBHOOK_ID}/?api_key={API_KEY}

Get Webhook Information

cURL example:

curl --include \
'https://surfly.com/v2/webhooks/WEBHOOK_ID/?api_key=API_KEY'

Response Body:

Name Description Example
id webhook ID 538
url webhook url https://mycompany.com/webhooks/
category webhook category session.started
enabled whether the webhook is enabled or nor true
ssl_verification whether to verify the server’s TLS certificate or not true
company_id company ID 94906
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
WEBHOOK_ID
string (required) Example: 1
PUT /webhooks/1/?api_key=3b57bd2db21c46d2875508b982968d26
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "url": "https://mycompany.com/webhooks/",
  "category": "session.started",
  "enabled": true,
  "ssl_verification": true
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 539,
  "url": "https://mycompany.com/webhooks/",
  "category": "session.started",
  "enabled": true,
  "ssl_verification": true,
  "company_id": 94906
}

Update an Webhook
PUT/webhooks/{WEBHOOK_ID}/?api_key={API_KEY}

Update an Webhook

cURL example:

curl --include \
     --request PUT \
     --header "Content-Type: application/json" \
     --data-binary "{
    \"url\": \"https://mycompany.com/webhooks/\",
    \"category\": \"session.started\",
    \"enabled\": false,
    \"ssl_verification\": true
}" \
'https://surfly.com/v2/webhooks/WEBHOOK_ID/?api_key=API_KEY'

Request Body:

Name Description Example
url webhook url https://mycompany.com/webhooks/
category webhook category session.started
enabled whether the webhook is enabled or nor true
ssl_verification whether to verify the server’s TLS certificate or not true

Response Body:

Name Description Example
id webhook ID 538
url webhook url https://mycompany.com/webhooks/
category webhook category session.started
enabled whether the webhook is enabled or nor true
ssl_verification whether to verify the server’s TLS certificate or not true
company_id company ID 94906
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
WEBHOOK_ID
string (required) Example: 1
DELETE /webhooks/1/?api_key=3b57bd2db21c46d2875508b982968d26
Responses204
This response has no content.

Delete an Webhook
DELETE/webhooks/{WEBHOOK_ID}/?api_key={API_KEY}

Remove an Webhook by WEBHOOK_ID

cURL example:

curl --include \
     --request DELETE \
'https://surfly.com/v2/webhooks/WEBHOOK_ID/?api_key=API_KEY'
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
WEBHOOK_ID
string (required) Example: 1

Generated by aglio on 26 Sep 2022