NAV Navbar
Logo

Introduction

Humi API helps our partners provide the best solutions to their customers.

To gain partner access to our system, please contact us to discuss your specific implementation, data usage, and benefits to our platform. Once approved, you will be provided the required client credentials to access the API.

Partners

To gain partner access to our system, please contact us to discuss your specific implementation, data usage, and benefits to our platform. Once approved, you will be provided the required client credentials to access the API.

Authentication

Authorization Code

GET /oauth/authorize HTTP/1.1
Host: https://www.humi.ca

client_id=your_client_id
response_type=code
redirect_uri=your_redirect_uri

Our API requires standard OAuth 2 authentication. Your application can request an authorization code using the following method.

Access Token

POST /oauth/token HTTP/1.1
Host: https://www.humi.ca

code=your_auth_code
grant_type=authorization_code
client_id=your_client_id
client_secret=your_client_secret

The standard OAuth response will contain your authorization code. Using the authorization code, your application can request an access token for a user.

Refresh Token

You may refresh an expired access token by changing the grant_type to refresh_token. You would provide your refresh token in place of the original authorization code.

Requests

POST /api/v1/user HTTP/1.1
Host: https://www.humi.ca
Authorization: Bearer your_access_token

We use a standard OAuth 2 Bearer authorization for API requests. Once you have obtained an access token, you may make requests on behalf of the user.

Users

Get A User

POST /api/v1/user HTTP/1.1
Host: https://www.humi.ca
Authorization: Bearer your_access_token

The above command returns JSON structured like this:

{
  "user_id": 299792458,
  "email": "ohn.smith@gmail.com",
  "language": 1,
  "date_created": "2016-02-28 00:00:00",
  "fields": {
    "company_id": 1990,
    "office_id": 45000,
    "first_name": "John",
    "last_name": "Smith",
    "middle_initial": "F",
    "legal_name": "John F Smith",
    "profile_photo": "",
    "address": "123 Walker Ave",
    "city": "Toronto",
    "province": "Ontario",
    "province_code": "ON",
    "postal_code": "M4V 1G3",
    "phone_mobile": "(647) 222-2222",
    "phone_home": "(416) 222-2222",
    "email": "john.smith@gmail.com",
    "gender": "Male",
    "date_of_birth": "1984-10-31 00:00:00",
    "job_title": "Director Of Fun",
    "department": "Fun Services",
    "reports_to": "299792608",
    "secondary_reports_to": "",
    "date_hired": "2016-01-02 00:00:00",
    "compensation_type": "Yearly",
    "salary": 0,
    "employment_type": "Full-Time",
    "status": "Active",
    "ec_primary_name": "Michael Jackson",
    "ec_primary_relation": "Father",
    "ec_primary_phone": "1-800-290-9189",
    "ec_secondary_name": "Steve Jobs",
    "ec_secondary_relation": "Brother",
    "ec_secondary_phone": "(393) 939-1920",
    "date_terminated": "0000-00-00 00:00:00",
    "termination_type": "",
    "termination_reason": ""
  }
}

The users employee information

Company

Get A Company

POST /api/v1/company HTTP/1.1
Host: https://www.humi.ca
Authorization: Bearer your_access_token

The above command returns JSON structured like this:

{
  "company_id": 1990,
  "name": "Humi Inc",
  "phone_primary": "(647) 227-8923",
  "notification_email": "matt.loszak@gmail.com",
  "suppress_all_alerts": 0,
  "employee_count": 71,
  "date_founded": "2016-02-02 00:00:00",
  "date_joined_humi": "2016-02-02 00:00:00",
  "connected_benefits": 0,
  "connected_payroll": 0,
  "payroll_start": "2016-05-11 00:00:00",
  "payroll_frequency": "Biweekly",
  "is_premium": 1
}

The users company information

Offices

Get Offices


POST /api/v1/offices HTTP/1.1
Host: https://www.humi.ca
Authorization: Bearer your_access_token

The above command returns JSON structured like this:

[
  {
    "office_id": 45000,
    "company_id": 1990,
    "address": "34 Claremont Ave",
    "city": "Toronto",
    "province": "Ontario",
    "province_code": "ON",
    "postal_code": "M6J 2M4"
  },
  {
    "office_id": 45003,
    "company_id": 1990,
    "address": "123 Fork Streets",
    "city": "Toronto",
    "province": "Ontario",
    "province_code": "ON",
    "postal_code": "M4V 1G3"
  }
]

The users company offices

Benefits

Get Benefits

POST /api/v1/benefits HTTP/1.1
Host: https://www.humi.ca
Authorization: Bearer your_access_token

The above command returns JSON structured like this:

{
  "plan_id": 1000,
  "plan_name": "Plan A",
  "provider_id": 5612,
  "company_id": 1990,
  "plan_pdf_url": "140nrwvwud9mp92gymkwmams.pdf",
  "opted_in_total": 1,
  "opted_as_single": 1,
  "opted_as_family": 0,
  "start_date": "2016-02-01 00:00:00",
  "expiry_date": "2017-02-01 00:00:00",
  "monthly_payment_day": 22,
  "probation_days": 0,
  "enrollment_preference": "Automatic",
  "life_coverage": "$25,000",
  "life_rate": "$0.13 / $1,000",
  "life_prem": "$9.75",
  "accidental_death_coverage": "$25,000",
  "accidental_death_rate": "$0.07 / $1,000",
  "accidental_death_prem": "$5.25",
  "dependent_spouse_coverage": "$5,000",
  "dependent_child_coverage": "$5,000",
  "dependent_rate": "$1.95 / family",
  "dependent_prem": "$0.00",
  "extended_hc_hospital_reimb": "100%",
  "extended_hc_presc_drugs_reimb": "80%",
  "extended_hc_presc_drugs_details": "Plan includes coverage for:\nOver-the-counter vaccines.\n\nPlan does not include coverage for: \nFertility drugs, all other over-the-counter drugs, smoking cessation products, sexual dysfunction drugs, drugs for weight loss, hair growth products, drugs administered in a hospital.",
  "extended_hc_rate_single": "$43.59 / single",
  "extended_hc_rate_family": "$121.84 / family",
  "extended_hc_prem_single": "$130.77",
  "extended_hc_prem_family": "$0.00",
  "out_of_province_expenses_reimb": "100%",
  "ltd_reimb": "",
  "ltd_coverage": "",
  "ltd_details": "",
  "ltd_rate": "",
  "ltd_prem": "",
  "std_reimb": "",
  "std_coverage": "",
  "std_details": "",
  "std_rate": "",
  "std_prem": "",
  "paramedical_reimb": "80%",
  "paramedical_coverage": "$300 / year",
  "paramedical_details": "Plan includes coverage for:\nAcupuncturist, audiologist, chiropractor, dietician, massage therapist, naturopath, occupational therapist, osteopath, physiotherapist, podiatrist/chiropodist, psychologist/social worker, speech therapist.",
  "dental_preventive_reimb": "80%",
  "dental_preventive_details": "Exams, x-rays, lab tests, cleanings, scaling, fluoride and disking (under age 19), oral hygiene instruction and space maintainers.",
  "dental_basic_reimb": "80%",
  "dental_basic_details": "Fillings, extractions, pit and fissure sealants (under age 19), root canals, local anaesthesia, treatment of gum and bone disease, relining and rebasing of dentures.",
  "dental_major_reimb": "",
  "dental_major_details": "",
  "dental_ortho_reimb": "",
  "dental_ortho_details": "",
  "dental_total_coverage": "$1,500",
  "dental_rate_single": "$42.72 / single",
  "dental_rate_family": "$119.60 / family",
  "dental_prem_single": "$128.16",
  "dental_prem_family": "$0.00",
  "total_monthly_prem": "$273.93",
  "provider": {
    "provider_id": 5612,
    "name": "Sun Life",
    "logo": "brand_sunlife.png",
    "colour": "ecab23",
    "portal_url": "https://www.sunnet.sunlife.com/signin/mysunlife/home.wca?",
    "company_count": 1,
    "employee_count": 3,
    "dependent_count": 0,
    "admin_portal_url": null,
    "provider_slug": "sun_life"
  }
}

The users benefit plan information

Timesheets

Get Timesheets

POST /api/v1/timesheets HTTP/1.1
Host: https://www.humi.ca
Authorization: Bearer your_access_token

The above command returns JSON structured like this:

[]

The users company information

Errors

The Kittn API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your API key is wrong
403 Forbidden – The kitten requested is hidden for administrators only
404 Not Found – The specified kitten could not be found
405 Method Not Allowed – You tried to access a kitten with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The kitten requested has been removed from our servers
418 I’m a teapot
429 Too Many Requests – You’re requesting too many kittens! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.