Sample Workflow

To help you better understand how our API works we've provided a brief example of a 'real world' workflow of making calls to various modules of the Humanity API

The API URL is located at https://www.humanity.com/api/

APP SETUP

First we'll make a request to the API to read in the initial config details that we'll use in other parts of the app for forms, display, etc. This will also very quickly confirm that the API is online, and our key, and request method is valid.

{
      "key": "YOUR_API_KEY",
      "request": {
            "module": "api.config"
          }
    }

In the above call we're passing very little information to the API because we're relying on the default output format (json) as well as the default method(GET).

AUTHENTICATION

We'll make a request to the API to authenticate the current user. We'll swap the key, username and password for an authentication token to be used on subsequent calls.

{
          "key": "YOUR_API_KEY",
          "request": {
                "module": "staff.login",
                "method": "GET",
                "username": "[email protected]",
                "password": "nicetry"
              }
    }

Assuming successful login our response will look like this: (See Authentication for full details)

{
          "success": "1",
          "data": {
                "employee": {
                      "name": "Ryan Fyfe",
                      "email": "[email protected]",
                      "etc": "..."
                        },
                "business": {
                "name": "Humanity Inc.",
                "etc": "..."
                    }
              },
          "token": "xxxxxxx"
    }

Now that we have authentication all future calls to the API just require this token which holds all of the other information in it.

SCHEDULE

To load an individual Employee's upcoming schedule we would use the schedules.shifts module like this:

{
          "token": "xxxxxxx",
          "request": {
                "module": "schedule.shift",
                "mode": "employee"
          }
    }

To fetch the details for any particular shift:

{
          "token": "xxxxxxx",
          "request": {
                "module": "schedule.shift",
                "id": "1(id of shift)"
              }
    }

To update the details on a shift:

{
          "token": "xxxxxxx",
          "request": {
                "module": "schedule.shift",
                "id": "1(id of shift)",
        "method": "UPDATE",
        "notes": "New Shift Notes"
          }
    }

To add an employee to a shift shift:

{  
           "token":"xxxxxxx",
           "request":{  
               "module":"schedule.shift",
               "method":"UPDATE",
               "add":"1(id of employee)"
             }
          }

To create a new shift:

{  
           "token":"xxxxxxx",
           "request":{  
               "module":"schedule.shift",
               "method":"CREATE",
               "start":"1(id of start time)",
               "end":"49(id of end time)",
               "start_date":"date",
               "end_date":"date",
               "schedule":"1(id of schedule)"
            }
         }

MESSAGE WALL

Let's say we want to display the message wall for the currently logged in employee's business:

{
         "token": "xxxxxxx",
         "request": {
           "module": "messaging.wall",
           "mode": "employee"
         }
       }

Now to leave a new post on the message wall requires a few more details:

{
         "token": "xxxxxxx",
         "request": {
           "method": "CREATE",
           "module": "messaging.wall",
           "title": "New post for the message wall",
           "post": "This is a new post that will be added to the message wall."
         }
       }