NAV
cURL Ruby Node

Introduction

___________.__                 __
\_   _____/|  |   ____   ____ |  | __
 |    __)  |  |  /  _ \_/ ___\|  |/ /
 |     \   |  |_(  <_> )  \___|    <
 \___  /   |____/\____/ \___  >__|_ \
     \/                     \/     \/

Base URLs

Test: - https://demo.helloflock.com/api/
Live: - https://api.helloflock.com/

Flock API Documentation

Welcome to Flock’s Partner Developer API Documentation. Using our Partner’s API, you can very easily integrate with our Company HR platform. Before you get started :

The API is organized around REST. All requests should be made over SSL. All request and response bodies, including errors, are encoded in JSON.

RESTful API



To test our API, we recommend using the REST client called Postman. We have created a collection for you to give it a try. Simply click on the button below.

Need to know

- API access is over HTTPS
- Timestamps are in UTC/ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
- All requests and responses, including errors, are encoded in JSON




Note: Please check back regularly as we will be frequently adding more endpoints and features. If you have any special needs, please email us. Just added endpiints and features are marked with

Authentication

Authentication:

$ curl  -H 'Accept: application/json' \
        -H "Authorization:Bearer YOUR-API-TOKEN-HERE" \
        https://api.helloflock.com
require 'http'

HTTP.auth('Authorization:Bearer YOUR-API-TOKEN-HERE')
    .headers(accept: 'application/json')
    .get('https://api.helloflock.com')

var request = require('request');

var options = {
  method: 'GET',
  url: 'https://api.helloflock.com',
  headers: {
    'Authorization': 'Bearer YOUR-API-TOKEN-HERE',
    'accept': 'application/json'
  }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);
  console.log(body);
});

Response body

{
  "code": 200,
  "status": "success",
  "message": "Hello {Company Name}, let's Flock together."
}

Authentication to the API is performed via Bearer Token Authentication. This authorization token must be passed for every request. All API requests must be made over HTTPS. Calls made over non-secure HTTP and/or without Bearer Authentication Token will fail.

HTTP Status Codes

HTTP Status Code Summary:

Code Status
400 Malformed or bad JSON Request.
401 Your API key is invalid or you do not have access to this endpoint.
404 The resource does not exist.
422 A validation error occurred.
200 The request was successful.
201 The resource was successfully created.
5XX An API error.


Errors

Error


{
  "code": 404,
  "status": "error",
  "type": "not_found",
  "message": "Resource could not be found"
}


{
  "code": 401,
  "status": "error",
  "type": "auth_error",
  "message": "API token is not valid"
}
Error Type Reason
invalid_params Request had invalid parameters.
not_found Resource could not be found.
api_error API server error.
auth_error Authorization error.

Versioning

We version our API to ensure backward compatibility whenever a new version is released. Our current version is v1. Please note that older versions will only be mantained and supported for one year (time may change with/without notice) after a new version is released.

Test Mode vs Live Mode

Initially you will only have access to Demo/Test API. Please use it to make API calls. Once you are production-ready, please contact us so we can issue you a production/live API.

Test URL : https://demo.helloflock.com/api
Live URL : https://api.helloflock.com

Companies

curl  -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/companies
require 'http'

HTTP.auth('Authorization:Bearer YOUR-API-TOKEN-HERE')
    .headers(accept: 'application/json')
    .get('https://api.helloflock.com/v1/companies')
var request = require('request');

var options = {
  method: 'GET',
  url: 'https://api.helloflock.com/v1/companies',
  headers: {
    'Authorization': 'Bearer YOUR-API-TOKEN-HERE',
    'accept': 'application/json'
  }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);
  console.log(body);
});

Response body

[
  {
    "id": "ce5e0bb6-051f-4207-85b4-c0e44c3f4582",
    "name": "ABC LLC",
    "address1": "18144 Bins Forge",
    "address2": "Suite 351",
    "city": "Jonesville",
    "state": "Massachusetts",
    "zip_code": "44038",
    "country": "US",
    "number_of_employee": 18
  },
  {
    "id": "aa053537-ec50-4af7-9e0e-f83634b7ce42",
    "name": "XYZ Inc.",
    "address1": "52945 Williamson Glens",
    "address2": "Suite 649",
    "city": "Franeckishire",
    "state": "Alabama",
    "zip_code": "13810",
    "country": "US",
    "number_of_employee": 6
  }
]

Returns detailed information about the company/companies that your developer account has been assigned to or has access to.

GET /v1/companies

Schema

Attribute Type Description
id uuid Company ID
name string Company Name
address1 string Street Address
address2 string Suite, Room#, etc.
city string City Name
state string State Name
zip_code string Zip Code
country string Country
number_of_employee integer Total number of employees

Employees

All Employees

curl  -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/companies/:company_id/employees

require 'http'
endpoint = 'https://api.helloflock.com/v1/companies/:company_id/employees'

HTTP.auth('Authorization:Bearer YOUR-API-TOKEN-HERE')
    .headers(accept: 'application/json')
    .get(endpoint)
var request = require('request');

var options = {
  method: 'GET',
  url: 'https://api.helloflock.com/v1/companies/:company_id/employees',
  headers: {
    'Authorization': 'Bearer YOUR-API-TOKEN-HERE',
    'accept': 'application/json'
  }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);
  console.log(body);
});

Response body

[
  {
    "id": "00000000-0000-0000-0000-000000000061",
    "employee_id": "EMP-11",
    "first_name": "John",
    "last_name": "Smith",
    "email": "employee@example.com",
    "date_of_birth": "1975-01-12",
    "home_phone": "123-123-1234",
    "cell_phone": "987-987-9876",
    "social_security_number": "123456789",
    "gender": "Male",
    "marital_status": "unknown",
    "employment_status": "Active",
    "employment_type": "Full-time",
    "job_title": "HR Manager",
    "job_category": "Human Resources",
    "role": "company_admin",
    "department": null,
    "manager": {
      "id": null,
      "first_name": null,
      "last_name": null,
      "email": null
    },
    "location": "San Francisco",
    "address1": "123 Main Street",
    "address2": "Apt 300",
    "city": "San Francisco",
    "state": "CA",
    "zip_code": "98657",
    "country": "United States",
    "hire_date": "2015-07-14",
    "termination_date": null,
    "custom_fields": [
      {
        "field_name" : "T-Shirt Size",
        "field_value": "Medium"
      },
      {
        "field_name" : "Computer ID",
        "field_value" : "ABXY12"
      }
    ]
  },
  {
    "id": "00000000-0000-0000-0000-000000000316",
    "employee_id": "EMP-12",
    "first_name": "Jamie",
    "last_name": "Doe",
    "email": "example@employee.com",
    "date_of_birth": "1987-03-08",
    "home_phone": null,
    "cell_phone": "1234567890",
    "social_security_number": "123456789",
    "gender": "Female",
    "marital_status": "unknown",
    "employment_status": "Inactive",
    "employment_type": "Part-time",
    "job_title": "Software Engineer",
    "job_category": "Engineering",
    "role": "employee",
    "department": null,
    "manager": {
      "id": "00000000-0000-0000-0000-000000000061",
      "first_name": "John",
      "last_name": "Smith",
      "email": "employee@example.com"
    },
    "location": "New York",
    "address1": "11 Chruch street",
    "address2": "#02",
    "city": "Brooklyn",
    "state": "NY",
    "zip_code": "11211",
    "country": "US",
    "hire_date": "2015-08-05",
    "termination_date": null,
    "custom_fields": [
      {
        "field_name" : "T-Shirt Size",
        "field_value": "Large"
      },
      {
        "field_name" : "Computer ID",
        "field_value" : "GHYU76"
      }
    ]
  }
]

Returns a list of employees for a given company.

GET /v1/companies/:company_id/employees

Schema

Attribute Type Description
id uuid Flock Employee ID
employee_id stiring Company Employee ID
first_name string Legal First Name
last_name string Legal Last Name
email string Email Address
date_of_birth string Date of Birth
home_phone string Home Phone Number
cell_phone string Cell Phone Number
social_security_number string Last 4 digits of SSN
gender string Gender (Male/Female/Unknown)
marital_status string Marital Status (married/single/unknown)
employment_status string Employment Status (Active/Inactive/LOA)
employment_type string Employment Type (Part-time/Full-time etc.)
job_category string Job Category
job_title string Job Title
role string Role (employee/company_admin)
department string Department
manager object Manger Object (id, first_name, last_name and email)
location string Location
address1 string Street Address
address2 string Apt#
city string City
state string State
zip_code string Zip Code
country string Country
hire_date string Hire Date
termination_date string Termination Date (null if inactive)
custom_fields string Custom fields. (e.g., computer ID#, tee-shirt size, etc.)
created_at timestamp Record creation timestamp
updated_at timestamp Record last updated timestamp

Individual Employee

curl  -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/companies/:company_id/employees/:employee_id
require 'http'
endpoint = 'https://api.helloflock.com/v1/companies/:company_id/employees/:employee_id'

HTTP.auth('Authorization:Bearer YOUR-API-TOKEN-HERE')
    .headers(accept: 'application/json')
    .get(endpoint)
var request = require('request');

var options = {
  method: 'GET',
  url: 'https://api.helloflock.com/v1/companies/:company_id/employees/:employee_id',
  headers: {
    'Authorization': 'Bearer YOUR-API-TOKEN-HERE',
    'accept': 'application/json'
  }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);
  console.log(body);
});

Response body

{
  "id": "00000000-0000-0000-0000-000000000061",
  "employee_id": "EMP-11",
  "first_name": "John",
  "last_name": "Smith",
  "email": "employee@example.com",
  "date_of_birth": "1975-01-12",
  "home_phone": "123-123-1234",
  "cell_phone": "987-987-9876",
  "social_security_number": "123456789",
  "gender": "Male",
  "marital_status": "unknown",
  "employment_status": "Active",
  "employment_type": "Full-time",
  "job_title": "HR Manager",
  "job_category": "Human Resources",
  "role": "company_admin",
  "department": null,
  "manager": {
    "id": null,
    "first_name": null,
    "last_name": null,
    "email": null
  },
  "location": "San Francisco",
  "address1": "123 Main Street",
  "address2": "Apt 300",
  "city": "San Francisco",
  "state": "CA",
  "zip_code": "98657",
  "country": "United States",
  "hire_date": "2015-07-14",
  "termination_date": null,
  "custom_fields": [
    {
      "field_name" : "T-Shirt Size",
      "field_value": "Medium"
    },
    {
      "field_name" : "Computer ID",
      "field_value" : "ABXY12"
    }
  ]
}

Returns detail information about an Employee

GET /v1/companies/:company_id/employees/:employee_id

Compensation

All Compensation

curl  -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/companies/:company_id/employees/compensations
require 'http'
endpoint = 'https://api.helloflock.com/v1/companies/:company_id/employees/compensations'

HTTP.auth('Authorization:Bearer YOUR-API-TOKEN-HERE')
    .headers(accept: 'application/json')
    .get(endpoint)
var request = require('request');

var options = {
  method: 'GET',
  url: 'https://api.helloflock.com/v1/companies/:company_id/employees/compensations',
  headers: {
    'Authorization': 'Bearer YOUR-API-TOKEN-HERE',
    'accept': 'application/json'
  }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);
  console.log(body);
});

Response body

[
  {
     "id" : "57a7ffb6-6cab-4236-b4ee-2cb1ed5c2614",
    "employee_id" : "49e487d3-ba1d-4cb0-98a7-f25bf91900ae",
    "amount" : 2500.00,
    "frequency" : "bi_weekly",
    "compensation_type" : "salary",
    "pay_group_id" : "3ef7c397-909c-460f-8aee-938a37a18518",
    "overtime_exempt" : true,
    "start_date" : "2015-01-01",
    "end_date" : null
  },
  {
    "id" : "478eeda1-a841-4670-9044-041175a3a1c7",
    "employee_id" : "00000000-0000-0000-0000-000000000090",
    "amount" : 800.00,
    "frequency" : "weekly",
    "compensation_type" : "hourly",
    "pay_group_id" : "3ef7c397-909c-460f-8aee-938a37a18518",
    "overtime_exempt" : false,
    "start_date" : "2015-07-14",
    "end_date" : null
  },
  {
    "id" : "6c6553a0-fdfa-4f5c-879a-750a40056f43",
    "employee_id" : "00000000-0000-0000-0000-000000000009",
    "amount" : 1800.00,
    "frequency" : "bi_weekly",
    "compensation_type" : "hourly",
    "pay_group_id" : "3ef7c397-909c-460f-8aee-938a37a18518",
    "overtime_exempt" : false,
    "start_date" : "2014-11-20",
    "end_date" : null
  }
]

Returns compensation information for all the employees.

GET /v1/companies/:company_id/employees/compensations

Schema

Attribute Type Description
id uuid Flock Compensation ID
employee_id string Flock Employee ID
amount float Compensation Amount
frequency string Compensation Frequency (weekly / bi_weekly / semi_monthly / monthly)
compensation_type string Compensation Type (hourly / salary / unlimited)
pay_group_id string Flock Pay Group ID
overtime_exempt boolean true or falses
start_date date Compensation start date
end_date string Comensation end date (null if unknown)

Individual Compensation

curl  -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/companies/:company_id/employees/:employee_id/compensation
require 'http'
endpoint = 'https://api.helloflock.com/v1/companies/:company_id/employees/:employee_id/compensation'

HTTP.auth('Authorization:Bearer YOUR-API-TOKEN-HERE')
    .headers(accept: 'application/json')
    .get(endpoint)
var request = require('request');

var options = {
  method: 'GET',
  url: 'https://api.helloflock.com/v1/companies/:company_id/employees/:employee_id/compensation',
  headers: {
    'Authorization': 'Bearer YOUR-API-TOKEN-HERE',
    'accept': 'application/json'
  }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);
  console.log(body);
});

Response body

{
  "id" : "57a7ffb6-6cab-4236-b4ee-2cb1ed5c2614",
  "employee_id" : "49e487d3-ba1d-4cb0-98a7-f25bf91900ae",
  "amount" : 2500.00,
  "frequency" : "bi_weekly",
  "compensation_type" : "salary",
  "pay_group_id" : "3ef7c397-909c-460f-8aee-938a37a18518",
  "overtime_exempt" : true,
  "start_date" : "2015-01-01",
  "end_date" : null
}

Returns detailed information about each employees compensation.

GET /v1/companies/:company_id/employees/employee_id/compensation

Deductions

All Deductions

curl  -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/companies/:company_id/employees/deductions
require 'http'
endpoint = 'https://api.helloflock.com/v1/companies/:company_id/employees/deductions'

HTTP.auth('Authorization:Bearer YOUR-API-TOKEN-HERE')
    .headers(accept: 'application/json')
    .get(endpoint)
var request = require('request');

var options = {
  method: 'GET',
  url: 'https://api.helloflock.com/v1/companies/:company_id/employees/deductions',
  headers: {
    'Authorization': 'Bearer YOUR-API-TOKEN-HERE',
    'accept': 'application/json'
  }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);
  console.log(body);
});

Response body

[
  {
    "id": "ed8d3043-9129-4fcd-9277-d000a2ad3432",
    "employee_id": "d81e735e-256e-4df4-b2e8-ce0cddc66c4b",
    "employer_contribution": "100.00",
    "employer_contribution_type": "employee_medical_plan",
    "employee_contribution": "60.00",
    "employee_contribution_type": "medical_plan",
    "start_date": "2016-04-18T00:00:00.000-07:00",
    "end_date": null,
    "annual_cap": null
  },
  {
    "id": "e93dbd32-0b8a-44d5-a53c-8767e5decbba",
    "employee_id": "d81e735e-256e-4df4-b2e8-ce0cddc66c4b",
    "employer_contribution": "100.00",
    "employer_contribution_type": "employee_dental_plan",
    "employee_contribution": "30.00",
    "employee_contribution_type": "dental_plan",
    "start_date": "2016-04-18T00:00:00.000-07:00",
    "end_date": null,
    "annual_cap": null
  },
  {
    "id": "cce95152-d8f1-4dba-9250-6d3dcf5301cf",
    "employee_id": "d81e735e-256e-4df4-b2e8-ce0cddc66c4b",
    "employer_contribution": "10.00",
    "employer_contribution_type": "employee_vision_plan",
    "employee_contribution": "10.00",
    "employee_contribution_type": "vision_plan",
    "start_date": "2016-04-18T00:00:00.000-07:00",
    "end_date": null,
    "annual_cap": null
  }
]

Returns deductions information for all the employees.

GET /v1/companies/:company_id/employees/deductions

Schema

Attribute Type Description
id uuid Flock Plan ID
employee_id uuid Employee ID
employer_contribution float Employer’s Contribution Amount
employer_contribution_type string Employer’s Contribution Type
employee_contribution float Employee’s Contribution Amount
employee_contribution_type string Employee’s Contribution Type
start_date date Start Date
end_date date End Date
annual_cap float Annual Cap Amount

Individual Deductions

curl  -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/companies/:company_id/employees/:employee_id/deductions
require 'http'
endpoint = 'https://api.helloflock.com/v1/companies/:company_id/employees/:employee_id/deductions'

HTTP.auth('Authorization:Bearer YOUR-API-TOKEN-HERE')
    .headers(accept: 'application/json')
    .get(endpoint)
var request = require('request');

var options = {
  method: 'GET',
  url: 'https://api.helloflock.com/v1/companies/:company_id/employees/:employee_id/deductions',
  headers: {
    'Authorization': 'Bearer YOUR-API-TOKEN-HERE',
    'accept': 'application/json'
  }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);
  console.log(body);
});

Response body

[
  {
    "id": "ed8d3043-9129-4fcd-9277-d000a2ad3432",
    "employee_id": "d81e735e-256e-4df4-b2e8-ce0cddc66c4b",
    "employer_contribution": "100.00",
    "employer_contribution_type": "employee_medical_plan",
    "employee_contribution": "60.00",
    "employee_contribution_type": "medical_plan",
    "start_date": "2016-04-18T00:00:00.000-07:00",
    "end_date": null,
    "annual_cap": null
  },
  {
    "id": "e93dbd32-0b8a-44d5-a53c-8767e5decbba",
    "employee_id": "d81e735e-256e-4df4-b2e8-ce0cddc66c4b",
    "employer_contribution": "100.00",
    "employer_contribution_type": "employee_dental_plan",
    "employee_contribution": "30.00",
    "employee_contribution_type": "dental_plan",
    "start_date": "2016-04-18T00:00:00.000-07:00",
    "end_date": null,
    "annual_cap": null
  },
  {
    "id": "cce95152-d8f1-4dba-9250-6d3dcf5301cf",
    "employee_id": "d81e735e-256e-4df4-b2e8-ce0cddc66c4b",
    "employer_contribution": "10.00",
    "employer_contribution_type": "employee_vision_plan",
    "employee_contribution": "10.00",
    "employee_contribution_type": "vision_plan",
    "start_date": "2016-04-18T00:00:00.000-07:00",
    "end_date": null,
    "annual_cap": null
  }
]

Returns detailed information about each employees deductions.

GET /v1/companies/:company_id/employees/employee_id/deductions

Need Help?

If you encounter any error or problem, please feel free to reach out to us via email. Each request will have its unique X-Request-Id on response header. Please make sure to include this X-Request-Id and the error response.