Motivosity API

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/v1

AUTHENTICATION

URL: api/v1/auth/token
METHOD: POST
CONTENT-TYPE: application/json
INPUT: {“username”:”user@company.com”,”password”:”mypass”}
RETURN: {“message” : “authentication succesfull”, “success” : “true”, “token” : “41749719-0004-udef-8782-f3e70353bcea”, “expires” : “2014-12-02 06:13:10”}
COMMENTS: “token” is used as a parameter in subsequent requests for user credentials and is passed as a request parameter of “access_token”

ANNOUNCEMENTS

Getting a list of announcements

URL: /api/v1/announcement
PARAMETERS: `page=1`
METHOD: GET
RETURN: `{announcement data}`

Saving Announcements

URL: /api/v1/announcement
METHOD: PUT
INPUT: `{“title”:”Announcement Title”,”note”:”Text Content”}`
RETURN: `{new announcement data}`

APPRECIATIONS

Save Appreciation

URL: /api/v1/user/1234/appreciation
METHOD: PUT
INPUT: `{“note”:”Thanks”,”companyValueID”:”40672358-3075-cval-a7a2-89e44aaab4c8″,”amount”:1}`
COMMENTS: If a user appreciates themselves, there will be an invalid appreciation error returned
RETURN: `{appreciation details}`

COMPANY VALUES

Company Values List

URL: /api/v1/companyvalue
METHOD: GET
RETURN: `{“id”:”1234″, “name”:”Company Value”, “description”:”Description”}`

COMMENTS

Editing an existing comment

URL: /api/v1/comment
METHOD: POST
INPUT: `{“id”:”1234″, “commentText”:”message goes here”}
RETURN: `{comment data}`
COMMENTS: 403 error if a user tries to edit a comment they don’t own

FEEDS

Getting list of feeds

URL: /api/v1/feed/
METHOD: GET
PARAMETERS: `like=true|false, comment=true|false, scope=TEAM|EXTM|DEPT|**CMPY**, page=0|feedType=PRSN,GNRL,GOAL,INST,BDAY,ANVY,IDEA,ABOT,APPR,BDGE`
COMMENTS: Like is an optional parameter that will include a list of users who like the feed when set to true. Comment is an optional parameter that will include a list of comments with each feed when set to true. Scope controls what is in the feed list: Just your team, your extended team, your department, or your company. ‘feedType’ is optional and multiple types can be comma-separated. The codes are for personality type, general, goal completion, interest group, birthday, anniversary, idea, about, appreciation received, and badge received respectively. Not including a feedType returns all of the above types of feeds. The default page size is 15 items. Page parameter controls which page of results you see.
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/v1/feed/1234
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/v1/feed/1234
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/v1/feed/1234/comment
METHOD: PUT
INPUT: `{“commentText”:”hi”}`
OUTPUT: `{comment details, user: {creator details}}`

Like Feed

URL: /api/v1/feed/1234/like
METHOD: PUT
OUTPUT: `{feed details, likes: [{liker details}], subject: {subject details}, commentList: [{comment details}] }`

LEADERBOARD

Leaderboard List

URL: /api/v1/leaderboard
METHOD: GET
PARAMETERS: `page=1`
COMMENTS: page is optional, default is 1
RETURN: `{“leaderboardMTD”:0, “leaderboardYTD”:0″id”, “firstName”: “John”, “lastName”: “Smith”, “avatarURL: “someURL”, other user details}`

SATISFACTION SURVEY

Get the survey

URL: /api/v1/satisfactionsurvey
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/v1/satisfactionsurvey
METHOD: PUT
INPUT: `{“answers”:[5,4,5,5,3]}`
RETURN: `{“success”}`

STORE ITEMS

Listing Store Items

URL: /api/v1/store
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/v1/store/purchase
METHOD: POST
INPUT BODY: `[{“id”:”41214077-9705-ivnt-b6da-f1acf9c2bbd7″, “currentQty”:1}],[{“id”:”41214077-8055-ivnt-9233-0759fa387d62″, “currentQty”:2}]`
RETURN: `{“success”:”true”}

USERS

List of Users

URL: /api/v1/user
METHOD: GET
PARAMETERS:
COMMENTS: returns the current logged-in user.
RETURN: `{user data}`

List of Users

URL: /api/v1/user/list
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}`

 

Sync Users

URL: /api/v1/user/sync
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″,
“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.

Change PayrollIDs

URL: /api/v1/user/changeExternalID
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/v1/user/1234
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.

User Profile Data

URL: /api/v1/user/1234/profile
METHOD: GET
PARAMETERS:
RETURNS: `{user profile details}`
COMMENTS:

SaveUser Profile

URL: /api/v1/user/1234/profile
METHOD: POST
INPUT BODY: {
“newSupervisorID”:”user-ron-swanson”,
“moveUser”:true,
“moveDirectReports”:true,
“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. Do not include ‘moveUser’ if you aren’t trying to move the user to a new location in the org chart. ‘moveDirectReports’ determines whether the user’s current direct reports move along with them or not. When ‘moveDirectReports’ is false, the direct reports get promoted to report to the moved user’s previous supervisor.

Typeahead Search

URL: /api/v1/usertypeahead
METHOD: GET
PARAMETERS: `name=name|ignoreSelf=true|false`
COMMENTS: type ahead search is an optimized search designed to return a list of minimal information for a search field drop-down (like adding a user to an appreciation)
RETURNS: `{“fullName”:”John Smith”, “id”:”1234″, “avatarURL”:”avatar/url/here”}

User Cash Balances

URL: /api/v1/usercash
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

Leaderboard

URL: api/v1/kiosk/KIOSK-ID/leaderboard
METHOD: GET
COMMENTS: returns a list of user data along with their leaderboard points MTD and YTD
RETURN [ {…user data…, “leaderboardMTD”: 680,”leaderboardYTD”: 3400}]

Announcements

URL: api/v1/kiosk/KIOSK-ID/announcements
Method: GET
COMMENTS: Returns two lists… recent hires in the last two weeks and recent announcements in the last two weeks
RETURN {“hire” : [{new hire data…}], “announcement”: [{announcement data…}]}

 Appreciations

URL: api/v1/kiosk/KIOSK-ID/feeds
Method: GET
COMMENTS: Returns recent feeds for the company
RETURN {feed data…}