Skip to main content
API docs by Redocly

REST API Reference (2.0)

Download OpenAPI specification:Download

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

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

Agents

List

List all agents

query Parameters
API_KEY
required
string
Example: API_KEY=3b57bd2db21c46d2875508b982968d26
free
boolean
Example: free=true

Agents that are ready to take a call. Depends on available field value and online status.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create

Create a new AGENT

query Parameters
API_KEY
required
string
Example: API_KEY=3b57bd2db21c46d2875508b982968d26

Your rest API key

Request Body schema: application/json
required
username
required
string

Username of the agent

agent_email
required
string

E-mail address of the agent

password
required
string

Password of the agent

role
required
string
Default: "agent"
Enum: "admin" "manager" "agent"

Role of the agent

Responses

Request samples

Content type
application/json
{
  • "username": "Peter Pan",
  • "agent_email": "peter@neverland.net",
  • "password": "Pass@123",
  • "role": "admin"
}

Response samples

Content type
application/json
{
  • "agent_id": "1"
}

Get by id

Get information about a certain AGENT by AGENT_ID

path Parameters
API_KEY
required
string
Example: 3b57bd2db21c46d2875508b982968d26
AGENT_ID
required
string
Example: 2

Responses

Response samples

Content type
application/json
{
  • "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
}

Update

Update an AGENT by AGENT_ID

path Parameters
AGENT_ID
required
string
Example: 2

Id of the agent to update

query Parameters
API_KEY
required
string
Example: API_KEY=3b57bd2db21c46d2875508b982968d26
Request Body schema: application/json
required
username
required
string

Username of the agent

role
string
Default: "agent"
Enum: "admin" "manager" "agent"

Agent's role.

available
required
boolean

Agent availability status

Responses

Request samples

Content type
application/json
{
  • "username": "Peter",
  • "available": true
}

Response samples

Content type
application/json
{
  • "agent_name": "Peter",
  • "agent_id": 2,
  • "agent_email": "peter@neverland.com",
  • "available": true
}

Delete

Remove an AGENT by AGENT_ID

path Parameters
AGENT_ID
required
string
Example: 2
query Parameters
API_KEY
required
string
Example: API_KEY=3b57bd2db21c46d2875508b982968d26

Responses

Response samples

Content type
application/json
{
  • "response": "Agent has been removed successfully"
}

Generate an access token

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.

query Parameters
API_KEY
required
string
Example: API_KEY=3b57bd2db21c46d2875508b982968d26
Request Body schema: application/json
required
agent_id
required
integer <int32>

Id of the agent

email
required
string

Agent email. Required when agent_id is not provided

name
required
string

Agent name. Required when agent_id is not provided

role
string
Enum: "admin" "manager" "agent"

User role

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

Responses

Request samples

Content type
application/json
{
  • "email": "agent@neverland.net",
  • "name": "Ethan Hunt",
  • "role": "agent"
}

Response samples

Content type
application/json
{
  • "user_created": true,
  • "agent_token": "t0aae2b2454c64b9a87b83ec09647dd9e",
  • "expires_in": 86400,
  • "agent_id": 1337,
  • "agent_role": "agent"
}

Sessions

List

List all sessions

query Parameters
API_KEY
required
string
Example: API_KEY=3b57bd2db21c46d2875508b982968d26

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create

Create a new session

query Parameters
API_KEY
required
string
Example: API_KEY=3b57bd2db21c46d2875508b982968d26
Request Body schema: application/json
required
url
required
string

Url to co-browse

tags
Array of strings

Tag associated to this session

agent_id
integer <int32>

Id of the agent

skip_queue
boolean
Default: false

Prevents queueing the session when using a widget key

hide_session_ui
boolean

Note that hide_session_ui here is just an example. You can also pass any session option(s) in the request body

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "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": {
    }
}

Filter

Filter session. For example, list all active sessions

query Parameters
api_key
required
string
Example: api_key=3b57bd2db21c46d2875508b982968d26
active_session
required
boolean
Example: active_session=true

Filter active or inactive sessions

agent_id
required
number <double>
Example: agent_id=1

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

year
required
number <double>
Example: year=2020

Filter by year

month
required
number <double>
Example: month=10

Filter by month

pin
required
number <double>
Example: pin=1234

Filter by PIN number (useful in combination with active_session)

tags
required
string
Example: tags=tag1,tag2

Filter by tag. Supports multiple comma separated tags at once

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get by id

Get information about a session by ID.

path Parameters
ID
required
string
Example: fuSHr0sRQ1usugvheahwQ

Id of the session. Can be a formatted ID (e.g. 123-123-123), or an unformatted ID (e.g. fuSHr0sRQ1usugvheahwQ)

query Parameters
API_KEY
required
string
Example: API_KEY=3b57bd2db21c46d2875508b982968d26

Responses

Response samples

Content type
application/json
{
  • "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": {
    }
}

End

End a session by Id

path Parameters
ID
required
string
Example: fuSHr0sRQ1usugvheahwQ
query Parameters
API_KEY
required
string
Example: API_KEY=3b57bd2db21c46d2875508b982968d26

Responses

Response samples

Content type
application/json
{
  • "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": {
    }
}

Company

Get default options

Get company options. A list of all available options is available here. Returns an object with default session options. Plan limitations are taken into account

query Parameters
api_key
required
string
Example: api_key=3b57bd2db21c46d2875508b982968d26

Responses

Response samples

Content type
application/json
{
  • "sounds_enabled": true,
  • "videochat": true,
  • "allowlist": "[]"
}

Post options

List of all available options is available here. 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.

query Parameters
api_key
required
string
Example: api_key=3b57bd2db21c46d2875508b982968d26

Responses

Response samples

Content type
application/json
{
  • "sounds_enabled": true,
  • "videochat": true,
  • "allowlist": "[]"
}

Update default options

List of all available options is available here. Updates values of options specified in the request body. Other options are left intact

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

Responses

Response samples

Content type
application/json
{
  • "sounds_enabled": true,
  • "videochat": true,
  • "allowlist": "[]"
}

Reset default options

List of all available options is available here. Resets all session options to their default values

query Parameters
api_key
required
string
Example: api_key=3b57bd2db21c46d2875508b982968d26

Responses

Screenshots

Latest Screenshot

Get latest screenshot for session by its ID.

path Parameters
ID
required
string
Example: fuSHr0sRQ1usugvheahwQ
query Parameters
API_KEY
required
string
Example: API_KEY=3b57bd2db21c46d2875508b982968d26

Responses

Response samples

Content type
application/json
{}

Create Screenshot

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.

path Parameters
ID
required
string
Example: fEapBPiwxSouiLcAgb2OXQ1
query Parameters
API_KEY
required
string
Example: API_KEY=3b57bd2db21c46d2875508b982968d26
Request Body schema: application/json
required
size
required
integer <int32>

Width of the screenshot in pixels

interval
required
integer <int32>

Rate in seconds, at which screenshot will be generated

Responses

Request samples

Content type
application/json
{
  • "size": 1024,
  • "interval": 30
}

Response samples

Content type
text/plain
"GENERATION-STARTED"

Clients

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

List

Return all clients of a reseller account

query Parameters
API_KEY
required
string
Example: API_KEY=3b57bd2db21c46d2875508b982968d26

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create

Add a new client

query Parameters
API_KEY
required
string
Example: API_KEY=3b57bd2db21c46d2875508b982968d26
Request Body schema: application/json
required
company_name
required
string

Name of the company

company_plan_name
string
Default: "client_enterprise"

Name of the plan

domains
string

Comma-separated list of domains

agent_email
string

Email of the agent

agent_name
string

Username of the agent

agent_password
string

Password of the agent

Responses

Request samples

Content type
application/json
{
  • "company_name": "Neverland",
  • "domains": "*",
  • "agent_email": "peter@mail.com",
  • "agent_name": "Peter Pan"
}

Response samples

Content type
application/json
{
  • "company_name": "Neverland",
  • "client_key": "fOBg4dXAPTHSoil6LywgfYA",
  • "rest_key": "22c0f77e5ca54d8fa6748f7cec4732c5",
  • "widget_key": "92cdd920f4e345768f6717b02f15dae8"
}

Get by Id

Get information about a specific client by CLIENT_KEY

path Parameters
CLIENT_KEY
required
string
Example: 63668234b4aa19dd436e6a76ab8ae000
query Parameters
API_KEY
required
string
Example: API_KEY=3b57bd2db21c46d2875508b982968d26

Responses

Response samples

Content type
application/json
{
  • "company_name": "Neverland",
  • "company_plan_name": "pro",
  • "client_key": "AOEUaoeuntsPDe",
  • "agent_count": 15,
  • "widget_key": "24d1414c71a94cbf9f205ed4fc4999b5",
  • "rest_key": "3b57bd2db21c46d2875508b982968d26",
  • "domains": "example.com, *.example.com"
}

Set Client Domain List

Set Client Domain List

path Parameters
CLIENT_KEY
required
string
Example: 63668234b4aa19dd436e6a76ab8ae000
query Parameters
API_KEY
required
string
Example: API_KEY=3b57bd2db21c46d2875508b982968d26
Request Body schema: application/json
required
domains
required
string

Comma-separated list of domains

Responses

Request samples

Content type
application/json
{
  • "domains": "example.com, *.example.com"
}

Response samples

Content type
application/json
{
  • "domains": "example.com, *.example.com"
}

Update

Update a client

path Parameters
CLIENT_KEY
required
string
Example: 63668234b4aa19dd436e6a76ab8ae000
query Parameters
API_KEY
required
string
Example: API_KEY=3b57bd2db21c46d2875508b982968d26
Request Body schema: application/json
required
company_name
required
string

Name of the company

company_plan_name
string
Default: "client_enterprise"

Name of the plan

domains
string

Comma-separated list of domains

agent_email
string

Email of the agent

agent_name
string

Username of the agent

agent_password
string

Password of the agent

Responses

Request samples

Content type
application/json
{
  • "company_name": "Peter Pan"
}

Response samples

Content type
application/json
{
  • "agent_count": 15,
  • "company_name": "Peter Pan",
  • "client_key": "AOEUaoeuntsPDe"
}

Delete

Delete a Client

path Parameters
CLIENT_KEY
required
string
Example: 63668234b4aa19dd436e6a76ab8ae000
query Parameters
API_KEY
required
string
Example: API_KEY=3b57bd2db21c46d2875508b982968d26

Responses

Response samples

Content type
application/json
{
  • "response": "Client has been removed Successfully"
}

List Active Sessions for Reseller's Client

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

query Parameters
CLIENT_KEY
required
string
Example: CLIENT_KEY=00063668234b4aa19dd436e6a76ab8ae
API_KEY
required
string
Example: API_KEY=3b57bd2db21c46d2875508b982968d26
active_session
boolean
Default: false
year
integer <int32>
month
integer <int32>

Responses

Response samples

Content type
application/json
[]

Servers

List

Return a list of available servers

Responses

Response samples

Content type
application/json
[
  • {
    }
]

History

List

List history of all sessions

query Parameters
API_KEY
required
string
Example: API_KEY=3b57bd2db21c46d2875508b982968d26

Responses

Response samples

Content type
application/json
{
  • "next": "string",
  • "previous": "string",
  • "results": [
    ]
}

Filter session history

Filter session history results with query params. 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'
query Parameters
api_key
required
string
Example: api_key=3b57bd2db21c46d2875508b982968d26

REST API key of a company

active_session
required
boolean
Example: active_session=false

Filter active or inactive sessions. Takes true or false.

agent_id
required
string
Example: agent_id=null

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

pin
required
string
Example: pin=1234

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

tags
required
string
Example: tags=tag1

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

min_duration
required
number <double>
Example: min_duration=120

Filter by minimum duration of a session.

max_duration
required
number <double>
Example: max_duration=120

Filter by maximum duration of a session.

min_date
required
string
Example: min_date=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
required
string
Example: max_date=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

Responses

Response samples

Content type
application/json
{
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Webhooks

List

List all Webhooks

query Parameters
API_KEY
required
string
Example: API_KEY=3b57bd2db21c46d2875508b982968d26

Responses

Response samples

Content type
application/json
{
  • "count": 2,
  • "next": null,
  • "previous": null,
  • "results": []
}

Create

Create an Webhook

query Parameters
API_KEY
required
string
Example: API_KEY=3b57bd2db21c46d2875508b982968d26
Request Body schema: application/json
required
url
required
string

Webhook URL

category
required
string

Webhook category

enabled
required
boolean

Whether the webhook is enabled or not

ssl_verification
required
boolean

Whether to verify the server's TLS certificate or not

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Get by Id

Get Webhook Information

path Parameters
WEBHOOK_ID
required
string
Example: 1
query Parameters
API_KEY
required
string
Example: API_KEY=3b57bd2db21c46d2875508b982968d26

Responses

Response samples

Content type
application/json
{}

Update

Update a Webhook

path Parameters
WEBHOOK_ID
required
string
Example: 1
query Parameters
API_KEY
required
string
Example: API_KEY=3b57bd2db21c46d2875508b982968d26
Request Body schema: application/json
required
url
required
string

Webook URL

category
required
string

Webhook category

enabled
required
boolean

Whether the webhook is enabled or not

ssl_verification
required
boolean

Whether to verify the server's TLS certificate or not

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Delete an Webhook

Remove a Webhook by WEBHOOK_ID

path Parameters
WEBHOOK_ID
required
string
Example: 1
query Parameters
API_KEY
required
string
Example: API_KEY=3b57bd2db21c46d2875508b982968d26

Responses