Motivosity API

AUTHENTICATION

To use the API, you can take one of three approaches:

1 - 'Sign In' - use this to authenticate directly as a user

2 - 'Service' - use this to access Motivosity for server side applications which will not be operating as a specific user

3 - OAuth2 - use this to access Motivosity for client side integrations (e.g. a web application needing access to Motivosity).

Each of these will be documented below:

Sign In

URL: /auth/v1/signin

Using this endpoint you can sign in  directly by passing in an authentication JSON. Since there is no OAuth 2 flow involved,  this endpoint only produces JWT access tokens with "user" role and "default" scope. Any admin privileges associated with the user signing in through this method will not be inherited. This token allows all basic user functions such as getting lists of people, pulling feeds, creating appreciations, etc.

METHOD: POST

INPUT:  { "username": "xyz", "password": "pass"}

Or if you build a client webapp : { "username": "xyz", "password": "pass", "appId": "the app id"}

NOTE:

All users signed in with the signin method will have 'user' privileges and will not inherit any other api privileges such as 'admin'.

The app_id is optional. If you are building a browser JS app then you probably need to register an application at Motivosity to be able to set your domain in our CORS system.

RESPONSE: { "success": true/false "messages": [{"message":"message text","severity":"info"}]

"Response": { "accessToken" : "...the.token...", "refreshToken": "...the.token...", "expiresIn" : 3600}

NOTES:

  • "messages" will be present if there is an error
  • Use the accessToken in subsequent requests in the 'Authorization' header with 'Bearer <accessToken>' as the value.
  • Use the refreshToken to generate new short term access token by calling auth/v1/refresh endpoint

POST /auth/v1/refresh

{ "appId": "optional app id","refreshToken": "the refresh token" }

COMMENT: The appId parameter is optional.

Use 'service accounts' for headless server side applications, use 'OAuth2' for client side access, and you can also choose our custom authentication endpoints for mobile apps and JS apps.

All endpoints are creating JWT based access tokens that will expire in a short amount of time. You can use locally the "expires_at" field to find out if a token is expired and if you get HTTP 401 response from the server side that also could signify that a token is expired. In both cases first try to get a new access token (service token) using the refresh token (secure token).  

Service accounts

If you are developing a server side (only) application for your own company then it is the best choice to use service accounts for accessing Motivosity APIs without real users. A service account represents a userless access to your company's data.

To get started, go to 'Setup' and then 'Integrations' in Motivosity. You will see an option to create a new authorization.

Once you create a new authorization, you will have an option to download the associated secure token and app id.

Please keep a secure token safe because it allows anybody to create short term access tokens for accessing your company's data at Motivosity.

A secure token is used for acquiring service access tokens during the communication. If an access token expires after 15 minutes (server returns with 401 status code) you can get a new one by calling this endpoint:

URL: auth/v1/servicetoken

METHOD: POST

CONTENT-TYPE: application/json

INPUT: {"appId":"app_id","secureToken":"your-token","appSecret":"optional-app-secret"}

RETURN: {"accessToken" : "...the.token...", "expiresIn" : "900"}

OAuth 2

Motivosity supports to access its API endpoints using the OAuth2 standard.

Authorization endpoint: /oauth2/v1/auth

Token exchange, token refresh endpoint: /oauth2/v1/token

You can check our demo application to learn to use OAuth2 with Motivosity:

https://github.com/scjnsn/Motivosity-Demo-app

Custom authentication

Besides Service accounts and Oauth2 we also support some custom authentication endpoint.

API Endpoints

The motivosity API allows you to easily integrate into other applications. You can use the api as an authenticated user, or as a non-user (such as a company activity monitor kiosk).

The base URL for all api calls is https://app.motivosity.com/api/v2

You can download an Insomnia json file pre-configured with all of the API calls here: Download insomnia file. You can download Insomnia application here.

ANNOUNCEMENTS

Saving Announcements

URL: /api/v2/announcement

Authorized roles: admin, leader, manager

It is a multipart request, the content type is "multipart/form-data".

METHOD: PUT

INPUT:

File part name: "photo"

The file the content is: binary data

JSON part name: "announcement"

JSON part content: `{"title":"Announcement Title","note":"Text Content"}`

RETURN: `{new announcement feed data}`

APPRECIATIONS

Create Appreciation

URL: /api/v2/appreciation

Required roles:  user

Required scopes: -

METHOD: PUT

INPUT:   { "amount":0, "amountType":"GM", "privateAppreciation":false, "note":"Just because", "companyValueID":"value-id", "companyValue":"Company value", "toUserIDs":["user-id"], "toUserEmails":["user@email.com"], "toUserPayrollIDs":["payroll-id"]}

NOTES:

  • The giver is going to be the signed in user
  • amountType may be 'GM' for 'Giving Money' or 'SM' for 'Spending Money'. This controls whether or not the user is using their giving or spending money for the appreciation
  • amount is optional
  • companyValueID is optional and can be used in place of companyValue
  • companyValue is optional and can be used in place of companyValueID
  • toUserIDs, toUserEmails, toUserPayrollIDs are just three different ways of looking up users

RETURN: `{appreciation details}`

Create Platform Appreciation

This endpoint differs from the standard /appreciation endpoint in that the appreciation is not being created by a user.

URL: /api/v2/platformappreciation

Authorized roles:  platform

METHOD: PUT

INPUT:   { "amount":0, "privateAppreciation":false, "note":"Just because", "companyValueID":"value-community-now", "companyValue":"Company value", "toUserIDs":["user-al-connor"], "toUserEmails":["andy@parks.com"], "toUserPayrollIDs":["3"]}

NOTES:

  • This type of appreciation is from an app and not from a user. This is useful for integrations that generate their own recognitions.
  • amount is optional
  • companyValueID is optional and can be used in place of companyValue
  • companyValue is optional and can be used in place of companyValueID
  • toUserIDs, toUserEmails, toUserPayrollIDs are just three different ways of looking up users

RETURN: `{appreciation details}`

AWARDS

Awards List

URL: /api/v2/award

Authorized roles: user

METHOD: GET

PARAMETERS:

  • awardScope - CMPY|DEPT|RLVT - limit awards list to company-wide, most relevant (global + department-specific), or department
  • Page - 0 - page number
  • sortBy - awardName <<or other field>> any field in the list
  • sortAsc - true|false

RETURN: `[{award list},...]`

Platform Awards List

URL: /api/v2/platformaward

Authorized roles: platform

METHOD: GET

PARAMETERS:

  • sortBy - awardName <<or other field>> any field in the list
  • sortAsc - true|false

RETURN: `[{award list},...]`

NOTE:

The list is limited to just central budget awards for the company

My Awards List

URL: /api/v2/award/myawards

Authorized roles: user

METHOD: GET

PARAMETERS:

  • page - 0 - page number
  • sortBy - awardName <<or other field>> any field in the list
  • sortAsc - true|false

RETURN: `[{award list},...]`

Give award

URL: /api/v2/award/{awardId}/giveaward

Authorized roles: user, platform

METHOD: PUT

INPUT: {"toUserIDs":["user-id","user-id"], "toUserEmails": [], "toUserPayrollIDs": [], "note":"the note", "amount": "10" }

NOTE:

  • All the "toUser..." fields can be used to identify the target users
  • If you use this from a userless service account, the award will be created by the app with 'App Name' as the creator. Also, only central-budget awards can be given by the userless the service account

RETURN: `[{list of of the given award}, ...]`

COMMENTS

Add a comment

URL: /api/v2/comment

Authorized roles: user

METHOD: POST

INPUT: `{"commentText":"message goes here","feedId":"feed-id"}

RETURN: `{feed data, comment data}`

COMMENTS:

  • feedId is is for the feed being commented on

Edit a comment

URL: /api/v2/comment/12345

Authorized roles: user

METHOD: POST

INPUT: `{"commentText":"message goes here"}

RETURN: true/false

COMMENTS:

  • 403 error if a user tries to edit a comment they don't own
  • Pass in 'id' if editing a comment

Delete a comment

URL: /api/v2/comment/{comment_id}

Authorized roles: user

METHOD: DELETE

RETURN: true/false

COMMENTS: 403 error if a user tries to edit a comment they don't own

COMPANY VALUES

Company Values List

URL: /api/v2/companyvalue

Authorized roles:  user, platform

METHOD: GET

RETURN: `{"id":"1234", "name":"Company Value", "description":"Description"}`

FEEDS

Recent feeds

URL: /api/v2/feed

Authorized roles: user, platform

METHOD: GET

PARAMETERS:

  • like -true|false
  • comment- true|false
  • scope - TEAM|EXTM|DEPT|CMPY
  • page - 0
  • pageLimit - 10
  • feedTypes - PRSN, GNRL, INST, RESP, BDAY, ANVY, ABOT, APPR, BDGE, ANNC, HGLT, GRUP`

RETURN: {"source" : {creator json data}, "subject" : {recipient json data}, "likes" : [list of people who like this], "comments" : [list of comments with commenter data], feed detail data}

NOTES:

  • This API is focused on return recent feeds only
  • 'like' and 'comment'  are optional and will include the list of users who like or who have comment on the feeds if set to true
  • 'scope' - controls whether the list of feeds belongs to the person's team, extended team, department, or company. The scope will be set to 'CMPY' by default or if the API is a service account
  • 'pageLimit' - defaults to 10 and is the number of feeds per page
  • 'feedTypes' - defauts to all the types that appear in the home feed. Setting this value to a comma-delimited list will include feeds that are personality types (PRSN), general (GNRL), announcements (ANNC), interests (INST), responsibilities (RESP), Birthdays (BDAY), Anniversary (ANVY), Highlight (HGLT), Appreciation (APPR), Award (BDGE), or Profile update (ABOT)

All feeds

URL: /api/v2/feed/all

Authorized roles: user, platform

METHOD: GET

PARAMETERS:

  • like -true|false
  • comment- true|false
  • scope - TEAM|EXTM|DEPT|CMPY
  • page - 0
  • pageLimit - 10
  • feedTypes - PRSN, GNRL, INST, RESP, BDAY, ANVY, ABOT, APPR, BDGE, ANNC, HGLT, GRUP`
  • startDate - string date
  • endDate - string date

NOTES:

This works like the recent feeds API, but will not default to any specific feed type or date range and will include future feeds created for upcoming anniversaries and birthdates

RETURN: {"source" : {creator json data}, "subject" : {recipient json data}, "likes" : [list of people who like this], "comments" : [list of comments with commenter data], feed detail data}

Finding a specific feed

URL: /api/v2/feed/1234

Authorized roles: user

METHOD: GET

COMMENTS: It will return feed with comments, likes, source user details, and recipient details

OUTPUT: `{feed detail data, "source" : {creator json data}, "subject" : {recipient json data}, "likes" : [list of people who like this], "comments" : [list of comments with commenter data]}`

Deleting a specific feed

URL: /api/v2/feed/1234

Authorized roles: admin

METHOD: DELETE

RETURN: Returns status entity

OUTPUT: `{"status":"success"|"failure", "message":"Return message"}`

COMMENTS: Rewinds all related financial transactions. Fails if the receiver has already spent the money.

Post Feed Comment

URL: /api/v2/feed/1234/comment

Authorized roles: user

METHOD: PUT

INPUT: `{"commentText":"hi"}`

OUTPUT: `{comment details, user: {creator details}}`

Like Feed

URL: /api/v2/feed/1234/like

Authorized roles: user

METHOD: PUT

OUTPUT: `{feed details, likes: [{liker details}], subject: {subject details}, commentList: [{comment details}] }`

LEADERBOARD

Leaderboard List

URL: /api/v2/leaderboard

Authorized roles: user, platform

METHOD: GET

PARAMETERS: type=month|year|top10,page=1

COMMENTS: page is optional, default is 0

RETURN: `{"leaderboardMTD":0, "leaderboardYTD":0"id", "firstName": "John", "lastName": "Smith", "avatarURL: "someURL", other user details}`

ORGANIZATION CHART

Find User in Organization

URL: api/v2/orgchart/find

Authorized roles: user, platform

Method: GET

PARAMETERS: userId=1234

COMMENTS: Returns an orgchart segment. Contains parent and peers of the user and children of the user.

RETURN A stringified JSON hierarchy structure

Supervisor

URL: api/v2/orgchart/sup

Authorized roles: user, platform

Method: GET

PARAMETERS: userId=1234

COMMENTS: Returns an orgchart segment. Contains parent and peers of the user.

RETURN A stringified JSON hierarchy structure

Direct Reports

URL: api/v2/orgchart/dr

Authorized roles: user, platform

Method: GET

PARAMETERS: userId=1234

COMMENTS: Returns an orgchart segment. Contains the direct children of the user.

RETURN A stringified JSON hierarchy structure

Partial Hierarchy

URL: api/v2/orgchart/partial

Authorized roles: user, platform

Method: GET

PARAMETERS: userId=1234,levels=3,rollupNumber=true|false

RETURN A stringified JSON hierarchy structure

COMMENTS: Returns a part of the organization hierarchy. The rolledHeadCount represents the total number of people under this person including themselves in the count

SATISFACTION SURVEY

Get the survey

URL: /api/v2/satisfactionsurvey

Authorized roles: user

METHOD: GET

PARAMETERS: `checkTime:**true**|false`

COMMENTS: when checkTime is true, the method first determines if it is time to show the satisfaction survey to the current user. If it is not time, the return will be `{}`.

RETURN: `{"questions":[["I tell my friends that Pawnee City is a great place to work.","I have a personal relationship with my boss and my team.","I am extremely satisfied working for Pawnee City.","If another company offered me a similar job for 10% more pay, I would take it.", "Custom question here"]}`

Adding a new survey

URL: /api/v2/satisfactionsurvey

Authorized roles: user

Required scopes: -

METHOD: PUT

INPUT: {"q1Score":5,"q2Score":1,"q3Score":1,"q4Score":2,"q5Score":3,"q6Score":4}

RETURN: `{"success"}`

STORE ITEMS

Listing Store Items

URL: /api/v2/store

Authorized roles: user

METHOD: GET

PARAMETERS: `type=digital|charity|local`

RETURN: `[{"id":null, "name":Walmart E-Gift Card", "imageURL":"image/url/here", "children":[{"id":"1234″,"name":"Walmart E-Gift Card", "price":10″, other item details},{"id":"5678″,"name":"Walmart E-Gift Card", "price":25", other item details}], "options":["price","size","color"], other parent details},{"id":"1234", "name":Amazon.com Gift Card", "imageURL":"image/url/here", "minPrice":1, "maxPrice":500, "price":}]`

COMMENTS: Some items are grouped under a 'parent' item. When an item is a parent, it won't have an id and will have a list of children. Some items can have a flexible price. When 'price' is empty the item has a flexible price and accepts a user-created price between minPrice and maxPrice. The 'options' list (on a parent only) contains what what differences exist among the children.

Purchasing Store Items

URL: /api/v2/store/purchase

Authorized roles: user

METHOD: POST

INPUT BODY: `{"id":"41214077-9705-ivnt-b6da-f1acf9c2bbd7", "currentQty":1}`

RETURN: `{"success":"true"}

USERS

Current  user

URL: /api/v2/user/me

Authorized roles: user

METHOD: GET

PARAMETERS:

COMMENTS: returns the current logged-in user.

RETURN: `{user data}`

List of Users

URL: /api/v2/user

Authorized roles: user, platform

METHOD: GET

PARAMETERS: sort=+firstName,-createdDate, scope=TEAM|EXTM|DEPT|CMPY, select=list,of,fields,to,include,page=0,pageLimit=20,name=name,department=deptname,directReports>0`

COMMENTS: sorting can be on any field, '+' (asc) is default. 'scope' is special in that it helps select a group relative to the current logged in user (team, extended team, department, company). 'select', when specified controls which fields are returned from the search - the list of available fields are those returned when 'select' is not included. 'name' is a special parameter that will attempt to do a like match on firstName, lastName, and preferredName. All other parameters will be assumed to be field names and matches (=, <, >).

RETURN: `[{user data}, {user data}]`

Search Users by name or email

URL: /api/v2/user/search

Authorized roles: user, platform

METHOD: GET

PARAMETERS: name=searchString&ignoreSelf=true/false

COMMENTS: The searchString can be a part of the name, full name or email.

RETURN: `[{user data}, {user data}]`

Sync Users

URL: /api/v2/user/sync

Authorized roles: admin, platform

METHOD: POST

INPUT BODY: [{"firstName":"Ron", "lastName":"Swanson","middleName":"","preferredName":"","hireDate":"9/7/2012","birthDate":"7/4/1967","department":"Parks","email":"ron@parks.com","countryCode":"USA","payrollID":"21″,"personalityType":"ISTJ","title":"Director","phone":"888-222-1111","supervisorPayrollID":"12","supervisorID":"supervisorid","keepWithDirectReports":true|false,"function":"UPDATE|CREATE|DELETE"}, ...]RETURNS: [{user data...}]

COMMENTS: This will synchronize data from a list of users being passed in. Any empty parameter will update the user data to empty. Any omitted parameter will not be considered. 'function' is optional, but helpful if you want to delete or create a user from the 'sync' command. When moving users around the org chart, update the supervisorPayrollID and determine if you want to move the user along with their direct reports, or to leave the direct reports in place by setting keepWithDirectReports. If the direct reports are left behind, they will be promoted one level to report to the moved user's old supervisor. This API should be called with a list of changes and should not be called individually for a list. To make individual one-off changes, use the move api

Move Users

URL: /api/v2/user/1234/move

Authorized roles: admin, platform

METHOD: POST

INPUT BODY: {"targetUserId":"new-direct-report-id","moveDirectReports":"true|false",}

RETURNS: [{user data...}]

COMMENTS: This will move a user from one direct report to another.

Recalculate Org Chart

URL: /api/v2/user/recalculateorgchart

Authorized roles: admin, platform

METHOD: GET

INPUT BODY: {}

RETURNS: {"success":true|false}

Change PayrollIDs

URL: /api/v2/user/changePayrollID

Authorized roles: admin, platform

METHOD: POST

INPUT BODY: [{"oldPayrollID":"old-system","payrollID":"21"}, ...]

RETURNS: [{user data...}]

COMMENTS: This will update the payrollID being used for a list of users. This is most likely only necessary when changing HRIS systems.

Individual User Data

URL: /api/v2/user/1234

Authorized roles: user, platform

METHOD: GET

PARAMETERS: select=list,of,fields

RETURNS: `{full user details}`

COMMENTS: 'select', when specified controls which fields are returned for the object - the list of available fields are those returned when 'select' is not included.

Current User Profile Data

URL: /api/v2/user/profile

Authorized roles: user

METHOD: GET

PARAMETERS:

RETURNS: `{user profile details}`

COMMENTS:

User Profile Data

URL: /api/v2/user/1234/profile

Authorized roles: user, platform

METHOD: GET

PARAMETERS:

RETURNS: `{user profile details}`

COMMENTS:

Save Current User Profile

URL: /api/v2/user/profile

Authorized roles: user

METHOD: POST

INPUT BODY, RETURN VALUE: Same as "Save User Profile"

Save User Profile

URL: /api/v2/user/1234/profile

Authorized roles: user, platform

METHOD: POST

INPUT BODY: {"newSupervisorID":"user-ron-swanson","user": {"location": "Pawnee","payrollID": "18","title": "Deputy Director","preferredName": "Leslie","lastName": "Knope","firstName": "Leslie","hireDateStr": "5/14/11","birthDateStr": "5/4/16","countryCode": "USA","department": "Parks","email": "leslie@parks.com","about": "parks,waffles,making friends and influencing people","personalityType": "ENFP","companyID": "parks"},"responsibilityList": [{"responsibilityName":"Citizen Outreach"},{"responsibilityName":"Making Pawnee great again"}]}

PARAMETERS: avatar

RETURNS: `{user profile details}`

COMMENTS: 'avatar' is a file input stream. If you set the user's supervisorID to a new supervisor, call

Current User Cash Balances

URL: /api/v2/usercash

Authorized roles: user

METHOD: GET

COMMENTS: no parameters available, only returns the user cash balances for the currently logged in user

RETURNS: `{"cashReceiving":10, "cashGiving":10}`

KIOSK

Motivosity has a kiosk mode that provides some basic information to be displayed on company lobby monitors, sharepoint portals, etc. The kiosk mode lets you access data without being logged in as a particular user. You get your kiosk ID in application Setup->Preferences

For an example of using the kiosk calls with angular.js, please download the attached file: kiosk-sdk

Kiosk Leaderboard

URL: api/v2/kiosk/KIOSK-ID/leaderboard

METHOD: GET

COMMENTS: returns the top 10 from the leaderboard

RETURN [ {...user data..., "leaderboardMTD": 680,"leaderboardYTD": 3400}]

Appreciations

URL: api/v2/kiosk/KIOSK-ID/feeds

Method: GET

COMMENTS: Returns the 20 most recent feeds for the company

RETURN {feed data...}