API Reference

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.

Response

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

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 Administrator as well. This allows you to use a common user account on all API operations, without 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

• List Posts
• Get a Post
• Create a Post
• Edit a Post
• Delete a Post
• Respond to a Post

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

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

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

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

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

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

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
• Remove Vote from a Post
• List Votes of a Post

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

Example

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

Response

200 OK
---
{}

Remove Vote from 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

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

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
• Get a Comment
• Add a Comment
• Edit a Comment
• Delete a Comment

List Comments

• Authentication: Optional

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

Parameters

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

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

• Authentication: Required

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

Parameters

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

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

Example

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

Response

200 OK
---
{}

Users

• List Users
• Create a User

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

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
• Create a Tag
• Edit a Tag
• Delete a Tag
• Tag a Post
• Untag a Post

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

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

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

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

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

Example

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

Response

200 OK
---
{}

Invitations

• Send a Sample
• Send an Invite

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

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

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
---
{}