Submit a ticket My Tickets
Welcome
Login  Sign up
  1. Motivosity Help Center
  2. Solution home
  3. Integrations
  4. Motivosity API
Open navigation

Motivosity API

Jalan Barrow
Modified on: Tue, 18 Oct, 2022 at 11:38 AM

Overview


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

  1. Service - use this to access Motivosity for server-side applications which will not be operating as a specific user
  2. OAuth2 - use this to access Motivosity for client side integrations (e.g. a web application needing access to Motivosity).
  3. 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:


  1. To get started, go ahead and navigate to the"Setup" page in Motivosity.
  2. Next, you'll select "Integrations" on the left-hand side. After you go ahead and select the "API Key" tab.
  3. From the API Key tab, select the "+ New API Key" button.
  4. 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".
  5. 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".
  6. 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.


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

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.