Overview

The Moodforce API gives you access to secure content and features for use in your own app. It strives to be RESTful.

Introduction

The Moodforce API is the primary way for third-party apps to get data in and out of the Moodforce platform. The API is still in beta and under heavy construction. If you think you are missing a specific endpoint please send a mail to info@moodforce.com and we'll get in touch with you as soon as possible.

If you think you have found a security vulnerability please contact us at info@moodforce.com and we will contact you straight away.

When making request to our endpoints please prefix the path with https://moodforce.com/api

Authentication

Moodforce uses OAuth 2.0 to authenticate connections that use the Moodforce APIs. OAuth 2 is an open protocol for authentication used with web, mobile, and desktop applications. Every use of Moodforce APIs requires authentication so that Moodforce can ensure that only authorized users can interact with the content. OAuth 2 is the protocol that Moodforce uses for such authentication. Moodforce uses the standard OAuth 2 three-legged authentication process. To gain access to our API you first need to create an OAuth client on your member profile page after logging in on moodforce.com.

Once a client has been created, you may use the client ID and secret to request an authorization code and access token from your application. First, the consuming application should make a redirect request to https://moodforce.com/oauth/authorize endpoint like so:


$query = http_build_query([
    'client_id' => 'client-id',
    'redirect_uri' => 'http://example.com/callback',
    'response_type' => 'code',
    'scope' => '',
]);

return redirect('https://moodforce.com/oauth/authorize?'.$query);
                        

If the user approves the authorization request, they will be redirected back to the consuming application. The consumer should then issue a POST request to https://moodforce.com/oauth/token to request an access token. The request should include the authorization code that was issued by Moodforce when the user approved the authorization request. In this example, we'll use the Guzzle HTTP library to make the POST request:


$http = new GuzzleHttp\Client;

$response = $http->post('https://moodforce.com/oauth/token', [
    'form_params' => [
        'grant_type' => 'authorization_code',
        'client_id' => 'client-id',
        'client_secret' => 'client-secret',
        'redirect_uri' => 'http://example.com/callback',
        'code' => $request->code,
    ],
]);

return json_decode((string) $response->getBody(), true);
                        

This request will return a JSON response containing access_token, refresh_token, and expires_in attributes. The expires_in attribute contains the number of seconds until the access token expires. You can use the access_token to make authenticated call's to our API.

Rate limits

In certain cases, Moodforce needs to enforce rate-limiting in order to prevent abuse by third-party services and/or users. In the event that an excessive level of usage is reached, a standard 429 Too Many Requests error will be returned, with an indication of when to retry the request. In the event that back-to-back 429s are received, an exponential backoff algorithm is recommended.

Scopes

Scopes allow your API clients to request a specific set of permissions when requesting authorization to access an account. Our API currently does not differentiate between read/write access or access to specific endpoint's. Please use the * scope for all authorization requests.

User endpoint

The user endpoint returns or stores data for the currently authenticated user.

POST user/register

An admin is able to send invitation to the email adress of employee's to invite them to the Moodforce application. This endpoint allows you to exchange the invitation for a user object.

The request will be validated against the following rules:

[
'name'              => 'required|max:255',
'email'             => 'required|email|max:255|unique:users',
'password'          => 'required|min:6',
'activation_code'   => 'required|exists:invitations,activation_code',
]
                            

POST user/devices/register

Moodforce will try to send a push notification to the users mobile when a new question is asked. This endpoint allows your application to register a new mobile device for this user. You will need to provide us with a ionic push token!

The request will be validated against the following rules:

[
'device_uuid'   => 'required|max:255',
'push_token'    => 'required|max:255',
'manufacturer'  => 'max:255',
'device_model'  => 'max:255',
'platform'      => 'max:255',
'version'       => 'max:255'
]
                            

GET user/feed

Returns a feed of answers (with their comments) of other users in the authenticated user groups.

The request will be validated against the following rules:

[
 'limit' => 'max:100'
]
                            

GET user/answers

Returns the answers given by the authenticated user. Anonymous given answers will not be returned!

The request will be validated against the following rules:

[
 'limit' => 'max:100'
]
                            

GET user/answers/unanswered

Returns open questions for the authenticated user. Questions will decay over time specified by the admin.

The request will be validated against the following rules:

[
 'limit' => 'max:100'
]
                            

Answers endpoint

The answer endpoint allows you the fetch a specific answer (up-on a notification f.e.) including all attached comments. This answers can still be un-answered or already answered by the authenticated user.

GET answers/{id}

Returns the answer with the specified id including the attached comments.

The request will be validated against the following rules:

[
 'id' => 'exists'
]
                            

POST answers/{id}/comment

Attach a new comment to the specified answer.

The request will be validated against the following rules:

[
 'id'   => 'exists',
 'body' => 'required|string|max:1000'
]
                            

Missions endpoint

The mission endpoint allows you to get all the missions from an group where the user is opt in and to create a mission.

GET missions

Returns all the missions from the user from the group.

The request will be validated against the following rules:

[
   'limit' => 'max:100'
]
                            

POST missions

Attach a new mission to a specified group.

The request will be validated against the following rules:

[
  'title'   => 'required|string|max:255',
  'group_id'   => 'required|int',
  'category_id'   => 'required|int',
]
                            

Categories endpoint

Question and answers within the Moodforce system are attached to a category. Categories allows us to generate insights for you. You will need to know which categories are existing in the system to request aggegrated statistics for example.

GET /categories

Returns all the available categories

Data endpoint

The data endpoint is used to generate dashboards. It will return aggegrated results for the specified account, user, group or category.

GET data/moving-average

Returns the moving average for the specified object

The request will be validated against the following rules:

[
 'limit' => 'max:100'
]
                            

The request must be filled with one or more of the following parameters:

  • account_slug
  • group_id
  • category_id
  • group_by day, month, or year