Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Retrieves a list of all users for the current account.
URL: /Users
Method: GET
Response:
Code: 200 OK
Content:
Retrieves a specific user by their SCIM ID or external ID.
URL: /Users/:id
Method: GET
URL Parameters: id=[string] (SCIM ID or external ID)
Creates a new user in the system.
URL: /Users
Method: POST
Data Params:
Updates an existing user's information.
URL: /Users/:id (SCIM ID or external ID)
Method: PUT
URL Parameters: id=[string] ( ID or external ID)
Deletes a user from the system.
URL: /Users/:id
Method: DELETE
URL Parameters: id=[string] ( ID or external ID)
In case of errors, the API will respond with an appropriate HTTP status code and a JSON object containing error details:
Common error scenarios:
User not found: 404 Not Found
Invalid input: 422 Unprocessable Entity
Attempting to delete account owner: 403 Forbidden
Internal server error: 500 Internal Server Error
The API uses SCIM 2.0 schemas and conventions.
User passwords are automatically generated and not returned in responses.
The active field in user objects indicates whether the user account is currently active.
The roles
When creating or updating a user, you can override the default roles by including a roles object in your request. The roles object should contain boolean values for each role you want to set:
If you don't include the roles object, the default roles will be applied (admin: false, member: true, editor: false).
If you include the roles object but omit a role, it will be set to false by default.
To assign a role to a user, set its value to true in the
Example:
This request would create a user with both admin and member roles, but without the editor role.
When creating or updating users, email validation is skipped to accommodate various SCIM client behaviors.
The account owner cannot be deleted through this API.
Response:
Code: 200 OK
Content: Same as individual user object in List Users response
Code: 201 Created
Content: Created user object
Data Params: Same as Create User
Response:
Code: 200 OK
Content: Updated user object
Response:
Code: 204 No Content
rolesTo remove a role from a user, set its value to false in the roles object.
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": <integer>,
"Resources": [
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "<string>",
"userName": "<string>",
"name": {
"formatted": "<string>",
"givenName": "<string>",
"familyName": "<string>"
},
"emails": [
{
"primary": true,
"value": "<string>",
"type": "work"
}
],
"active": <boolean>,
"roles": [<string>]
},
// ... more users
]
}{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "<string>"
"userName": "<string>",
"name": {
"givenName": "<string>",
"familyName": "<string>"
},
"emails": [
{
"value": "<string>",
"primary": true,
"type": "work"
}
],
"externalId": "<string>",
"active": <boolean>,
"roles": {
"admin": <boolean>,
"member": <boolean>,
"editor": <boolean>
}
}{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail": "<string>",
"status": "400"
}"roles": {
"admin": false,
"member": true,
"editor": false
}{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "john.doe@example.com",
"name": {
"givenName": "John",
"familyName": "Doe"
},
"emails": [
{
"value": "john.doe@example.com",
"primary": true,
"type": "work"
}
],
"active": true,
"roles": {
"admin": true,
"member": true,
"editor": false
}
}Some methods return paginated results. The formatting of a paginated result is always:
{
"pagination": {
"next_page": "...",
"prev_page": "...",
"last_page": "...",
"page": "...",
"items": "...",
"pages": "...",
"from": "...",
"to": "...",
"count": "..."
},
"records": [
...
]
}The pagination object contains metadata about the current page and links to other pages. The records array contains the actual data for the current page.
next_page: The number of the next page (if available)
prev_page: The number of the previous page (if available)
last_page: The number of the last page
page: The current page number
items: The number of items per page
pages: The total number of pages
from: The starting index of the current page's items
to: The ending index of the current page's items
count: The total number of items across all pages
Fields that are not applicable (e.g., prev_page on the first page) will be omitted from the response.
Let's say you make a GET request to a paginated endpoint:
You might receive a response like this:
To get the next page of results, you would make a request to:
GET /api/v2/users{
"pagination": {
"next_page": 2,
"last_page": 5,
"page": 1,
"items": 100,
"pages": 5,
"from": 1,
"to": 100,
"count": 450
},
"users": [
...
]
}GET /api/v2/users?page=2The Screendesk API uses Personal access tokens to authenticate requests.
To create an access token, sign in to your Screendesk account and go to the "Personal Settings" page. In the “” tab click the “Create an API Token” button.
Enter a token name and click on the “Create token” button. Once the token gets created, you will be able to copy the token to your clipboard.
You should now see the new token information in the table. You are able to view the raw token anytime you need to, as well as edit the token name and revoke the token.
Once you have created your access token, you can use it to make requests to the API. Requests are authenticated using . You must provide the access token in the Authorization header:
Authorization: Bearer {ACCESS_TOKEN}
Welcome to the Screendesk API! You can use this API to access our endpoints, such as the Screendesk API to get your recordings.
Welcome to the Screendesk API! You can use this API to access our endpoints, such as the Screendesk API to get your recordings.
To access our API, you need to be on the Screendesk Enterprise plan.
If you have any questions about the Enterprise plan, you can reach out to the .
The Screendesk API is REST-based and uses standard HTTP verbs and status codes. The API accepts form-encoded request bodies and returns JSON-encoded responses. All requests should be made over SSL.
If you have any question, please contact the Screendesk support.
The base URL to access the Screendesk API is https://app.screendesk.io.
For example, to access the recordings endpoint, just add the endpoint to the base URL: https://app.screendesk.io/api/v1/recordings.
Learn more about the endpoints you can use from the Screendesk API.
Learn about API errors.
Create an API access token and authenticate your API requests.
All responses from the API will include a standard HTTP successful or error status code. The successful status codes are as follows:
200 OK
The request was successful.
For errors, we include extra information as to why the request was not successful. The error response body will have the following format:
For example, if you try to retrieve a recording that does not exist, you will get the following error response:
The error status codes, along with their error types, are as follows:
{
"error": {
"message": "Descriptive information about the error",
"code": "HTTP error code",
}
}{
"error": {
"message": "Recording not found or does not exist",
"code": 404,
}
}400 Bad Request
The request cannot be accepted. Might be because the request body is empty when it should not be.
401 Unauthorized
The access token provided is invalid or deactivated.
404 Not Found
We could not find any record associated with this request.
500 Internal Server Error
Something went wrong with the Screendesk API.
All endpoints require authentication. Ensure you include the appropriate authentication headers with each request.
Please contact support@screendesk.io to get a token for SCIM. Token cannot be obtained through the Screendesk dashboard.
This document outlines the SCIM (System for Cross-domain Identity Management) API endpoints for user management. The API uses SCIM 2.0 schemas and conventions.
https://app.screendesk.io/api/v2/scim/
Returns a paginated list of recordings. Members see only their own recordings; admins see all recordings in the account.
API token obtained from Screendesk account settings
Page number (defaults to 1)
1Filter by an exact helpdesk ticket, conversation, issue, or object ID.
Results include a normalized metadata.helpdesk_info.ticket_id.
Optionally restrict ticket_id to one helpdesk provider.
freshchat is accepted as an alias for freshdesk_chat.
A paginated list of recordings
Total number of records
Current page number
Number of items per page
Total number of pages
Next page number (absent if on last page)
Previous page number (absent if on first page)
Last page number
Index of the first item on this page
Index of the last item on this page
Recording duration in seconds
Number of times the recording has been viewed
The type of recording
Human-readable source label (e.g. "Zendesk Ticket", "Intercom Operator")
Public URL to view the recording
Current Zendesk follow-up ticket ID when it differs from ticket_id
Raw console log output captured during the recording
Call duration in seconds (inferred from started_at and ended_at)
Invalid ticket search parameters
Error message
Invalid or missing API token
Error message
API access not enabled or insufficient permissions
Error message
GET /api/v2/recordings HTTP/1.1
Host: app.screendesk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"pagination": {
"count": 1,
"page": 1,
"items": 1,
"pages": 1,
"next_page": 1,
"prev_page": 1,
"last_page": 1,
"from": 1,
"to": 1
},
"records": [
{
"uuid": "123e4567-e89b-12d3-a456-426614174000",
"title": "text",
"summary": "text",
"description": "text",
"metadata": {
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"duration": 1,
"impressions_count": 1,
"recording_type": "Received",
"recording_source": "text",
"url": "https://example.com",
"helpdesk_info": {
"platform": "zendesk",
"conversation_id": "text",
"ticket_id": "text",
"active_ticket_id": "text",
"user_id": "text",
"operator_id": "text",
"customer_id": "text",
"issue_id": "text",
"object_id": "text"
}
},
"technical_details": {
"vendor": "text",
"ip_address": "text",
"timezone": "text",
"network_type": "text",
"isp": "text"
},
"console_logs": "text",
"customer": {
"email": "name@gmail.com"
},
"user": {
"email": "name@gmail.com",
"name": "text"
},
"room_insights": {
"started_at": "2026-01-01T00:00:00.000Z",
"ended_at": "2026-01-01T00:00:00.000Z",
"duration": 1,
"total_participant_minutes": 1,
"total_unique_participants": 1,
"participants_insights": [
{
"participant_id": "text",
"display_name": "text",
"role": "text",
"browser": "text",
"os": "text",
"device": "text",
"device_type": "text",
"user_agent": "text",
"joined_at": "2026-01-01T00:00:00.000Z",
"left_at": "2026-01-01T00:00:00.000Z"
}
]
}
}
]
}Returns a single recording by UUID.
API token obtained from Screendesk account settings
The recording's UUID
Recording details
Recording duration in seconds
Number of times the recording has been viewed
The type of recording
Human-readable source label (e.g. "Zendesk Ticket", "Intercom Operator")
Public URL to view the recording
Current Zendesk follow-up ticket ID when it differs from ticket_id
Raw console log output captured during the recording
Call duration in seconds (inferred from started_at and ended_at)
Invalid or missing API token
Error message
API access not enabled or insufficient permissions
Error message
Resource not found
Error message
GET /api/v2/recordings/{uuid} HTTP/1.1
Host: app.screendesk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"uuid": "123e4567-e89b-12d3-a456-426614174000",
"title": "text",
"summary": "text",
"description": "text",
"metadata": {
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"duration": 1,
"impressions_count": 1,
"recording_type": "Received",
"recording_source": "text",
"url": "https://example.com",
"helpdesk_info": {
"platform": "zendesk",
"conversation_id": "text",
"ticket_id": "text",
"active_ticket_id": "text",
"user_id": "text",
"operator_id": "text",
"customer_id": "text",
"issue_id": "text",
"object_id": "text"
}
},
"technical_details": {
"vendor": "text",
"ip_address": "text",
"timezone": "text",
"network_type": "text",
"isp": "text"
},
"console_logs": "text",
"customer": {
"email": "name@gmail.com"
},
"user": {
"email": "name@gmail.com",
"name": "text"
},
"room_insights": {
"started_at": "2026-01-01T00:00:00.000Z",
"ended_at": "2026-01-01T00:00:00.000Z",
"duration": 1,
"total_participant_minutes": 1,
"total_unique_participants": 1,
"participants_insights": [
{
"participant_id": "text",
"display_name": "text",
"role": "text",
"browser": "text",
"os": "text",
"device": "text",
"device_type": "text",
"user_agent": "text",
"joined_at": "2026-01-01T00:00:00.000Z",
"left_at": "2026-01-01T00:00:00.000Z"
}
]
}
}Updates a recording's title, summary, or description. Admin only.
API token obtained from Screendesk account settings
The recording's UUID
The recording title
A short summary
A detailed description
Updated recording
Recording duration in seconds
Number of times the recording has been viewed
The type of recording
Human-readable source label (e.g. "Zendesk Ticket", "Intercom Operator")
Public URL to view the recording
Current Zendesk follow-up ticket ID when it differs from ticket_id
Raw console log output captured during the recording
Call duration in seconds (inferred from started_at and ended_at)
Invalid or missing API token
Error message
API access not enabled or insufficient permissions
Error message
Resource not found
Error message
Validation error
Error message
PATCH /api/v2/recordings/{uuid} HTTP/1.1
Host: app.screendesk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 68
{
"recording": {
"title": "text",
"summary": "text",
"description": "text"
}
}{
"uuid": "123e4567-e89b-12d3-a456-426614174000",
"title": "text",
"summary": "text",
"description": "text",
"metadata": {
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"duration": 1,
"impressions_count": 1,
"recording_type": "Received",
"recording_source": "text",
"url": "https://example.com",
"helpdesk_info": {
"platform": "zendesk",
"conversation_id": "text",
"ticket_id": "text",
"active_ticket_id": "text",
"user_id": "text",
"operator_id": "text",
"customer_id": "text",
"issue_id": "text",
"object_id": "text"
}
},
"technical_details": {
"vendor": "text",
"ip_address": "text",
"timezone": "text",
"network_type": "text",
"isp": "text"
},
"console_logs": "text",
"customer": {
"email": "name@gmail.com"
},
"user": {
"email": "name@gmail.com",
"name": "text"
},
"room_insights": {
"started_at": "2026-01-01T00:00:00.000Z",
"ended_at": "2026-01-01T00:00:00.000Z",
"duration": 1,
"total_participant_minutes": 1,
"total_unique_participants": 1,
"participants_insights": [
{
"participant_id": "text",
"display_name": "text",
"role": "text",
"browser": "text",
"os": "text",
"device": "text",
"device_type": "text",
"user_agent": "text",
"joined_at": "2026-01-01T00:00:00.000Z",
"left_at": "2026-01-01T00:00:00.000Z"
}
]
}
}Streams the best available video file for a recording through the Screendesk API. The response body is the video binary, not JSON.
Screendesk returns the edited file when available, then the processed file, and finally the original upload. Use this endpoint for API/backend downloads such as curl, scripts, or server-side integrations.
API token obtained from Screendesk account settings
The recording's UUID
The recording video file
Attachment filename for the downloaded video
attachment; filename="customer-bug-report-00000000-0000-0000-0000-000000000000.mp4"File size in bytes
Invalid or missing API token
Error message
API access not enabled or insufficient permissions
Error message
Resource not found
Error message
Video file is not available yet
Error message
GET /api/v2/recordings/{uuid}/download HTTP/1.1
Host: app.screendesk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
binaryReturns the current timestamped transcript for a recording, including live recordings, with up to 100 segments per page. Edited transcript rows take precedence over processed rows. Older recordings fall back to their legacy transcript text.
API token obtained from Screendesk account settings
The recording's UUID
Transcript segment page number (defaults to 1)
1Recording transcript and its current availability status
Detected BCP 47 language code when available
Total number of records
Current page number
Number of items per page
Total number of pages
Next page number (absent if on last page)
Previous page number (absent if on first page)
Last page number
Index of the first item on this page
Index of the last item on this page
Invalid or missing API token
Error message
API access not enabled or insufficient permissions
Error message
Resource not found
Error message
GET /api/v2/recordings/{uuid}/transcript HTTP/1.1
Host: app.screendesk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"recording_uuid": "123e4567-e89b-12d3-a456-426614174000",
"status": "ready",
"language": "text",
"speaker_map": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"pagination": {
"count": 1,
"page": 1,
"items": 1,
"pages": 1,
"next_page": 1,
"prev_page": 1,
"last_page": 1,
"from": 1,
"to": 1
},
"segments": [
{
"start_seconds": 1,
"end_seconds": 1,
"text": "text",
"sentences": [
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}
]
}
]
}Returns a paginated list of all users in the account. Admin only.
API token obtained from Screendesk account settings
A paginated list of users
Total number of records
Current page number
Number of items per page
Total number of pages
Next page number (absent if on last page)
Previous page number (absent if on first page)
Last page number
Index of the first item on this page
Index of the last item on this page
The user's role in the account
Invalid or missing API token
Error message
API access not enabled or insufficient permissions
Error message
GET /api/v2/users HTTP/1.1
Host: app.screendesk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"pagination": {
"count": 1,
"page": 1,
"items": 1,
"pages": 1,
"next_page": 1,
"prev_page": 1,
"last_page": 1,
"from": 1,
"to": 1
},
"users": [
{
"email": "name@gmail.com",
"name": "text",
"has_profile_picture": true,
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"role": "admin",
"notifications": {
"notify_first_view": "Enabled",
"notify_all_recordings": "Enabled",
"notify_own_recordings": "Enabled"
}
}
]
}Returns a single user matching the provided email address. Admin only.
API token obtained from Screendesk account settings
The email address to search for
User details
The user's role in the account
Missing email parameter
Error message
Invalid or missing API token
Error message
API access not enabled or insufficient permissions
Error message
Resource not found
Error message
GET /api/v2/users/search?email=name%40gmail.com HTTP/1.1
Host: app.screendesk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"email": "name@gmail.com",
"name": "text",
"has_profile_picture": true,
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"role": "admin",
"notifications": {
"notify_first_view": "Enabled",
"notify_all_recordings": "Enabled",
"notify_own_recordings": "Enabled"
}
}