Overview
To use the API, you can take one of the following approaches:
Service - use this to access Motivosity for server-side applications which will not be operating as a specific user
OAuth2 - use this to access Motivosity for client side integrations (e.g. a web application needing access to Motivosity).
Custom authentication
Each of these steps will be documented below:
Authentication
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.
The steps below will help walk you through how to generate an API Key in Motivosity to setup this authentication:
To get started, go ahead and navigate to the"Setup" page in Motivosity.
Next, you'll select "Integrations" on the left-hand side. After you go ahead and select the "API Key" tab.
From the API Key tab, select the "+ New API Key" button.
A modal should then appear allowing you to set up your App Name, App Secret, and an optional Enabled IPs. Please note, the App Name is display only in Motivosity. When you are finished, select "Save".
Once you have saved your authentication, you'll see it now in the list of enabled API Keys. To view the API Key, select "View Details".
In this modal, you will see your generated APP ID, SHORT ID, and APP SECRET. You will then be able to download your secure token as well.
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
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.
API Endpoints
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}`
Creating 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 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}, ...]`
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 List
URL: /api/v2/companyvalue
Authorized roles: user, platform
METHOD: GET
RETURN: `{"id":"1234", "name":"Company Value", "description":"Description"}`
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 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}`
Find User in Organization Chart
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 - Organization Chart
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 - Organization Chart
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 - Organization Chart
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
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"}`
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"}
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":"2012-09-07", "birthDate":"Jul 17", "department":"Parks", "email":"ron@parks.com", "countryCode":"USA", "payrollID":"21″, "personalityType":"ISTJ", "title":"Director", "phone":"888.222.1111", "supervisorEmail":"paul@parks.com", "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.
Acceptable date formats for Hire Dates and Birthdays:
ISO: YYYY-MM-DD (i.e. 2022-01-31)
Short Date: 01/31/2022
Medium Format: Jan 31, 2022
Long Date: January 31, 2022
Dates without a year:
Numerical Month/Day: 01/31
Alpha Month/Day: Jan 31
Any empty parameter will update the user data to empty.
Any omitted parameter will not be considered.
The 'function' is optional, but helpful if you want to delete or create a user from the 'sync' command.
You only need to use one of the supervisor data fields when passing data through (i.e. "supervisorEmail":"paul@parks.com","supervisorPayrollID":"12","supervisorID":"supervisorid")
When moving users around the org chart, update the supervisorPayrollID, supervisorEmail, or supervisorID 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
Adding Avatar Pictures
API: /api/v2/user/user-id/avatar
Authorized Roles: user, admin, and platform
METHOD: POST
REQUEST PARAMETERS: "file"
COMMENTS: replace ‘user-id’ with the userID of the Motivosity user who will be assigned the avatar (You can find the user ID by using the List of Users endpoint). The file input stream should be the complete avatar image, in .jpg or .png format.
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 Mode
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 will need a "Kiosk ID" to use this endpoint. You can find your Kiosk ID in Motivosity by going to Setup > Integrations > Select the "Kiosk" link on the left-hand side of the page. After you have enabled Kiosk Mode, you can then select view your Kiosk ID here located in each URL (example: token={KIOSK ID}):
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...}