Heads up! Need help getting started? Read our API introduction.
REMEMBER! You should never provide any links with support agent's access token to end users. You will provide to the user all the same access as your support agents have! In this case all your content can be downloaded or even deleted by the user. Instead of it you can use anonymous access token in combination with user's SSO token or provide a proxy link (without access token) to your side and make request from your server-side to hidden the access token from users.
Users
| Resource |
Description |
Authentication |
| GET users | List of all users in the project. | read |
| GET users/current | Displays current user profile details. | read |
| GET users/[user_id] | Displays user profile details. | read |
| PUT users/[user_id] | Update user profile details. | all |
| DELETE users/[user_id] | Delete user profile. | all |
| GET users/sso/[sso_guid] | Displays user profile details by SSO guid. | read |
| GET users/[user_id]/logout | Clear all sessions for selected user. | all |
| POST users/get_or_create | Get user by email or create a new user. | all |
| GET users/[user_id]/subscriptions | Displays user's subscriptions. | read |
| PUT users/[user_id]/subscriptions | Update user's subscription to an object updates. | all |
| POST users/[user_id]/group | Add user to user's group. | all |
| DELETE users/[user_id]/group | Delete user from user's group. | all |
Users groups
| Resource |
Description |
Authentication |
| GET users/groups | List of users groups. | all |
| POST users/groups | Create a new user group. | all |
| PUT users/groups | Update user group. | all |
| DELETE users/groups | Delete user group. | all |
Forums
| Resource |
Description |
Authentication |
| GET forums | List of all forums in the project. | read |
| POST forums | Creates a new forum. | all |
| PUT forums | Update a forum. | all |
| DELETE forums | Delete forum. | all |
Types, Categories, Tags ...
| Resource |
Description |
Authentication |
| GET forums/[forum_id]/types | List of topic types supported by selected forum. | read |
| GET forums/[forum_id]/types/[type_id]/statuses | List of topic statuses supported by selected type. | read |
| GET forums/[forum_id]/categories | List of selected forum categories. | read |
| GET forums/[forum_id]/tags | List of selected forum tags. | read |
| GET forums/[forum_id]/access_list | List of emails with access to the forum. For private forums only. | read, all |
| POST forums/[forum_id]/categories | Create new category. | write, all |
| POST forums/[forum_id]/tags | Create new tag. | write, all |
| POST forums/[forum_id]/access_list | Add emails to the forum access list. | write, all |
| DELETE forums/[forum_id]/access_list | Delete emails from the forum access list. | write, all |
| PUT forums/[forum_id]/categories | Update a category. | write, all |
| PUT forums/[forum_id]/tags | Update a tag. | write, all |
| DELETE forums/[forum_id]/categories | Delete a category. | write, all |
| DELETE forums/[forum_id]/tags | Delete a tag. | write, all |
Topics
| Resource |
Description |
Authentication |
| GET forums/[forum_id]/topics | List of topics belongs to the selected forum. Additional parameters. | read |
| POST forums/[forum_id]/topics | Creates a new topic. | write |
| PUT forums/[forum_id]/topics | Update topic. | write |
| GET forums/[forum_id]/users/[user_id]/topics | List of topics belongs to the selected forum & user. Additional parameters. | read |
| GET forums/[forum_id]/topics/search | Search topics in selected forum. | read |
| GET users/[user_id]/topics | List of topics belongs to the selected user. | read - self,
manage - all |
| GET categories/[category_id]/topics | List of topics belongs to the selected category. | read |
| GET tags/[tag_id]/topics | List of topics belongs to the selected tag. | read |
| GET topics/[topic_id] | Selected topic details. | read |
| DELETE topics/[topic_id] | Delete selected topic. | write |
Voters
| Resource |
Description |
Authentication |
| GET topics/[topic_id]/voters | Voters for selected topic. | read |
| GET topics/[topic_id]/comments/[comment_id]/voters | Voters for selected comment. | read |
Comments
| Resource |
Description |
Authentication |
| GET topics/[topic_id]/comments | List of comments related to the selected topic. | read |
| POST topics/[topic_id]/comments | Creates a new comment. | write |
| GET users/[user_id]/comments | List of comments belongs to the selected user. | read - self
all - all |
Files
| Resource |
Description |
Authentication |
| POST forums/[forum_id]/upload/[file|image] | Uploads a file to the forum to use in topics. | all |
Note:Files uploaded to a private ticket are not available to download without authentication (access check required). If you need to download such file via API you can use the file URL with user's SSO token or your project access token in GET parameters.
Example:
1. https://support.userecho.com/uploaded/file/1/1/1/12345678901234567890123456789012.pdf?sso_token=users_sso_token
2. https://support.userecho.com/uploaded/file/1/1/1/12345678901234567890123456789012.pdf?access_token=your_access_token
Webhooks
| Resource |
Description |
Authentication |
| GET hooks | List of all hooks in the project. | all |
| POST hooks | Creates a new webhook. | all |
| DELETE hooks/[hook_id] | Deletes a webhook. | all |
| GET hooks/events | List of all available events. | all |
Additional filter parameters
Most of "read" methods that return "List" allow to filter objects by common fields. Example: id, status, created, etc.
If you want to apply additional filter to request create filter parameter name:
- Start with "filter__" for a regular field or "filter__custom_fields__" for a custom field
- Add "[field_name]"
- (optional) Add filter condition like "__[condition]"
Allowed conditions:
- in - in list of values (pass comma separated string)
- gt - greater than
- gte - greater than or equal
- lt - lower than
- lte - lower than or equal
- contains - contains a string (case sensitive)
- icontains - contains a string (case insensitive)
- exact - equal to value (case sensitive)
- iexact - equal to value (case insensitive)
Negotiate conditions (NOT):
You can negotiate the filter value if you add "not" before condition above.
Example: filter__status__not__in=1,3,5 - Will select values where "status" field not equal to 1, 3 or 5.
Additional filter examples:
- filter__status=1
- filter__status__in=1,3,5
- filter__id__gte=10
- filter__id__not__in=11
- filter__created__gte=2014-03-17T03:34:29.320Z
- filter__updated__lt=2014-03-17
- filter__needs_review=0
- filter__header__icontains=test
Additional filter examples (for custom fields):
Note: Custom fields are saved as string. So, you should compare it as string.
- filter__custom_fields__cf_1=1
- filter__custom_fields__cf_1__icontains=test
How to make an API request on behalf of another user? (any project's user)
If your key has a "
all" access rights you are able to do API requests on behalf of any user of your project. You have a few ways to do it:
- Best way! Pass "sso_token" parameter. Add GET parameter "sso_token" for a user to your request. Or add parameter to your requests parameter for POST and PUT requests. If user does not exists API will create a new user and do action on behalf of this user. More information about SSO read in your project administrative section.
- Pass "user_sso_guid" parameter. Add GET parameter "user_sso_guid" to your request. Or add parameter to your requests parameter for POST and PUT requests. If user does not exists the action will be completed on behalf of API token user.
- Pass "user_id" parameter. Add GET parameter "user_id" to your request. Or add parameter to your requests parameter for POST and PUT requests. If user does not exists the action will be completed on behalf of API token user. For an Anonymous user set user_id to 0 (zero).
Our API is constantly developed and improved, we welcome your suggestions on our forum.