1. Introduction

FeedbackStreet aims at being a complete platform and offers various endpoints and integration services. From authentication (with JWT) to error handling, this is a guide to work with our app’s RESTful APIs.

Our services run at https://app.feedbackstreet.com

2. HTTP verbs

FeedbackStreet adheres as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

PATCH

Used to update an existing resource, including partial updates

DELETE

Used to delete an existing resource

3. HTTP status codes

FeedbackStreet adheres as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

200 OK

The request completed successfully

201 Created

A new resource has been created successfully. The resource’s URI is available from the response’s Location header

204 No Content

An update to an existing resource has been applied successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information

401 Unauthorized

The request has not been applied because it lacks valid authentication credentials for the target resource

404 Not Found

The requested resource did not exist

4. Authentication (prerequisite)

This is a prerequisite for all the secured calls. With this call you will get a token to use under authorization header for other calls. The token will expire after a period, so eventual refresh needs to happen. You can get a new one under this API call. You can do this when status code 401 Unauthorized occurs.

CURL example
$ curl 'https://app.feedbackstreet.com/auth' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "username" : "user",
  "password" : "password"
}'
Request
POST /auth HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.feedbackstreet.com
Content-Length: 52

{
  "username" : "user",
  "password" : "password"
}
Response
{
  "token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..etc"
}
Table 1. Response Fields
Path Type Description

token

String

The bearer token to use with other calls

5. User

5.1. Sign Up

This endpoint allows you to sign up an user. The user will be provisioned in trial mode. The list of information to be supplied can be checked in table below.

Ensure that you are authenticated (you should send the bearer token together with this request)

Table 2. Headers
Name Description

Authorization

Holds the Bearer token used for authorization of request

CURL example
$ curl 'https://app.feedbackstreet.com/api/users/signup' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..etc' \
    -H 'Accept: application/json' \
    -d '{
  "username" : "user11",
  "password" : "123456678",
  "name" : "John",
  "lastName" : "Doe",
  "email" : "email@g.com"
}'
Request
POST /api/users/signup HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..etc
Accept: application/json
Host: app.feedbackstreet.com
Content-Length: 123

{
  "username" : "user11",
  "password" : "123456678",
  "name" : "John",
  "lastName" : "Doe",
  "email" : "email@g.com"
}
Table 3. Request Fields
Path Type Description

username

String

[Required] The username used for login

password

String

[Required] The password used for login (minimum length 8 characters)

email

String

[Required] The email of this user

name

String

[Required] The name of the user

lastName

String

The last name of the user

Response
HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: SAMEORIGIN
Table 4. Status Codes
Status code Description

200 OK

The user with the given email is already registered

400 Bad Request

The request was malformed. The response body will include an error providing further information

Error Example
{
   "errors":[
      {
         "code":"user.already_exists",
         "message":"Another user with the username user11 already exists"
      }
   ]
}

5.2. Find User By Email

This endpoint allows you to check if a user with the given email exists in the application. This search is bound to the users you had registered through the registration API.

Ensure that you are authenticated (you should send the bearer token together with this request)

Table 5. Headers
Name Description

Authorization

Holds the Bearer token used for authorization of request

CURL example
$ curl 'https://app.feedbackstreet.com/api/users/email@domain' -i -X GET \
    -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..etc' \
    -H 'Accept: application/json'
Request
GET /api/users/email@domain HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..etc
Accept: application/json
Host: app.feedbackstreet.com
Response
HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: SAMEORIGIN
Table 6. Status Codes
Status code Description

200 OK

The user with the given email is already registered

404 Not Found

The user you searched for does not exist

5.3. Retrieve Authenticated User

In order to get the current authenticated user (and then retrieve how many sms message you have left to consume) you can run the following api call under api/me

Ensure that you are authenticated (you should send the bearer token together with this request)

Table 7. Headers
Name Description

Authorization

Holds the Bearer token used for authorization of request

CURL example
$ curl 'https://app.feedbackstreet.com/api/me' -i -X GET \
    -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..etc' \
    -H 'Accept: application/json'
Request
GET /api/me HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..etc
Accept: application/json
Host: app.feedbackstreet.com
Response
{
  "created" : "2019-03-09T23:00:00Z",
  "username" : "user",
  "name" : "John",
  "lastName" : "Doe",
  "email" : "contact@feedbackstreet.com",
  "active" : true,
  "availableMessages" : 250
}
Table 8. Response Fields
Path Type Description

created

String

The user’s creation date (string date)

username

String

The user’s username (authentication)

name

String

The user’s first name

lastName

String

The user’s last name

active

Boolean

Whether this user is active or not

availableMessages

Number

The user’s SMS balance or how many SMS messages this user has left

email

String

The user’s email address

6. SMS

6.1. Bulk Message Sending

The following API call sends a SMS to multiple recipients at once. If you have enabled webhooks in FeedbackStreet Integration & Service page then you will receieve at the configured endpoint a report with information like errors, duration, individual recipient send status.

Ensure that you are authenticated (you should send the bearer token together with this request)

Table 9. Headers
Name Description

Authorization

Holds the Bearer token used for authorization of request

CURL example
$ curl 'https://app.feedbackstreet.com/api/bulkSMS' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..etc' \
    -H 'Accept: application/json' \
    -d '{
  "smsBody" : "Your feedback matters",
  "recipients" : [ "4075323433", "4013444534" ]
}'
Request
POST /api/bulkSMS HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..etc
Accept: application/json
Host: app.feedbackstreet.com
Content-Length: 90

{
  "smsBody" : "Your feedback matters",
  "recipients" : [ "4075323433", "4013444534" ]
}
Table 10. Request Fields
Path Type Description

smsBody

String

The SMS you want to send out to your recipients

recipients

Array

The list of phone numbers to send sms to

Response
HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: SAMEORIGIN