Api doc


SDK's


Api Modules

Rest Requests

The Humanity API allows you to call modules with the Humanity service that respond in REST style json or xml.

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

Although we support multiple output types, all requests to the Humanity API are packaged as string representation of the JSON request object and sent only in the POST HTTP Request Method. Virtually all requests require an authentication token. The following parameters are accepted on each call:

  • key :Required for initial authentication
  • token : Authentication token where required
  • request : JSON object carrying all parameters for your request
  • output : json, xml, simplexml, html (default=json)

Example data:

  1. {
  2. "key": "xxxxxxx",
  3. "token": "xxxxxxx",
  4. "output": "json",
  5. "request": [
  6. "see below"
  7. ]
  8. }

Remember that any data passed to the API is to be formatted as JSON, and its string value needs to be sent via the POST HTTP request method all as the post variable 'data' (Checkout the 9th line from an example below). Also Content-Type needs to be set to application/x-www-form-urlencoded. Here is an example of what this looks like in PHP:

  1. # CALL VARIABLES
  2. $api['key'] = 'xxxxxxx';
  3. $api['output'] = 'html';
  4. $api['request'] = array('username'=>'ryan', 'password'=>'nicetry');
  5.  
  6. # OPEN CURL CONNECTION
  7. $ch = curl_init();
  8. curl_setopt($ch,CURLOPT_URL, 'https://www.humanity.com/api/');
  9.  
  10. curl_setopt($ch,CURLOPT_POSTFIELDS, <b>'data='.json_encode($api)</b>);
  11.  
  12. # EXECUTE COMMAND
  13. $result = curl_exec($ch);
  14.  
  15. # CLOSE CONNECTION
  16. curl_close($ch);
request

This object contains all of the variables that will be used to handle your request - including the api module, method as well as any method particular parameters.

  • module : API module (default=staff.login)
  • method : GET, CREATE, UPDATE, DELETE (default=GET)
  • ... : Any module specific variables

Example request:

  1. {
  2. "module": "staff.login",
  3. "method": "GET",
  4. "username": "ryan@humanity.com",
  5. "password": "nicetry"
  6. }
Accepted Variable Types

The Humanity API is strict with what variables it accepts in the request field. Meaning that you MUST pass the required variables for that module(if any), and you can ONLY pass other variables with are accepted by that module (if any).

For every variable that is passed we are also strict on the variable type that is allowed:

  • integer : Integer Values only
  • varchar : Variable Characters(default)
  • enum : only values from this list
  • min length : Minimum variable length
  • date : Valid Humanity Date ID, Unix TimeStamp or any date accepted by strtotime
  • time : Valid Humanity Time ID, any time accepted by strtotime
  • email : Valid E-mail
  • phone : Valid Phone Number

Rest Responses

Regardless on what output type you select the API will return data in the following format every time:

  • status : Response code of request (success=1)
  • data : Data returned in your request
  • token : Authentication Token (if authenticated)
Example response: (json)
  1. {
  2. "status": "1",
  3. "data": [
  4. {
  5. "name": "Ryan Fyfe",
  6. "email": "ryan@humanity.com"
  7. },
  8. {
  9. "name": "Mark Ryder",
  10. "email": "mark@humanity.com"
  11. }
  12. ],
  13. "token": "xxxxxxx"
  14. }
Example response: (xml)
  1. <?xml version="1.0"?>
  2. <response>
  3. <status>1</status>
  4. <data>
  5. <item>
  6. <name>Ryan Fyfe</name>
  7. <email>ryan@humanity.com</email>
  8. </item>
  9. <item>
  10. <name>Mark Ryder</name>
  11. <email>mark@humanity.com</email>
  12. </item>
  13. </data>
  14. <token>xxxxxxx</token>
  15. </response>
  16.  
Example response: (simplexml)
  1. <?xml version="1.0"?>
  2. <response>
  3. <status>1</status>
  4. <data>
  5. <name>Ryan Fyfe</name>
  6. <email>ryan@humanity.com</email>
  7. </data>
  8. <data>
  9. <name>Mark Ryder</name>
  10. <email>mark@humanity.com</email>
  11. </data>
  12. <token>xxxxxxx</token>
  13. </response>
  14.  
Example response: (html)
status1
data
0
nameRyan Fyfe
emailryan@humanity.com
1
nameMark Ryder
emailmark@humanity.com
tokenxxxxxxx



Error response: (json)

In the event of an error we provide the error number, and error description(in the data field), as well as an extra variable called 'error' which can be used for more detailed debugging or error reporting. eg:

  1. {
  2. "status": "9",
  3. "data": "Invalid parameters - Your request has an invalid parameter type",
  4. "error": "date expected: start_date",
  5. "token": ""
  6. }

You'll notice in the above that we both receive a response using the standard error codes, as well as in the 'error' field we have more detailed information that points us directly to the field that is wrong.

Multiple Requests/Responses

You can very easily make multiple requests to our API (up to 5 at a time). This will allow you to collect data from the API much faster, and make much more responsive applications. The format for request/response, is basically identical to when making individual requests except for now both the input/output are arrays as well.

Example Requests: (json)
  1. {
  2. "key": "xxxxxxx",
  3. "token": "xxxxxxx",
  4. "output": "json",
  5. "request": [
  6. {
  7. "module": "schedule.shifts"
  8. },
  9. {
  10. "module": "staff.employees"
  11. },
  12. {
  13. "module": "staff.employees"
  14. }
  15. ]
  16. }

In this same way you can make requests of different types(GET,DELETE,UPDATE,CREATE) with a single call to the API:

  1. {
  2. "key": "xxxxxxx",
  3. "token": "xxxxxxx",
  4. "output": "json",
  5. "request": [
  6. {
  7. "module": "schedule.shifts"
  8. },
  9. {
  10. "module": "schedule.shift",
  11. "method": "UPDATE",
  12. "id": "1"
  13. },
  14. {
  15. "module": "staff.employees",
  16. "method": "GET"
  17. },
  18. {
  19. "module": "staff.employee",
  20. "method": "CREATE",
  21. "name": "Ryan Fyfe"
  22. }
  23. ]
  24. }
Example Responses:

Responses are returned in an array, in the same order they are sent. They have the same internal structure as individual requests.

  1. [
  2. {
  3. "status": "1",
  4. "data": [
  5. {
  6. "name": "Ryan Fyfe",
  7. "email": "ryan@humanity.com"
  8. },
  9. {
  10. "name": "Mark Ryder",
  11. "email": "mark@humanity.com"
  12. }
  13. ],
  14. "token": "xxxxxxx"
  15. },
  16. {
  17. "status": "1",
  18. "data": [
  19. {
  20. "name": "Ryan Fyfe",
  21. "email": "ryan@humanity.com"
  22. },
  23. {
  24. "name": "Mark Ryder",
  25. "email": "mark@humanity.com"
  26. }
  27. ],
  28. "token": "xxxxxxx"
  29. }
  30. ]
  1. <?xml version="1.0"?>
  2. <response>
  3. <item>
  4. <status>1</status>
  5. <data>
  6. <item>
  7. <name>Ryan Fyfe</name>
  8. <email>ryan@humanity.com</email>
  9. </item>
  10. <item>
  11. <name>Mark Ryder</name>
  12. <email>mark@humanity.com</email>
  13. </item>
  14. </data>
  15. <token>xxxxxxx</token>
  16. </item>
  17. <item>
  18. <status>1</status>
  19. <data>
  20. <item>
  21. <name>Ryan Fyfe</name>
  22. <email>ryan@humanity.com</email>
  23. </item>
  24. <item>
  25. <name>Mark Ryder</name>
  26. <email>mark@humanity.com</email>
  27. </item>
  28. </data>
  29. <token>xxxxxxx</token>
  30. </item>
  31. </response>
  32.  

GET STARTED NOW

Free Trial. No Credit Card Required.

close
(e.g.+14158675309 or +1415-8675-309)

By clicking "Create my ShiftPlanning Account" you agree to the Terms of Service and Privacy Policy.

Have a promotional code?Click Here


LIVE CHAT DEMO REQUEST!

Please provide information below.

close
INSTANT DEMOSCHEDULED DEMO
Connect with a ShiftPlanning Team Member for a live demo right now!
 

RESELLER REQUEST!

Please provide information below.

close