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 programatic manner. With our API you can do the following things:

  • Clients - Create new clients (reseller only)

  • Agents - Manage your agents

  • Sessions - Get an overview of all your sessions

  • Queue - Manipulate the incoming Queue for your agents


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).


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"
  }
]

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'

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
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
POST /agents/?api_key=3b57bd2db21c46d2875508b982968d26
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "username": "Peter Pan",
  "agent_email": "peter@neverland.net",
  "password": "Pass@123"
}
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

Response Body:

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

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

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
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"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "agent_name": "Peter",
  "agent_id": 2,
  "agent_email": "peter@neverland.com"
}

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

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

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,
    "viewer_link": "https://surfly.com/123-123-123",
    "start_time": "2017-04-21T13:55:08.251918Z",
    "duration": null,
    "end_time": null,
    "queue_id": 0,
    "pin": null,
    "queued": false,
    "start_url": "https://surfly.com.com/test/widget/?widget_key=3b57bd2db21c46d2875508b982968d26&autohide_button=false&hide_until_agent_joins=false",
    "meta": "{}",
    "tags": [],
    "options": {
      "enable_sounds": 1,
      "videochat": 1,
      "whitelist": "[]",
      "agent_can_end_session": 1,
      "auto_restore": 1,
      "set_to_smallest": 0,
      "cookie_transfer_enabled": 1,
      "cookie_transfer_scopes": [],
      "QUEUE_CALLBACK": 0,
      "min_width": 0,
      "agent_can_request_control": 0,
      "widget_key": 0,
      "on_end_redirect_follower_to_queue": 0,
      "cookie_transfer_proxying": 0,
      "store_chat_logs": 0,
      "allow_control_switching": 1,
      "dock_position": "left",
      "start_muted": 0,
      "QUEUE_HANDLER": 0,
      "format_session_id": 1,
      "disable_end_redirect": 0,
      "agent_can_take_control": 0,
      "cookie_transfer_urls": [],
      "splash": 1,
      "theme_font_size": 0,
      "drawing_mode": "temporary",
      "drawing_width": "15",
      "QUEUE_METADATA_CALLBACK": 0,
      "theme_font_color": 0,
      "verbose_console": 0,
      "newurl": 1,
      "QUEUE_ENDPOINT": 0,
      "end_of_session_popup_url": "",
      "start_docked": 0,
      "chat_box_color": "#eb777f",
      "autohide_button": 0,
      "max_height": 0,
      "white_label": 0,
      "blacklist": "[]",
      "drawing_timeout": "3",
      "position": 0,
      "filesharing": 1,
      "hide_until_agent_joins": 0,
      "hidden": 0,
      "min_height": 0,
      "allow_original_file_download": 0,
      "docked_only": 0,
      "ui_off": 0,
      "drawing_color": "default",
      "max_width": 0,
      "sharing_button": 1,
      "auto_start": 0,
      "theme_font_background": 0,
      "block_until_agent_joins": 0,
      "follower_redirect_url": "",
      "only_embedded_sessions": 0,
      "stealth_mode": 1,
      "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
viewer_link the link that must be opened in a viewer 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
end_time time the session finished 2016-06-17T15:30:44.026111Z
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}
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,
  "viewer_link": "https://surfly.com/123-123-123",
  "leader_link": "https://surfly.com/mUBRJyslQStVXPEwUwFyQ",
  "start_time": "2017-04-21T13:55:08.251918Z",
  "duration": null,
  "end_time": null,
  "queue_id": 0,
  "pin": null,
  "queued": false,
  "start_url": "https://example.com",
  "meta": "{}",
  "tags": [],
  "options": {
    "enable_sounds": 1,
    "videochat": 1,
    "whitelist": "[]",
    "agent_can_end_session": 1,
    "auto_restore": 1,
    "set_to_smallest": 0,
    "cookie_transfer_enabled": 1,
    "cookie_transfer_scopes": [],
    "QUEUE_CALLBACK": 0,
    "min_width": 0,
    "agent_can_request_control": 0,
    "widget_key": 0,
    "on_end_redirect_follower_to_queue": 0,
    "cookie_transfer_proxying": 0,
    "store_chat_logs": 0,
    "allow_control_switching": 1,
    "dock_position": "left",
    "start_muted": 0,
    "QUEUE_HANDLER": 0,
    "format_session_id": 1,
    "disable_end_redirect": 0,
    "agent_can_take_control": 0,
    "cookie_transfer_urls": [],
    "splash": 1,
    "theme_font_size": 0,
    "drawing_mode": "temporary",
    "drawing_width": "15",
    "QUEUE_METADATA_CALLBACK": 0,
    "theme_font_color": 0,
    "verbose_console": 0,
    "newurl": 1,
    "QUEUE_ENDPOINT": 0,
    "end_of_session_popup_url": "",
    "start_docked": 0,
    "chat_box_color": "#eb777f",
    "autohide_button": 0,
    "max_height": 0,
    "white_label": 0,
    "blacklist": "[]",
    "drawing_timeout": "3",
    "position": 0,
    "filesharing": 1,
    "hide_until_agent_joins": 0,
    "hidden": 0,
    "min_height": 0,
    "allow_original_file_download": 0,
    "docked_only": 0,
    "ui_off": 0,
    "drawing_color": "default",
    "max_width": 0,
    "sharing_button": 1,
    "auto_start": 0,
    "theme_font_background": 0,
    "block_until_agent_joins": 0,
    "follower_redirect_url": "",
    "only_embedded_sessions": 0,
    "stealth_mode": 1,
    "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\"]
}" \
'https://surfly.com/v2/sessions/?api_key=API_KEY'

Request Body:

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

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

Active Sessions Collection

GET /sessions/?api_key=3b57bd2db21c46d2875508b982968d26&active_session=true
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": "fvFkrL4saf52nuFh4GP9oQw",
    "session_id": "fvFkrL4saf52nuFh4GP9oQw",
    "formatted_id": "123-123-123",
    "agent_id": null,
    "viewer_link": "https://surfly.com/123-123-123",
    "start_time": "2017-04-21T13:55:08.251918Z",
    "duration": null,
    "end_time": null,
    "queue_id": 0,
    "pin": null,
    "queued": false,
    "start_url": "https://example.com",
    "meta": "{}",
    "tags": [],
    "options": {
      "enable_sounds": 1,
      "videochat": 1,
      "whitelist": "[]",
      "agent_can_end_session": 1,
      "auto_restore": 1,
      "set_to_smallest": 0,
      "cookie_transfer_enabled": 1,
      "cookie_transfer_scopes": [],
      "QUEUE_CALLBACK": 0,
      "min_width": 0,
      "agent_can_request_control": 0,
      "widget_key": 0,
      "on_end_redirect_follower_to_queue": 0,
      "cookie_transfer_proxying": 0,
      "store_chat_logs": 0,
      "allow_control_switching": 1,
      "dock_position": "left",
      "start_muted": 0,
      "QUEUE_HANDLER": 0,
      "format_session_id": 1,
      "disable_end_redirect": 0,
      "agent_can_take_control": 0,
      "cookie_transfer_urls": [],
      "splash": 1,
      "theme_font_size": 0,
      "drawing_mode": "temporary",
      "drawing_width": "15",
      "QUEUE_METADATA_CALLBACK": 0,
      "theme_font_color": 0,
      "verbose_console": 0,
      "newurl": 1,
      "QUEUE_ENDPOINT": 0,
      "end_of_session_popup_url": "",
      "start_docked": 0,
      "chat_box_color": "#eb777f",
      "autohide_button": 0,
      "max_height": 0,
      "white_label": 0,
      "blacklist": "[]",
      "drawing_timeout": "3",
      "position": 0,
      "filesharing": 1,
      "hide_until_agent_joins": 0,
      "hidden": 0,
      "min_height": 0,
      "allow_original_file_download": 0,
      "docked_only": 0,
      "ui_off": 0,
      "drawing_color": "default",
      "max_width": 0,
      "sharing_button": 1,
      "auto_start": 0,
      "theme_font_background": 0,
      "block_until_agent_joins": 0,
      "follower_redirect_url": "",
      "only_embedded_sessions": 0,
      "stealth_mode": 1,
      "leader_redirect_url": ""
    }
  }
]

List all Active Sessions
GET/sessions/?api_key={API_KEY}&active_session=true

List all ACTIVE sessions

cURL example:

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

Sessions Collection by tags

GET /sessions/?api_key=3b57bd2db21c46d2875508b982968d26&tags=tag1,tag2
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": "fvFkrL4saf52nuFh4GP9oQw",
    "session_id": "fvFkrL4saf52nuFh4GP9oQw",
    "formatted_id": "123-123-123",
    "agent_id": null,
    "viewer_link": "https://surfly.com/123-123-123",
    "start_time": "2017-04-21T13:55:08.251918Z",
    "duration": null,
    "end_time": null,
    "queue_id": 0,
    "pin": null,
    "queued": false,
    "start_url": "https://example.com",
    "meta": "{}",
    "tags": [
      "tag1",
      "tag2",
      "tag3"
    ],
    "options": {
      "enable_sounds": 1,
      "videochat": 1,
      "whitelist": "[]",
      "agent_can_end_session": 1,
      "auto_restore": 1,
      "set_to_smallest": 0,
      "cookie_transfer_enabled": 1,
      "cookie_transfer_scopes": [],
      "QUEUE_CALLBACK": 0,
      "min_width": 0,
      "agent_can_request_control": 0,
      "widget_key": 0,
      "on_end_redirect_follower_to_queue": 0,
      "cookie_transfer_proxying": 0,
      "store_chat_logs": 0,
      "allow_control_switching": 1,
      "dock_position": "left",
      "start_muted": 0,
      "QUEUE_HANDLER": 0,
      "format_session_id": 1,
      "disable_end_redirect": 0,
      "agent_can_take_control": 0,
      "cookie_transfer_urls": [],
      "splash": 1,
      "theme_font_size": 0,
      "drawing_mode": "temporary",
      "drawing_width": "15",
      "QUEUE_METADATA_CALLBACK": 0,
      "theme_font_color": 0,
      "verbose_console": 0,
      "newurl": 1,
      "QUEUE_ENDPOINT": 0,
      "end_of_session_popup_url": "",
      "start_docked": 0,
      "chat_box_color": "#eb777f",
      "autohide_button": 0,
      "max_height": 0,
      "white_label": 0,
      "blacklist": "[]",
      "drawing_timeout": "3",
      "position": 0,
      "filesharing": 1,
      "hide_until_agent_joins": 0,
      "hidden": 0,
      "min_height": 0,
      "allow_original_file_download": 0,
      "docked_only": 0,
      "ui_off": 0,
      "drawing_color": "default",
      "max_width": 0,
      "sharing_button": 1,
      "auto_start": 0,
      "theme_font_background": 0,
      "block_until_agent_joins": 0,
      "follower_redirect_url": "",
      "only_embedded_sessions": 0,
      "stealth_mode": 1,
      "leader_redirect_url": ""
    }
  }
]

List all Sessions by given tags
GET/sessions/?api_key={API_KEY}&tags=tag1,tag2

List all sessions with certain tags

cURL example:

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

Agent Sessions Collection

GET /sessions/?api_key=3b57bd2db21c46d2875508b982968d26&active_session=true&agent_id=1&year=2017&month=04
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": "fvFkrL4saf52nuFh4GP9oQw",
    "session_id": "fvFkrL4saf52nuFh4GP9oQw",
    "formatted_id": "123-123-123",
    "agent_id": 1,
    "viewer_link": "https://surfly.com/123-123-123",
    "start_time": "2017-04-21T13:55:08.251918Z",
    "duration": null,
    "end_time": null,
    "queue_id": 0,
    "pin": null,
    "queued": false,
    "start_url": "https://example.com",
    "meta": "{}",
    "tags": [],
    "options": {
      "enable_sounds": 1,
      "videochat": 1,
      "whitelist": "[]",
      "agent_can_end_session": 1,
      "auto_restore": 1,
      "set_to_smallest": 0,
      "cookie_transfer_enabled": 1,
      "cookie_transfer_scopes": [],
      "QUEUE_CALLBACK": 0,
      "min_width": 0,
      "agent_can_request_control": 0,
      "widget_key": 0,
      "on_end_redirect_follower_to_queue": 0,
      "cookie_transfer_proxying": 0,
      "store_chat_logs": 0,
      "allow_control_switching": 1,
      "dock_position": "left",
      "start_muted": 0,
      "QUEUE_HANDLER": 0,
      "format_session_id": 1,
      "disable_end_redirect": 0,
      "agent_can_take_control": 0,
      "cookie_transfer_urls": [],
      "splash": 1,
      "theme_font_size": 0,
      "drawing_mode": "temporary",
      "drawing_width": "15",
      "QUEUE_METADATA_CALLBACK": 0,
      "theme_font_color": 0,
      "verbose_console": 0,
      "newurl": 1,
      "QUEUE_ENDPOINT": 0,
      "end_of_session_popup_url": "",
      "start_docked": 0,
      "chat_box_color": "#eb777f",
      "autohide_button": 0,
      "max_height": 0,
      "white_label": 0,
      "blacklist": "[]",
      "drawing_timeout": "3",
      "position": 0,
      "filesharing": 1,
      "hide_until_agent_joins": 0,
      "hidden": 0,
      "min_height": 0,
      "allow_original_file_download": 0,
      "docked_only": 0,
      "ui_off": 0,
      "drawing_color": "default",
      "max_width": 0,
      "sharing_button": 1,
      "auto_start": 0,
      "theme_font_background": 0,
      "block_until_agent_joins": 0,
      "follower_redirect_url": "",
      "only_embedded_sessions": 0,
      "stealth_mode": 1,
      "leader_redirect_url": ""
    }
  }
]

List Active Sessions for Agent
GET/sessions/?api_key={API_KEY}&active_session=true&agent_id=1&year=2017&month=04

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

active_session, agent_id, year and month are optional

cURL example:

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

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,
  "viewer_link": "https://surfly.com/123-123-123",
  "start_time": "2017-04-21T13:55:08.251918Z",
  "duration": null,
  "end_time": null,
  "queue_id": 0,
  "pin": null,
  "queued": false,
  "start_url": "https://example.com",
  "meta": "{}",
  "tags": [],
  "options": {
    "enable_sounds": 1,
    "videochat": 1,
    "whitelist": "[]",
    "agent_can_end_session": 1,
    "auto_restore": 1,
    "set_to_smallest": 0,
    "cookie_transfer_enabled": 1,
    "cookie_transfer_scopes": [],
    "QUEUE_CALLBACK": 0,
    "min_width": 0,
    "agent_can_request_control": 0,
    "widget_key": 0,
    "on_end_redirect_follower_to_queue": 0,
    "cookie_transfer_proxying": 0,
    "store_chat_logs": 0,
    "allow_control_switching": 1,
    "dock_position": "left",
    "start_muted": 0,
    "QUEUE_HANDLER": 0,
    "format_session_id": 1,
    "disable_end_redirect": 0,
    "agent_can_take_control": 0,
    "cookie_transfer_urls": [],
    "splash": 1,
    "theme_font_size": 0,
    "drawing_mode": "temporary",
    "drawing_width": "15",
    "QUEUE_METADATA_CALLBACK": 0,
    "theme_font_color": 0,
    "verbose_console": 0,
    "newurl": 1,
    "QUEUE_ENDPOINT": 0,
    "end_of_session_popup_url": "",
    "start_docked": 0,
    "chat_box_color": "#eb777f",
    "autohide_button": 0,
    "max_height": 0,
    "white_label": 0,
    "blacklist": "[]",
    "drawing_timeout": "3",
    "position": 0,
    "filesharing": 1,
    "hide_until_agent_joins": 0,
    "hidden": 0,
    "min_height": 0,
    "allow_original_file_download": 0,
    "docked_only": 0,
    "ui_off": 0,
    "drawing_color": "default",
    "max_width": 0,
    "sharing_button": 1,
    "auto_start": 0,
    "theme_font_background": 0,
    "block_until_agent_joins": 0,
    "follower_redirect_url": "",
    "only_embedded_sessions": 0,
    "stealth_mode": 1,
    "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
viewer_link the link that must be opened in a viewer 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
end_time time the session finished 2016-06-17T15:30:44.026111Z
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}
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,
  "viewer_link": "https://surfly.com/123-123-123",
  "start_time": "2017-04-21T13:55:08.251918Z",
  "duration": 10,
  "end_time": "2017-04-21T13:55:18.251918Z",
  "queue_id": 0,
  "pin": null,
  "queued": false,
  "start_url": "https://example.com",
  "meta": "{}",
  "tags": [],
  "options": {
    "enable_sounds": 1,
    "videochat": 1,
    "whitelist": "[]",
    "agent_can_end_session": 1,
    "auto_restore": 1,
    "set_to_smallest": 0,
    "cookie_transfer_enabled": 1,
    "cookie_transfer_scopes": [],
    "QUEUE_CALLBACK": 0,
    "min_width": 0,
    "agent_can_request_control": 0,
    "widget_key": 0,
    "on_end_redirect_follower_to_queue": 0,
    "cookie_transfer_proxying": 0,
    "store_chat_logs": 0,
    "allow_control_switching": 1,
    "dock_position": "left",
    "start_muted": 0,
    "QUEUE_HANDLER": 0,
    "format_session_id": 1,
    "disable_end_redirect": 0,
    "agent_can_take_control": 0,
    "cookie_transfer_urls": [],
    "splash": 1,
    "theme_font_size": 0,
    "drawing_mode": "temporary",
    "drawing_width": "15",
    "QUEUE_METADATA_CALLBACK": 0,
    "theme_font_color": 0,
    "verbose_console": 0,
    "newurl": 1,
    "QUEUE_ENDPOINT": 0,
    "end_of_session_popup_url": "",
    "start_docked": 0,
    "chat_box_color": "#eb777f",
    "autohide_button": 0,
    "max_height": 0,
    "white_label": 0,
    "blacklist": "[]",
    "drawing_timeout": "3",
    "position": 0,
    "filesharing": 1,
    "hide_until_agent_joins": 0,
    "hidden": 0,
    "min_height": 0,
    "allow_original_file_download": 0,
    "docked_only": 0,
    "ui_off": 0,
    "drawing_color": "default",
    "max_width": 0,
    "sharing_button": 1,
    "auto_start": 0,
    "theme_font_background": 0,
    "block_until_agent_joins": 0,
    "follower_redirect_url": "",
    "only_embedded_sessions": 0,
    "stealth_mode": 1,
    "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
viewer_link the link that must be opened in a viewer 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
end_time time the session finished 2016-06-17T15:30:44.026111Z
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}
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
ID
string (required) Example: fuSHr0sRQ1usugvheahwQ

Screenshots

Screenshot Information

GET /sessions/fuSHr0sRQ1usugvheahwQ/screenshots/?api_key=3b57bd2db21c46d2875508b982968d26
Responses200
Headers
Content-Type: application/json
Body
{
  "status": "EXISTS",
  "url": "http://surfly-screenshots.s3.amazonaws.com/screenshot-ID.png",
  "timestamp": "1520356023"
}

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

Get information about screenshot for session by its ID.

cURL example:

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

Response body

Name Description Example
status status of the screenshot one of [“EXISTS”, “NOT_EXISTS”, “IN_PROGRESS”] EXISTS
url the address of the image http://surfly-screenshots.s3.amazonaws.com/screenshot-ID.png
timestamp timestamp of the screenshot 1520356023
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
ID
string (required) Example: fuSHr0sRQ1usugvheahwQ
POST /sessions/fuSHr0sRQ1usugvheahwQ/screenshots/?api_key=3b57bd2db21c46d2875508b982968d26
Responses200
Headers
Content-Type: application/json
Body
{
  "status": "STARTED"
}

Create a screenshot
POST/sessions/{ID}/screenshots/?api_key={API_KEY}

Create a new screenshot

cURL example:

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

Response Body:

Name Description Example
status status of the screenshot creation process STARTED
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
ID
string (required) Example: fuSHr0sRQ1usugvheahwQ

Queue

Manage and maintain the QUEUE for a certain client

Queue Collection

GET /queue/?api_key=3b57bd2db21c46d2875508b982968d26
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "start_time": "2016-08-11T13:44:58.025358Z",
    "url": "",
    "start_url": "http://www.surfly.com/",
    "pin": null,
    "identifier": null
  }
]

List all Active Sessions in the Queue
GET/queue/?api_key={API_KEY}

List all items in the support Queue

cURL example:

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

Response body

A list of objects containing the following parameters:

Name Description Example
start_time time the session started 2016-08-11T13:44:58.025358Z
url
start_url starting page of the session http://www.surfly.com/
pin 4-digit PIN code that can be used to join the session null
identifier null
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
POST /queue/?api_key=3b57bd2db21c46d2875508b982968d26
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "url": "http://www.example.com/",
  "id": "fEapBPiwxSouiLcAgb2OXQ"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "start_time": "2016-08-11T13:44:58.025358Z",
  "url": "",
  "start_url": "http://www.surfly.com/",
  "pin": 1234,
  "identifier": 1234
}

Add an item to the Queue
POST/queue/?api_key={API_KEY}

cURL example:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --data-binary "{
    \"url\": \"http://www.example.com/\",
    \"id\": \"fEapBPiwxSouiLcAgb2OXQ\"
}" \
'https://surfly.com/v2/queue/?api_key=API_KEY'

Request Body:

Name Description Example
id session ID or formatted session ID fEapBPiwxSouiLcAgb2OXQ or 123-456-789

Response Body:

Name Description Example
start_time time the session started 2016-08-11T13:44:58.025358Z
url
start_url starting page of the session http://www.surfly.com/
pin 4-digit PIN code that can be used to join the session 1234
identifier 1234
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
GET /queue/status/?api_key=3b57bd2db21c46d2875508b982968d26&tag=tag1
Responses200
Headers
Content-Type: application/json
Body
{
  "agent_available": true,
  "queued_sessions": 3
}

Get current queue status
GET/queue/status/?api_key={API_KEY}&tag={SESSION_TAG}

cURL example:

curl --include \
'https://surfly.com/v2/queue/status/?api_key=&tag='

Response Body:

Name Description Example
agent_available Returns true if there is an online available agent false
queued_sessions A number of the sessions in the queue. If session tag is specified, only sessions with that tag will be counted 24
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26
SESSION_TAG
string (optional) Example: tag1

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",
    "client_key": "AOEUaoeuntsPDe",
    "agent_count": 15,
    "widget_key": "24d1414c71a94cbf9f205ed4fc4999b5",
    "rest_key": "3b57bd2db21c46d2875508b982968d26",
    "domains": "example.com, *.example.com"
  },
  {
    "company_name": "DefaultCompany",
    "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
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",
  "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
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,
    "viewer_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
viewer_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

Invoice

Invoice Collection

GET /get/invoice/details/?api_key=3b57bd2db21c46d2875508b982968d26
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "item_list": [
      {
        "amount": 40,
        "description": "Date from 2015-06-29 to 2015-01-29",
        "unit_price": 0.67,
        "quantity": 60
      }
    ],
    "issue_date": "2015-6-06",
    "to_address": "ABC,1221,Netherlands,4343",
    "from_address": "Surfly Admin, Netherlands",
    "payment_term": 14,
    "sub_total": 1490,
    "currency": "euro",
    "invoice_number": 5,
    "total": 1490
  }
]

Lists your current month's invoice
GET/get/invoice/details/?api_key={API_KEY}

cURL example:

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

Response body

Name Description Example
issue_date the date the payment was issued 2015-6-06
to_address the address of the recipient ABC,1221,Netherlands,4343
from_address the address of the sender Surfly Admin, Netherlands
payment_term 14
sub_total amount due 1490
currency the currency type euro
invoice_number 5
total total payment amount 1490
URI Parameters
HideShow
API_KEY
string (required) Example: 3b57bd2db21c46d2875508b982968d26

Logs

Logs Collection

GET /logs/?api_key=jj34bd2db21c46d2875508b982968d26
Responses200
Headers
Content-Type: application/json
Body
{
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "agent_id": 4,
      "created": "2016-05-30T15:13:03.253096Z",
      "session_id": "flogr0sRQ1usugvheahwQ",
      "details": "New session with url http://surfly.com/ was started"
    }
  ]
}

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

Return a list of the logs

cURL example:

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

Response body

A list of objects containing the following parameters:

Name Description Example
id the queue ID 1
agent_id ID of the agent 4
created time and date the log was created 2016-05-30T15:13:03.253096Z
session_id the session ID flogr0sRQ1usugvheahwQ
details the log details New session with url http://surfly.com/ was started
URI Parameters
HideShow
API_KEY
string (required) Example: jj34bd2db21c46d2875508b982968d26
POST /logs/?api_key=jj34bd2db21c46d2875508b982968d26
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "session_id": "flogr0sRQ1usugvheahwQ",
  "details": "Log message"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 1,
  "agent_id": 4,
  "created": "2016-05-31T08:22:58.310337Z",
  "session_id": "flogr0sRQ1usugvheahwQ",
  "details": "Log message"
}

Create log instance
POST/logs/?api_key={API_KEY}

Create a new log

cURL example:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --data-binary " {
    \"session_id\": \"flogr0sRQ1usugvheahwQ\",
    \"details\": \"Log message\"
}" \
'https://surfly.com/v2/logs/?api_key=API_KEY'

Request body

Name Description Example
session_id the session ID flogr0sRQ1usugvheahwQ
details the message you want to log log message

Response body

Name Description Example
id the queue ID 1
agent_id the ID of the agent 4
created time and date 2016-05-31T08:22:58.310337Z
session_id the session ID flogr0sRQ1usugvheahwQ
details the message you want to log Log message
URI Parameters
HideShow
API_KEY
string (required) Example: jj34bd2db21c46d2875508b982968d26

Session Logs Collection

GET /logs/?api_key=jj34bd2db21c46d2875508b982968d26&session_id=flogr0sRQ1usugvheahwQ
Responses200
Headers
Content-Type: application/json
Body
{
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "agent_id": 4,
      "created": "2016-05-30T15:13:03.253096Z",
      "session_id": "flogr0sRQ1usugvheahwQ",
      "details": "New session with url http://surfly.com/ was started"
    }
  ]
}

List all session logs
GET/logs/?api_key={API_KEY}&session_id={SESSION_ID}

List all the logs from a session by SESSION_ID

cURL example:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --data-binary " {
    \"session_id\": \"flogr0sRQ1usugvheahwQ\",
    \"details\": \"Log message\"
}" \
'https://surfly.com/v2/logs/?api_key=API_KEY'

Response body

A list of objects containing the following parameters:

Name Description Example
id the queue ID 1
agent_id the ID of the agent 4
created the time and date at which the log was created 2016-05-30T15:13:03.253096Z
session_id the session ID flogr0sRQ1usugvheahQ
details the logged message New session with url http://surfly.com/ was started
URI Parameters
HideShow
API_KEY
string (required) Example: jj34bd2db21c46d2875508b982968d26
SESSION_ID
string (required) Example: flogr0sRQ1usugvheahwQ

Generated by aglio on 10 Aug 2018