API Reference

Integrate your App with Fider

Overview

Welcome to the Fider API documentation.

The Fider API allows you to manage Posts and other data within your Fider instance in a simple, programmatic way using conventional HTTP requests. The endpoints are intuitive and powerful, allowing you to easily make calls to retrieve information or to execute actions.

Version

The API v1 was introduced on Fider v0.16.0. Make sure you’re running the latest version of Fider to leverage the API. All Cloud users on fider.io are already on the latest so you can start using it right now.

Request

Allowed HTTP Verbs are GET, POST, PUT and DELETE. All data must be sent as JSON.

Requests are sent to your Fider URL using the HTTP/HTTPS protocol.

Hosting URL Protocol
Cloud https://<subdomain>.fider.io or, if configured, your custom domain name (e.g: https://feedback.yourcompany.com) HTTPS only
Self-Hosted The URL you have configured HTTP or HTTPS

Response

Every response will be encoded with application/json and one of the following status code.

Status Code Description
200 OK Fider has accepted and processed your request, no error was encountered.
400 Bad Request Something is incorrect with your request, it might be missing a parameter or have an invalid value. See Error Messages below.
403 Forbidden API Key is not present or not allowed to perform the operation
404 Not Found The resource you're looking for doesn't exist.
500 Internal Error This generally indicates a server-side problem on Fider and it cannot fulfill your request currently.

Error Messages

Every 400 Bad Request response contains a JSON payload with details of what went wrong. Each error (object) contains a message (string) describing what is incorrect and may also contain a field (string) property. If the error object doesn’t contain the field, that’s a general error message.

{
  "errors": [
    {
      "field": "color",
      "message": "'dark' is an invalid color."
    },
    {
      "message": "A tag named 'suggestion' already exists."
    }
  ]
}

Authentication

Some API endpoint require authentication to work. This section explains how to make authenticated HTTP Requests to Fider.

The first step is to generate an API Key on your user profile. Sign in on Fider and navigate to Settings -> API Key and click on Regenerate API Key. An API Key will be shown. Take note of it as you won’t be able to retrieve this key again. If your Key is lost or has been compromised, you can always repeat this process to generate a new Key.

API Key is only available for users with Collaborator or Administrator role. Visitors are not allowed to use any authenticated API endpoint.

With the API Key on hands, it’s now possible to send authenticated requests the API using the Authorization HTTP Header as shown below.

Authorization: Bearer {api-key}

Impersonation

Every action performed via the API is executed under the User that generated the API Key. Fider also allow Administrators to impersonate another User and execute the operations under their behalf. To do so, add the following HTTP Header to the request.

Authorization: Bearer {api-key}
X-Fider-UserID: {target-user-id}

Roles

Fider has 3 user roles: Visitor, Collaborator and Administrator. These roles are used to restrict which actions each user can perform on the platform, be it via UI or via the API. Most operations can only be executed if the authenticated user has a specific role assigned. Every operation listed below will specify which role is required.

Best Practices

Service Account

A common approach when using Fider API is to sign in with a generic email address (like admin@yourcompany.com), then switch to an Administrator user and promote the new user to an Adminitrator as well. This allows you to use a common user account on all API operations, which having to use a personal user account.

How to properly use impersonation

We usually recommend the usage of impersonation in combination with the Create User API. This API will retrieve or create a new user and returns its User ID, which can then be used to impersonate that user.

As an example, imagine that you have a Mobile App that lists all your Fider posts and you want to let the user vote on it via your App. The first step is to call Create User with the name, email and an optional (altough recommended) reference ID. The API will the return a user ID. It might be a new user ID or an existing one, it doesn’t matter. Call the Add Vote API with the X-Fider-UserID parameter to execute this action under that user account.

Posts

A Post is new topic created by a user on the Feedback Site, while it’s usually a suggestion or feature request, sometimes it might also be a bug report or a complain.

List Posts

  • Authentication: Optional
GET /api/v1/posts

Parameters

Name Type Description
query string The search keywords
view string The filter and order to apply. Possible values are all, recent, my-votes, most-wanted, most-discussed, planned, started, completed, declined and trending. Default: all
limit integer The number of entries to return. Default: 30
tags string The list of tags to filter by. Separate multiple tags by ,

Example

GET <baseURL>/api/v1/posts?view=completed&query=open+links&limit=50

Response

200 OK
---
[
  {
    "id": 4315,
    "number": 65,
    "title": "Open links in new tab",
    "slug": "open-links-in-new-tab",
    "description": "When somebody pastes a link in the description of an item, it has to open link in a new tab so you don't lose focus in the app",
    "createdAt": "2018-05-16T13:50:34.579281Z",
    "user": {
      "id": 45642,
      "name": "Jon Snow",
      "role": "visitor"
    },
    "hasVoted": true,
    "votesCount": 34,
    "commentsCount": 0,
    "status": "completed",
    "response": {
      "text": "This is now available on `v0.14`. Links from any markdown text will open in a new tab.",
      "respondedAt": "2018-06-13T17:48:27.073178Z",
      "user": {
        "id": 8,
        "name": "Arya Stark",
        "role": "administrator"
      },
      "original": null
    },
    "tags": ["hard","critical"]
  },
  {
    ...
  }
]

Get a Post

  • Authentication: Optional
GET /api/v1/posts/{number}

Parameters

Name Type Description
number number Required. The number of the post to retrieve.

Example

GET <baseURL>/api/v1/posts/65

Response

200 OK
---
{
  "id": 4315,
  "number": 65,
  "title": "Open links in new tab",
  "slug": "open-links-in-new-tab",
  "description": "When somebody pastes a link in the description of an item, it has to open link in a new tab so you don't lose focus in the app",
  "createdAt": "2018-05-16T13:50:34.579281Z",
  "user": {
    "id": 45642,
    "name": "Jon Snow",
    "role": "visitor"
  },
  "hasVoted": true,
  "votesCount": 34,
  "commentsCount": 0,
  "status": "completed",
  "response": {
    "text": "This is now available on `v0.14`. Links from any markdown text will open in a new tab.",
    "respondedAt": "2018-06-13T17:48:27.073178Z",
    "user": {
      "id": 8,
      "name": "Arya Stark",
      "role": "administrator"
    },
    "original": null
  },
  "tags": ["hard","critical"]
}

Create a Post

  • Authentication: Required
POST /api/v1/posts

Parameters

Name Type Description
title string Required. The title of the post.
description string The description of the post.

Example

POST <baseURL>/api/v1/posts
---
{
  "title": "Allow users to edit any comment",
  "description": "This is useful to fix some minor typos or introduce more details"
}

Response

200 OK
---
{
  "id": 6848,
  "number": 47,
  "title": "Allow users to edit any comment",
  "slug": "allow-users-to-edit-any-comment"
}

Edit a Post

  • Authentication: Required
  • Required Role: Collaborator or Administrator
PUT /api/v1/posts/{number}

Parameters

Name Type Description
number number Required. The number of the post to be edited.
title string Required. The title of the post.
description string The description of the post.

Example

POST <baseURL>/api/v1/posts/47
---
{
  "title": "Allow users to edit their own comments",
  "description": "This is useful to fix some minor typos or introduce more details"
}

Response

200 OK
---
{}

Delete a Post

  • Authentication: Required
  • Required Role: Administrator
DELETE /api/v1/posts/{number}

Parameters

Name Type Description
number number Required. The number of the post to be deleted.
text string The reason why this post is being deleted.

Example

DELETE <baseURL>/api/v1/posts/47
---
{
  "text": "this is spam!"
}

Response

200 OK
---
{}

Respond to a Post

  • Authentication: Required
  • Required Role: Collaborator or Administrator
PUT /api/v1/posts/{number}/status

Parameters

Name Type Description
number number Required. The number of the post to add a response.
status string Required.The new status of the post. Possible values are open, planned, started, completed, declined and duplicate
text string An optional description of what is the status on this post. This is made visible to all visitors on the website.
originalNumber number The number of the post to merge this into. This parameter Required when status is duplicate.

Example #1

PUT <baseURL>/api/v1/posts/47/status
---
{
  "status": "declined",
  "text": "this is spam!"
}

Example #2

PUT <baseURL>/api/v1/posts/47/status
---
{
  "status": "duplicate",
  "originalNumber": 84
}

Response

200 OK
---
{}

Votes

Vote on a Post

  • Authentication: Required

When casting a vote upon a post, the vote is registered under the current authenticated user. Impersonate another user to vote on behalf of them.

POST /api/v1/posts/{number}/votes

Parameters

Name Type Description
number number Required. The number of the post to vote on.

Example

POST <baseURL>/api/v1/posts/47/votes

Response

200 OK
---
{}

Remove Vote from on a Post

  • Authentication: Required

When removing the vote from a post, the vote is removed from the current authenticated user. Impersonate another user to remove votes on behalf of them.

DELETE /api/v1/posts/{number}/votes

Parameters

Name Type Description
number number Required. The number of the post to have the vote removed.

Example

DELETE <baseURL>/api/v1/posts/47/votes

Response

200 OK
---
{}

List Votes of a Post

  • Authentication: Required
  • Required Role: Collaborator or Administrator
GET /api/v1/posts/{number}/votes

Parameters

Name Type Description
number number Required. The number of the post to list the votes.

Example

GET <baseURL>/api/v1/posts/47/votes

Response

200 OK
---
[
  {
    "createdAt":"2018-11-28T12:18:26.95415Z",
    "user":{
      "id":1234,
      "name":"Jon Snow",
      "email":"jon.snow@got.com"
    }
  },
  {
    "createdAt":"2018-11-28T15:45:45.612288Z",
    "user":{
      "id":5678,
      "name":"Arya Stark",
      "email":"arya.stark@got.com"
    }
  }
]

Comments

List Comments

  • Authentication: Optional
GET /api/v1/posts/{number}/comments

Parameters

Name Type Description
number number Required. The number of the post to get comments from.

Example

GET <baseURL>/api/v1/posts/47/comments

Response

[
  {
    "id":67,
    "content":"Sounds good, right?",
    "createdAt":"2017-07-26T04:15:22.72261Z",
    "user":{
      "id":54,
      "name":"Michael Jackson",
      "role":"visitor"
    }
  },
  {
    "id":68,
    "content":"Definitely. Just do it!",
    "createdAt":"2017-07-26T06:49:03.951383Z",
    "user":{
      "id":23,
      "name":"Darth Vader",
      "role":"visitor"
    },
    "editedAt":"2018-09-29T17:37:59.516909Z",
    "editedBy":{
      "id":1,
      "name":"Jon Snow",
      "role":"administrator"
    }
  }
]

Get a Comment

  • Authentication: Optional
GET /api/v1/posts/{number}/comments/{id}

Parameters

Name Type Description
number number Required. The number of the post to retrieve.
id number Required. The id of the comment to be retrieved.

Example

GET <baseURL>/api/v1/posts/47/comments/68

Response

200 OK
---
{
  "id":68,
  "content":"Definitely. Just do it!",
  "createdAt":"2017-07-26T06:49:03.951383Z",
  "user":{
    "id":23,
    "name":"Darth Vader",
    "role":"visitor"
  },
  "editedAt":"2018-09-29T17:37:59.516909Z",
  "editedBy":{
    "id":1,
    "name":"Jon Snow",
    "role":"administrator"
  }
}

Add a Comment

POST /api/v1/posts/{number}/comments

Parameters

Name Type Description
number number Required. The number of the post to add the comment.
content string Required. The content of the comment.

Example

POST <baseURL>/api/v1/posts/47/comments
---
{
  "content": "Agreed, we'll soon need to act on this"
}

Response

200 OK
---
{
  "id":5675
}

Edit a Comment

  • Authentication: Required
  • Required Role: Collaborator or Administrator.
PUT /api/v1/posts/{number}/comments/{id}

Parameters

Name Type Description
number number Required. The number of the post that has given comment.
id number Required. The id of the comment to be edited.
content string Required. The new content of the comment.

Example

POST <baseURL>/api/v1/posts/47/comments/5675
---
{
  "content": "Agreed, we need to act on this as soon as possible"
}

Response

200 OK
---
{}

Delete a Comment

  • Authentication: Required
  • Required Role: Collaborator or Administrator.
DELETE /api/v1/posts/{number}/comments/{id}

Parameters

Name Type Description
number number Required. The number of the post that has given comment.
id number Required. The id of the comment to be edited.

Example

DELETE <baseURL>/api/v1/posts/47/comments/5675

Response

200 OK
---
{}

Users

List Users

  • Authentication: Required
  • Required Role: Collaborator or Administrator
GET /api/v1/users

Example

GET <baseURL>/api/v1/users

Response

200 OK
---
[
  {
    "id": 3,
    "name": "Arya Stark",
    "role": "administrator",
    "status": "active",
  },
  {
    "id": 5,
    "name": "Jon Snow",
    "role": "visitor",
    "status": "active"
  },
  {
    "id": 24,
    "name": "The Queen",
    "role": "collaborator",
    "status": "blocked"
  },
  {
    ...
  }
]

Create a User

  • Authentication: Required
  • Required Role: Administrator
POST /api/v1/users

The Create User API will only create a new user if it cannot find an existing user with given email or reference ID. If the user already exists on Fider, the ID of the existing user is returned instead of creating a new user.

The ID returned by this API can be used to impersonate that user. Read more about impersonation.

Parameters

Name Type Description
name string Required. The name of the user.
email string The email of the user.
reference string A unique ID for the user in another system.

Example

POST <baseURL>/api/v1/users
---
{
  "name": "Jon Snow",
  "email": "jon.snow@got.com",
  "reference": "CRM-817453"
}

Response

200 OK
---
{
  "id": 6332
}

Tags

List Tags

  • Authentication: Optional
GET /api/v1/tags

The list of tags returned by this endpoint depends on the role of the authenticated user. Private Tags are only returned for users with either administrator or collaborator role.

Example

GET <baseURL>/api/v1/tags

Response

200 OK
---
[
  {
    "id": 8,
    "name": "Under Consideration",
    "slug": "under-consideration",
    "color": "87BE1F",
    "isPublic": true
  },
  {
    "id": 86,
    "name": "Hard",
    "slug": "hard",
    "color": "E60737",
    "isPublic": false
  }
]

Create a Tag

  • Authentication: Required
  • Required Role: Administrator
POST /api/v1/tags

Parameters

Name Type Description
name string Required. The display name of the tag.
color string Required. The Hex color of the tag (without #).
isPublic boolean Required. true for public tags or false for private tags.

Example

POST <baseURL>/api/v1/tags
---
{
  "name": "impact: big", 
  "color": "FE422D", 
  "isPublic": true
}

Response

200 OK
---
{
  "id": 1003,
  "name": "impact: big",
  "slug": "impact-big",
  "color": "FE422D",
  "isPublic": true
}

Edit a Tag

  • Authentication: Required
  • Required Role: Administrator
PUT /api/v1/tags/{slug}

Parameters

Name Type Description
slug string Required. The slug of the tag to be edited.
name string Required. The display name of the tag.
color string Required. The Hex color of the tag (without #).
isPublic boolean Required. true for public tags or false for private tags.

Example

PUT <baseURL>/api/v1/tags/impact-big
---
{
  "name": "impact: small", 
  "color": "063589", 
  "isPublic": true
}

Response

200 OK
---
{
  "id": 1003,
  "name": "impact: small",
  "slug": "impact-small",
  "color": "063589",
  "isPublic": false
}

Delete a Tag

  • Authentication: Required
  • Required Role: Administrator
DELETE /api/v1/tags/{slug}

Parameters

Name Type Description
slug string Required. The slug of the tag to be deleted.

Example

DELETE <baseURL>/api/v1/tags/impact-small

Response

200 OK
---
{}

Tag a Post

  • Authentication: Required
  • Required Role: Collaborator or Administrator
POST /api/v1/posts/{number}/tags/{slug}

Parameters

Name Type Description
number number Required. The number of the post to add the tag.
slug string Required. The slug of the tag to be added.

Example

POST <baseURL>/api/v1/posts/47/tags/impact-big

Response

200 OK
---
{}

Untag a Post

  • Authentication: Required
  • Required Role: Collaborator or Administrator
DELETE /api/v1/posts/{number}/tags/{slug}

Parameters

Name Type Description
number number Required. The number of the post to remove the tag.
slug string Required. The slug of the tag to be removed.

Example

DELETE <baseURL>/api/v1/posts/47/tags/impact-big

Response

200 OK
---
{}

Invitations

Send a Sample

Sample invitations are example of invitations emails that are sent to current authenticated user’s email. Use it to see how the email looks like before sending to other users.

  • Authentication: Required
  • Required Role: Collaborator or Administrator
POST /api/v1/invitations/sample

Parameters

Name Type Description
subject number Required. The subject of the email to be sent.
message string Required. The content of the email to be sent. The message must include the %invite% placeholder, which will be replaced a secure invitation link.

Example

POST <baseURL>/api/v1/invitations/sample
---
{
  "subject": "Share your ideas and thoughts about Fider",
  "message": "Hi,\n\nAt **Fider** we take feedback very seriously, which is why we've launched a space where you can vote, discuss and share your ideas and thoughts about our products and services.\n\nWe'd like to extend an invite for you to join this community and raise awareness on topics you care about!\n\nTo join, click on the link below.\n\n%invite%\n\nRegards,\nFider"
}

Response

200 OK
---
{}

Send an Invite

  • Authentication: Required
  • Required Role: Collaborator or Administrator
POST /api/v1/invitations/send

Parameters

Name Type Description
recipients array of strings Required. The list of email addresses to send an invite.
subject number Required. The subject of the email to be sent.
message string Required. The content of the email to be sent. The message must include the %invite% placeholder, which will be replaced a secure invitation link.

Example

POST <baseURL>/api/v1/invitations/send
---
{
  "recipients":["jon.snow@got.com","arya.stark@got.com"],
  "subject": "Share your ideas and thoughts about Fider",
  "message": "Hi,\n\nAt **Fider** we take feedback very seriously, which is why we've launched a space where you can vote, discuss and share your ideas and thoughts about our products and services.\n\nWe'd like to extend an invite for you to join this community and raise awareness on topics you care about!\n\nTo join, click on the link below.\n\n%invite%\n\nRegards,\nFider"
}

Response

200 OK
---
{}