API Reference
Back to the USERSNAP website

REST API

👍

This is a gated feature

Please contact our support for more details. customer success team

Usersnap provides a way for you to use the platform's capabilities via a REST API. To begin with, you need to make sure that you're part of a plan that allows you to do that. Once you're a part of such a plan, you'll see an option to configure Rest API under settings, as shown below.

Usersnap uses Bearer authentication to protect its API endpoints. To be able to make requests to the platform API, you'll first need to generate a JWT secret on Usersnap.

Once this secret has been generated, you can use it to create JWTs on your own. The JWT secret that Usersnap creates is a shared secret between Usersnap and you, which is used to sign the JSON Web Tokens (JWTs) generated by you. This secret is used to verify the authenticity and integrity of the JWTs sent by you when making API requests to Usersnap.

For more information on JWTs, please check out the auth0 guide.

The header of the JWT needs to contain a kid field whose value is the JWT ID generated on Usersnap. The JWT header would look like this:

{
    "alg": "HS256",
    "typ": "JWT",
    "kid": "<JWT ID>"
}

🚧

Please, use HS256 as algorithm

Don't use HS512.

Finally, you must send this JWT as a bearer token in the Authorization header when making requests to Usersnap's API endpoints.

📘

Usersnap's REST API v0.1 documentation can be accessed on Swaggerhub.

Pagination and limits

/projects/{project-id}/feedbacks (GET)

By using your project id through this endpoint, you can receive a list of all the feedback items from that project.

For query parameters, please note:

  • limit: (Optional) The number of feedback items to return per page. The default value is 10. You can set it to any number between 1 and 100.
  • after: (Optional) A pagination cursor, which is the feedback_id of the last feedback item in the current page. Use this to fetch feedback items after the specified item, sorted by Feedback.updated_at in descending order by default.
  • before: (Optional) A pagination cursor, which is the feedback_id of the first feedback item in the current page. Use this to fetch feedback items before the specified item, sorted by Feedback.updated_at in descending order by default.

The endpoint uses cursor-based pagination, with the limit and after or before query parameters controlling the pagination. In the response, you'll find the next and previous keys, which provide information about the next and previous pages. The has_more boolean indicates if there are more pages available after the current page.

Feedback filtering

/projects/{project-id}/feedbacks/filter (POST)

If you want to receive a list of feedback items of a project with certain filters applied, you can use this endpoint.

For example, you can order the feedback items based on the creation time (instead of the last updated time) and apply a filter to only see those feedbacks that are set as "done":

{
	"order_by": {
		"direction": "desc",
		"order_by_type": "created_at"
	},
	"query": [
		{
			"filter_type": "state",
			"operator": "eq",
			"value": "done"
		}
	]
}

Please note, when making a POST request to this endpoint, it is required to include a JSON payload in the request body, even if it contains no data. In such cases, simply send an empty JSON object: {}. Failing to include a JSON body may result in an error or unexpected behavior.

/projects/{project-id}/feedbacks/filter/count (POST)

If you want to receive the number of available feedback items within a project based on certain filters, you can use this endpoint.

Please note that for this point, ordering only matters when the pagination is passed.

How to submit user feedback with rest API?

The endpoint to submit user feedback through the rest API can be found HERE.

Example call for the REST API

This is an example request on how you can post data via a CURL call. Is this how you can use it in your application and send feedback without using the feedback widgets.

# submit a feedback
curl 'https://platform.usersnap.com/v0.1/projects' \
-H 'Authorization: Bearer eyabc.eyabc.xyz'

The above can be used for both receiving and submitting feedback, but if there's no data provided and passed to this endpoint, then the request will be a 'GET' request.