To use the API, you can take one of the following 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).
  4. Custom authentication 

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}
  • "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.



Custom authentication - 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.

  • 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":"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...}