NAV
curl

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.

Authentication

Authentication:

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

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

All Companies

All Companies

curl  -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/companies
[
  {
    "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

Attributes

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

Individual Company

Individual Company

curl  -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/companies/{company_id}
{
  "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
}

Returns detailed information about individual company.

GET /v1/companies/{company_id}

Attributes

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

Create a Company

Create a Company

curl  -X POST \
      -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/companies
      -d '{
            "name": "Company Name",
            "address1": "123 Main Street",
            "address2": "Suite 111",
            "city": "San Francisco",
            "state": "CA",
            "zip_code": "94530",
            "country": "USA",
            "payroll_frequency": "bi_weekly",
            "primary_admin": {
              "first_name": "James",
              "last_name": "Bond",
              "email": "another.user.email@example.com",
              "joining_date": "01/01/2015"
            }
        }'
{
  "id" : "bbf3ca2c-1238-45dd-b1fc-605b0a9d8920",
  "name": "Company Name",
  "address1": "123 Main Street",
  "address2": "Suite 111",
  "city": "San Francisco",
  "state": "CA",
  "zip": "94530",
  "country": "USA",
  "payroll_frequency": "bi_weekly",
  "primary_admin": {
    "first_name": "James",
    "last_name": "Bond",
    "email": "another.user.email@example.com",
    "joining_date": "01/01/2015"
  }
}

Creates a company.

POST /v1/companies

Arguments

Type Description
name string Company Name required
address1 string Street Address required
address2 string Suite, Room#, etc. required
city string City Name required
state string State Name required
zip_code string Zip Code required
country string Country required
number_of_employee integer Total number of employees required
primary_admin json First/Last names, Email and Joining Date for Primary Admin required

Update a Company

Update a Company

curl -X PATCH \
     -H "Authorization: Bearer YOUR-API-TOKEN-HERE" \
     -H "Content-Type: application/json" \
     -i "https://api.helloflock.com/v1/companies/{company_id}" \
     -d '{
          "name": "New Company Name",
          "address1": "123 Main Street",
          "address2": "Suite 111",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94530",
          "country": "USA",
          "payroll_frequency": "bi_weekly"
       }'
{
  "id" : "bbf3ca2c-1238-45dd-b1fc-605b0a9d8920",
  "name": "New Company Name",
  "address1": "123 Main Street",
  "address2": "Suite 111",
  "city": "San Francisco",
  "state": "CA",
  "zip": "94530",
  "country": "USA",
  "payroll_frequency": "bi_weekly"
}

Updates a company.

PATCH /v1/companies/{company_id}

Arguments

Type Description
id uuid Company ID required

Employees

All 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
[
  {
    "id": "dcabaa3d-c2a9-4b1a-b5f4-ca7fa6c25759",
    "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": "aa5663ca-8099-4907-89b1-94844a6c9f4b",
    "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

Attributes

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

Individual Employee

curl  -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/employees/{employee_id}
{
  "id": "dcabaa3d-c2a9-4b1a-b5f4-ca7fa6c25759",
  "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/employees/{employee_id}

Attributes

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

Create an Employee

Create an Employee

curl  -X POST \
      -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/companies/{company_id}/employees/{employee_id}
      -d '{
            "employee_id": "EMP-11",
            "first_name": "John",
            "last_name": "Smith",
            "email": "employee@example.com",
            "hire_date": "2015-07-14",
            "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",
            "termination_date": null,
            "custom_fields": [
              {
                "field_name" : "T-Shirt Size",
                "field_value": "Medium"
              },
              {
                "field_name" : "Computer ID",
                "field_value" : "ABXY12"
              }
            ]
        }
      '
{
  "id": "dcabaa3d-c2a9-4b1a-b5f4-ca7fa6c25759",
  "employee_id": "EMP-11",
  "first_name": "John",
  "last_name": "Smith",
  "email": "employee@example.com",
  "hire_date": "2015-07-14",
  "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",
  "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

POST /v1/companies/{company_id}/employees/{employee_id}

Arguments

Type Description
employee_id stiring Company Employee ID
first_name string Legal First Name required
last_name string Legal Last Name required
email string Email Address required
hire_date string Hire Date required
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
termination_date string Termination Date (null if inactive)
custom_fields string Custom fields. (e.g., Computer ID#, T-Shirt size, etc.)

Update an Employee

Update an Employee

curl  -X PATCH \
      -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/employees/{employee_id}
      -d '{
            "id": "dcabaa3d-c2a9-4b1a-b5f4-ca7fa6c25759",
            "first_name": "James",
            "email": "james.smith@example.com",
          }
      '
{
  "id": "dcabaa3d-c2a9-4b1a-b5f4-ca7fa6c25759",
  "employee_id": "EMP-11",
  "first_name": "James",
  "last_name": "Smith",
  "email": "james.smith@example.com",
  "hire_date": "2015-07-14",
  "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",
  "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

PATCH /v1/employees/{employee_id}

Arguments

Type Description
id uuid Employee ID required

Dependents

All Dependents

All Dependents

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

[
  {
    "id" : "d3aa09eb-62eb-4e2e-a06f-e81fcbd7e6cd",
    "first_name" : "Melinda",
    "last_name" : "Barry",
    "relationship" : "Spouse",
    "gender" : "Female",
    "date_of_birth" : "Tue, 05 May 1987",
    "ssn" : "440-93-8289",
    "email" : "malinda.berry@gmail.com",
    "cell_phone" : "636-887-7887",
    "home_phone" : "(134) 674-3543",
    "address1" : "5196 Miller Run",
    "address2" : "Apt 111",
    "city" : "San Francisco",
    "state" : "CA",
    "zip_code" : "94111"
  },
  {
    "id" : "f58082ea-0860-4965-adb5-ccb97835532c",
    "first_name" : "Berry",
    "last_name" : "Barry",
    "relationship" : "Son",
    "gender" : "Male",
    "date_of_birth" : "Mon, 13 Feb 2006",
    "ssn" : "201-86-7156",
    "email" : null,
    "cell_phone" : null,
    "home_phone" : "(134) 674-3543",
    "address1" : "5196 Miller Run",
    "address2" : "Apt 111",
    "city" : "San Francisco",
    "state" : "CA",
    "zip_code" : "94111"
  }
]

Returns a list of dependents for an employee.

GET /v1/employees/{employee_id}/dependents

Individual Dependent

Individual Dependent

curl  -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/dependents/{dependent_id}

{
  "id" : "d3aa09eb-62eb-4e2e-a06f-e81fcbd7e6cd",
  "first_name" : "Melinda",
  "last_name" : "Barry",
  "relationship" : "Spouse",
  "gender" : "Female",
  "date_of_birth" : "Tue, 05 May 1987",
  "ssn" : "440-93-8289",
  "email" : "malinda.berry@gmail.com",
  "cell_phone" : "636-887-7887",
  "home_phone" : "(134) 674-3543",
  "address1" : "5196 Miller Run",
  "address2" : "Apt 111",
  "city" : "San Francisco",
  "state" : "CA",
  "zip_code" : "94111"
}

Returns detail information about a Dependent

GET /v1/dependents/{dependent_id}

Create a Dependent

Create a Dependent

curl  -X POST \
      -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/employees/{employee_id}/dependents
      -d '{
            "first_name" : "Jenny",
            "last_name" : "Barry",
            "relationship" : "Daughter",
            "gender" : "Female",
            "date_of_birth" : "Tue, 05 May 2000",
            "ssn" : "111-22-3333",
            "email" : "jenny.berry@gmail.com",
            "cell_phone" : "123-333-4444",
            "home_phone" : "666-777-8888",
            "address1" : "5196 Miller Run",
            "address2" : "Apt 111",
            "city" : "San Francisco",
            "state" : "CA",
            "zip_code" : "94111"
          }
      '
{
  "id" : "5521680e-68a2-4259-bdd2-cc23e10aaa7b",
  "first_name" : "Jenny",
  "last_name" : "Barry",
  "relationship" : "Daughter",
  "gender" : "Female",
  "date_of_birth" : "Tue, 05 May 2000",
  "ssn" : "111-22-3333",
  "email" : "jenny.berry@gmail.com",
  "cell_phone" : "123-333-4444",
  "home_phone" : "666-777-8888",
  "address1" : "5196 Miller Run",
  "address2" : "Apt 111",
  "city" : "San Francisco",
  "state" : "CA",
  "zip_code" : "94111"
}

Create a dependent for an Employee.

POST /v1/employees/{employee_id}/dependents

Arguments

Type Description
first_name string Legal First Name required
last_name string Legal Last Name required
relationship string Relationship required
gender string Gender required
date_of_birth string Date of Birth required
ssn string Social Security Number required
email string Email Address
cell_phone string Cell Phone Number
home_phone string Home Phone Number
address1 string Street Address
address2 string Apt#
city string City
state string State
zip_code string Zip Code

Update a Dependent

Update a Dependent

curl  -X PATCH \
      -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/dependents/{dependent_id}
      -d '{
            "id" : "5521680e-68a2-4259-bdd2-cc23e10aaa7b",
            "date_of_birth" : "Fri, 05 May 2001",
            "ssn" : "111-22-4444"
          }
      '
{
  "id" : "5521680e-68a2-4259-bdd2-cc23e10aaa7b",
  "first_name" : "Jenny",
  "last_name" : "Barry",
  "relationship" : "Daughter",
  "gender" : "Female",
  "date_of_birth" : "Fri, 05 May 2001",
  "ssn" : "111-22-4444",
  "email" : "jenny.berry@gmail.com",
  "cell_phone" : "123-333-4444",
  "home_phone" : "666-777-8888",
  "address1" : "5196 Miller Run",
  "address2" : "Apt 111",
  "city" : "San Francisco",
  "state" : "CA",
  "zip_code" : "94111"
}

Update information about a given Dependent.

PATCH /v1/dependents/{dependent_id}

Arguments

Type Description
id uuid Dependent ID required

Compensations

All Compensation

All Compensation

curl  -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/companies/{company_id}/compensations
[
  {
     "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}/compensations

Attributes

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

Individual Compensation

curl  -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/employees/:employee_id/compensation
{
  "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/employees/:employee_id/compensation

Create a Compensation

Create a Compensation

curl  -X POST \
      -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/employees/{employee_id}/compensations
      -d '
        {
          "amount" : 3500.00,
          "frequency" : "bi_weekly",
          "compensation_type" : "salary",
          "pay_group_id" : "3ef7c397-909c-460f-8aee-938a37a18518",
          "overtime_exempt" : true,
          "start_date" : "2016-01-01",
          "end_date" : null
        }
      '
{
   "id" : "c17d517d-817a-4738-901f-e0ba2c878922",
  "employee_id" : "1dc0b244-c50a-432b-8989-2cdba694738d",
  "amount" : 3500.00,
  "frequency" : "bi_weekly",
  "compensation_type" : "salary",
  "pay_group_id" : "3ef7c397-909c-460f-8aee-938a37a18518",
  "overtime_exempt" : true,
  "start_date" : "2016-01-01",
  "end_date" : null
}

Create a compensation record for an employee.

POST /v1/employees/{employee_id}/compensations

Arguments

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

Update a Compensation

Update a Compensation

curl  -X PATCH \
      -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/compensations/{compensation_id}
      -d '
        {
          "id": "c17d517d-817a-4738-901f-e0ba2c878922",
          "amount" : 1500.00,
          "frequency" : "weekly",
        }
      '
{
   "id" : "c17d517d-817a-4738-901f-e0ba2c878922",
  "employee_id" : "1dc0b244-c50a-432b-8989-2cdba694738d",
  "amount" : 1500.00,
  "frequency" : "weekly",
  "compensation_type" : "salary",
  "pay_group_id" : "3ef7c397-909c-460f-8aee-938a37a18518",
  "overtime_exempt" : true,
  "start_date" : "2016-01-01",
  "end_date" : null
}

Update a compensation record for an employee.

PATCH /v1/compensations/{compensation_id}

Arguments

Type Description
id uuid Compensation ID required

Candidates

All Candidates

All Candidates

curl \
    -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
    -i https://app.helloflock.com/api/v1/companies/{company_id}/candidates
[
    {
      "id": "0d605582-b934-42bc-b896-5739c8b5b061",
      "first_name": "John",
      "last_name": "Doe",
      "middle_name": null,
      "zipcode": null,
      "email": "john.candidate@example.com",
      "phone": null,
      "date_of_birth": "1980-01-01",
      "social_security_number": "XXX-XX-1234",
      "offer_type": "Employee",
      "status": "signed",
      "designation": "Engineering",
      "salary": 100000.00,
      "bonus": 0,
      "commissions": 0,
      "referal_bonus": 0,
      "relocation_bonus": 0,
      "signing_bonus": 0,
      "sent_at": "2015-09-18T14:18:18.790-07:00",
      "hire_date": "2015-09-22",
      "sign_due_date": "2015-09-21"
    },
    {
      "id": "3145f548-ede7-4207-8ffc-419a0f1a0ba9",
      "first_name": "Jane",
      "last_name": "Doe",
      "middle_name": null,
      "zipcode": null,
      "email": "jane.candidate@example.com",
      "phone": null,
      "date_of_birth": "1985-01-01",
      "social_security_number": null,
      "offer_type": "Employee",
      "status": "unsigned",
      "designation": "System Administration",
      "salary": 150000.00,
      "bonus": 0,
      "commissions": 0,
      "referal_bonus": 0,
      "relocation_bonus": 0,
      "signing_bonus": 0,
      "sent_at": "2015-09-18T14:18:18.790-07:00",
      "hire_date": "2015-09-22",
      "sign_due_date": "2015-09-21"
    },
    {
      "id": "7a6786d3-87d6-4708-b63d-f4f99db49c70",
      "first_name": "Test",
      "last_name": "Candidate",
      "middle_name": null,
      "zipcode": null,
      "email": "test.candidate@example.com",
      "phone": null,
      "date_of_birth": null,
      "social_security_number": null,
      "offer_type": "Employee",
      "status": "voided",
      "designation": "Eng",
      "salary":0.00,
      "bonus": 0,
      "commissions": 0,
      "referal_bonus": 0,
      "relocation_bonus": 0,
      "signing_bonus": 0,
      "sent_at": "2015-09-18T14:18:18.790-07:00",
      "hire_date": "2015-09-22",
      "sign_due_date": "2015-09-21"
    }
]

Returns a list of all candidates for a given company

GET /v1/companies/{company_id}/candidates

Attributes

Type Description
id uuid Candidate ID
first_name string First Name
last_name string Last Name
middle_name string Middle Name
zipcode string Zip Code
email string email
phone string Contact Phone Number
date_of_birth date Date of Birth
social_security_number string Social Security Number
offer_type string Offer Type (Employee / Contractor)
status string Candidate / Offer status (signed / unsigned / expired)
designation string Designation (title)
salary float Salary Amount
bonus float Bonus Amount
commissions float Commission Amount
referral_bonus float Referral Bonus
relocation_bonus float Relocation Bonus
signing_bonus float Relocation Bonus
sent_at datetime Timestamp (Offer Sent at)
hire_date datetime Timestamp (Candidate hired at)
sign_due_date datetime Timestamp (Offer sign due date)

Individual Candidate

Individual Candidate

curl \
    -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
    -i https://app.helloflock.com/api/v1/candidates/{candidate_id}
{
  "id": "0d605582-b934-42bc-b896-5739c8b5b061",
  "first_name": "John",
  "last_name": "Doe",
  "middle_name": null,
  "zipcode": null,
  "email": "john.candidate@example.com",
  "phone": null,
  "date_of_birth": "1980-01-01",
  "social_security_number": "XXX-XX-1234",
  "offer_type": "Employee",
  "status": "signed",
  "designation": "Engineering",
  "salary": 100000.00,
  "bonus": 0,
  "commissions": 0,
  "referal_bonus": 0,
  "relocation_bonus": 0,
  "signing_bonus": 0,
  "sent_at": "2015-09-18T14:18:18.790-07:00",
  "hire_date": "2015-09-22",
  "sign_due_date": "2015-09-21"
}

Returns a candidate record for a company.

GET /v1/candidates/{candidate_id}

Attributes

Type Description
id uuid Candidate ID
first_name string First Name
last_name string Last Name
middle_name string Middle Name
zipcode string Zip Code
email string email
phone string Contact Phone Number
date_of_birth date Date of Birth
social_security_number string Social Security Number
offer_type string Offer Type (Employee / Contractor)
status string Candidate / Offer status (signed / unsigned / expired)
designation string Designation (title)
salary float Salary Amount
bonus float Bonus Amount
commissions float Commission Amount
referral_bonus float Referral Bonus
relocation_bonus float Relocation Bonus
signing_bonus float Relocation Bonus
sent_at datetime Timestamp (Offer Sent at)
hire_date datetime Timestamp (Candidate hired at)
sign_due_date datetime Timestamp (Offer sign due date)

Candidate with Status

Candidate with Status

curl \
    -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
    -i https://app.helloflock.com/api/v1/companies/{company_id}/candidates?status={status}
[
  {
    "id": "0d605582-b934-42bc-b896-5739c8b5b061",
    "first_name": "John",
    "last_name": "Doe",
    "middle_name": null,
    "zipcode": null,
    "email": "john.candidate@example.com",
    "phone": null,
    "date_of_birth": "1980-01-01",
    "social_security_number": "XXX-XX-1234",
    "offer_type": "Employee",
    "status": "signed",
    "designation": "Engineering",
    "salary": 100000.00,
    "bonus": 0,
    "commissions": 0,
    "referal_bonus": 0,
    "relocation_bonus": 0,
    "signing_bonus": 0,
    "sent_at": "2015-09-18T14:18:18.790-07:00",
    "hire_date": "2015-09-22",
    "sign_due_date": "2015-09-21"
  }
]

Returns candidates with given statuses. Statuses include

GET /v1/companies/{company_id}/candidates?status={status}

Attributes

Type Description
id uuid Candidate ID
first_name string First Name
last_name string Last Name
middle_name string Middle Name
zipcode string Zip Code
email string email
phone string Contact Phone Number
date_of_birth date Date of Birth
social_security_number string Social Security Number
offer_type string Offer Type (Employee / Contractor)
status string Candidate / Offer status (signed / unsigned / expired)
designation string Designation (title)
salary float Salary Amount
bonus float Bonus Amount
commissions float Commission Amount
referral_bonus float Referral Bonus
relocation_bonus float Relocation Bonus
signing_bonus float Relocation Bonus
sent_at datetime Timestamp (Offer Sent at)
hire_date datetime Timestamp (Candidate hired at)
sign_due_date datetime Timestamp (Offer sign due date)

Plans

Carriers

All Carriers

All Carriers

curl  -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/plans/carriers
[
  {
    "id" : "b38fdc5c-4e9c-4586-b2aa-93a3e871ff99",
    "name" : "United Health Care",
    "logo" : "https://logo.url",
    "description" : "Individual and family health insuranc...",
    "url" : "https://www.uhc.com/",
    "types" : [ "medical", "dental", "life_insurance"]
  },

  {
    "id" : "b0cc8a9f-3f1d-4727-99d1-29b5d66de981",
    "name" : "Kaiser Permanente",
    "logo" : "https://logo.url",
    "description" : "Staying healthy is easier with the...",
    "url" : "https://www.cigna.com",
    "types" : [ "vision", "life_insurance", "std_ltd"]
  },

  {
    "id" : "5c7c736b-3964-40c4-9349-459fb4084461",
    "name" : "Cigna",
    "logo" : "https://logo.url",
    "description" : "Cigna Health Insurance...",
    "url" : "https://www.cigna.com",
    "types" : [ "dental"]
  }
]

Returns a list of carriers.

GET v1/plans/carriers

Attributes

Type Description
id uuid Carrier ID
name stiring Carrier name
logo string Carrier logo URL
description text Carrier description
url string Carrier URL
types array Carrier Types (medical/dental/vision/life_insurance/std_ltd/fsa/hsa)

Individual Carrier

Individual Carrier

curl  -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/plans/carriers/{carrier_id}
{
  "id" : "b38fdc5c-4e9c-4586-b2aa-93a3e871ff99",
  "name" : "United Health Care",
  "logo" : "https://logo.url",
  "description" : "Individual and family health insuranc...",
  "url" : "https://www.uhc.com/",
  "types" : [ "medical", "dental", "life_insurance"]
}

Returns a list of carriers.

GET v1/plans/carriers/{carrier_id}

Attributes

Type Description
id uuid Carrier ID
name stiring Carrier name
logo string Carrier logo URL
description text Carrier description
url string Carrier URL
types array Carrier Types (medical/dental/vision/life_insurance/std_ltd/fsa/hsa)

Create a Carrier

Create a Carrier

curl  -X POST \
      -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/plans/carriers \
      -d '{
        "name" : "Blue Shield of California",
        "logo" : "https://logo.url",
        "description" : "Blue Shield of California...",
        "url" : "https://www.blueshieldca.com/",
        "types" : [ "medical", "dental", "vision"]
      }'

Creates a Carrier

POST v1/plans/carriers

Attributes

Type Description
name stiring Carrier name required
logo string Carrier logo URL required
description text Carrier description
url string Carrier URL
types array Carrier Types (medical/dental/vision/life_insurance/std_ltd/fsa/hsa) required

Update a Carrier

Update a Carrier

curl  -X PATCH \
      -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/plans/carriers \
      -d '{
        "id" : "7cd0239f-7bde-4183-a907-499ab4d78b72",
        "name" : "BlueCross BlueShield",
        "description" : "Blue Cross BlueShield...",
        "url" : "https://www.bcbs.com/",
      }'

Updates a Carrier

PATCH v1/plans/carriers/{carrier_id}

Attributes

Type Description
id uuid Carrier ID required

All Plans

All Plans

All Plans

curl  -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/companies/{company_id}/plans
[
  {
    "id": "23258e9a-fce4-4f9a-a27c-d3466d888d35",
    "name" : "Medical Plan",
    "description" : "This Plan Is HDMP",
    "carrier_id" : "cc526468-c411-44b2-8a3b-ba85a5042d9a",
    "type": "default/High Deductable",
    "out_of_network" : "$100",
    "emergency" : "$100",
    "hmo" : true,
    "deductibles" : {
      "individual" : "$100",
      "family" : "$100"
    },
    "pocket_max" : {
      "individual" : "$100",
      "family" : "$100"
    },
    "co_pay" : {
      "office" : "$100",
      "specialist" : "$100"
    },
    "rx" : {
      "deductible" : "$100",
      "generic" : "$100",
      "speciality" : "$100",
      "brand" : "$100"
    },
    "document_url": [
      "https://document.url",
      "https://document.url",
      "https://document.url"
    ],
    "configuration": {
      "start_date" : "2017-10-20T23:59:59.000-08:00",
      "end_date" : "2017-12-20T23:59:59.000-08:00",
      "enrollement_type" : "active",
      "pre_tax" : "yes",
      "new_hire_waiting_period" : "30_days_from_hire_date",
      "benefits_termination_waiting_period" : "same_day_termination",
      "over_age_limit" : 24,
      "over_age_limit_for_part_time_student" : 30
    },
    "rate": {
      "rate_type" : "composite",
      "plan_type" : "buy_up",
      "employee_contributions" : {
         "employee" : 100.00,
         "employee_and_spouse" : 300.00,
         "employee_and_child" :  400.00,
         "employee_and_children" : 300.00,
         "employee_and_family" : 100.00
      },
      "employer_contributions" : {
         "type" : "individual",
         "towards_employee" : 100.00,
         "towards_spouse" : 100.00,
         "towards_child" : 1000.00,
         "towards_children" : 1000.00,
         "towards_family" : 10000.00
      },
      "region_rates": [
        {
          "start_age": 20,
          "end_age": 30,
          "amount": 100
        },
        {
          "start_age": 30,
          "end_age": 40,
          "amount": 200
        },
        {
          "start_age": 40,
          "end_age": 50,
          "amount": 300
        }
      ]
    }
  },

  {
    "id": "0000000-0000-0000-0000-000000000061",
    "name": "Dental Plan",
    "description": "This is the dental plan",
    "carrier_id": "00000000-0000-0000-0000-000000000063",
    "carrier_name": "abc",
    "hmo": true,
    "document_url": [
      "https://document.url",
      "https://document.url",
      "https://document.url"
    ],
    "configuration": {
      "start_date": "09/21/2017",
      "end_date": "12/21/2017",
      "passive": "true",
      "pre_tax": "true",

      "new_hire_waiting_period": "30_days_from_hire_date",
      "benefits_termination_waiting_period": "last_of_month_following_termination",
      "over_age_limit": "2",
      "over_age_limit_for_part_time_student": "2"
    },
    "rate": {

      "plan_type": "None",
      "rate_type": "composite",
      "employee_contributions": {
        "employee": 20.00,
        "employee_and_spouse": 40.00,
        "employee_and_child": 100.00,
        "employee_and_children": 1000.00,
        "employee_and_family": 300.00
      },
      "employer_contributions": {
        "rate_symbol": "dollar",
        "type": "individual",
        "towards_employee": 10.00,
        "towards_spouse": 100.00,
        "towards_child": 200.00,
        "towards_children": 300.00,
        "towards_family": 400.00
      },
      "region_rates": [
        {
          "start_age": "integer",
          "end_age": "integer",
          "amount": "float"
        },
        {
          "start_age": "integer",
          "end_age": "integer",
          "amount": "float"
        },
        {
          "start_age": "integer",
          "end_age": "integer",
          "amount": "float"
        }
      ]
    }
  }
]

Returns a list of active plans for a given company.

GET v1/companies/company_id/plans

You can also break down these plans by:-

Attributes

Type Description
id uuid
name string
description text
carrier_id uuid
type string
out_of_network float
emergency float
hmo boolean
deductibles json individual / family
pocket_max json individual / family
co_pay json office / specialist
rx json deductible / generic / speciality / brand
document_url array Document URL
configuration json Plan Configuration
rate json Plan Rate

Medical Plans

All Medical Plans

All Medical Plans

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

Returns a collection of all medical plans for a given company

GET v1/companies/{company_id}/plans/medical

Individual Medical Plan

Individual Medical Plan

curl  -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/plans/{medical_plan_id}
{
  "id": "03ba9868-c82f-4cd7-8d8f-37deaa0ad406",
  "name" : "Medical Plan",
  "description" : "This Plan Is HDMP",
  "carrier_id" : "cf2f4e5a-8e72-40e8-ab57-e1cbdc17eecf",
  "type": "default/High Deductable",
  "out_of_network" : 100.00,
  "emergency" : 100.00,
  "hmo" : true,
  "deductibles" : {
    "individual" : 100.00,
    "family" : 100.00
  },
  "pocket_max" : {
    "individual" : 100.00,
    "family" : 100.00
  },
  "co_pay" : {
    "office" : 100.00,
    "specialist" : 100.00
  },
  "rx" : {
    "deductible" : 100.00,
    "generic" : 100.00,
    "speciality" : 100.00,
    "brand" : 100.00
  },
  "document_url": [
    "https://document.url",
    "https://document.url",
    "https://document.url"
  ],
  "configuration": {
    "start_date" : "2017-10-20T23:59:59.000-08:00",
    "end_date" : "2017-12-20T23:59:59.000-08:00",
    "enrollement_type" : "active",
    "pre_tax" : "yes",
    "new_hire_waiting_period" : "30_days_from_hire_date",
    "benefits_termination_waiting_period" : "same_day_termination",
    "over_age_limit" : 24,
    "over_age_limit_for_part_time_student" : 30
  },
  "rate": {
    "rate_type" : "composite",
    "plan_type" : "buy_up",
    "employee_contributions" : {
       "employee" : 100.00,
       "employee_and_spouse" : 300.00,
       "employee_and_child" :  400.00,
       "employee_and_children" : 300.00,
       "employee_and_family" : 100.00
    },
    "employer_contributions" : {
       "type" : "individual",
       "towards_employee" : 100.00,
       "towards_spouse" : 100.00,
       "towards_child" : 1000.00,
       "towards_children" : 1000.00,
       "towards_family" : 10000.00
    },
    "region_rates": [
      {
        "start_age": 20,
        "end_age": 30,
        "amount": 100
      },
      {
        "start_age": 30,
        "end_age": 40,
        "amount": 200
      },
      {
        "start_age": 40,
        "end_age": 50,
        "amount": 300
      }
    ]
  }
}

Returns an individual Medical Plan

GET v1/companies/:uuid/plans/medical/:uuid

Create a Medical Plan

Create a Medical Plan

curl  -X POST \
      -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/medical
      - d '{
        "name" : "string",
        "description" : "text",
        "carrier_id" : "uuid",
        "type": "default/High Deductable",
        "out_of_network" : "string",
        "emergency" : "string",
        "hmo": "boolean",
        "attachment": {
        "name": "file2",
        "file": "send encoded base64 file as string"
        },
        "deductibles" : {
          "individual" : "string",
          "family" : "string",
        },
        "pocket_max" : {
          "individual" : "string",
          "family" : "string"
        },
        "co_pay" : {
          "office" : "string",
          "specialist" : "string",
        },
        "rx" : {
          "deductible" : "string",
          "generic" : "string",
          "speciality" : "string",
          "brand" : "string"
        },
        "configuration": {
          "start_date" : "date",
          "end_date" : "date",
          "enrollement_type" : "active/passive",
          "pre_tax" : "yes/no",
          "new_hire_waiting_period" : "Please see New hire waiting period",
          "benefits_termination_waiting_period" : "Please see Benefits termination waiting period",
          "over_age_limit" : "integer 19..30",
          "over_age_limit_for_part_time_student" : "N/A or integer between 19..30",
          "aca" : "Please see ACA Types below"
        },
        "rate": {
          "rate_type" : "composite / age_banded / no_rates/ grand_fathered",
          "plan_type" : "buy_up/ buy_down, none",
          "employee_contributions" : {
             "employee" : "float",
             "employee_and_spouse" : "float",
             "employee_and_child" : "float",
             "employee_and_children" : "float",
             "employee_and_family" : "float"
          },
          "employer_contributions" : {
             "type" : "individual / blended",
             "rate_symbol": "dollar / percentage",
             "towards_employee" : "float / percentage",
             "towards_spouse" : "float / percentage",
             "towards_child" : "float / percentage",
             "towards_children" : "float / percentage",
             "towards_family" : "float / percentage"
          },
          "region_rates": [
            {
              "start_age": "integer",
              "end_age": "integer",
              "amount": "float"
            },
            {
              "start_age": "integer",
              "end_age": "integer",
              "amount": "float"
            },
            {
              "start_age": "integer",
              "end_age": "integer",
              "amount": "float"
            }
          ]
        }
      }'

Response

{
  "id": "03ba9868-c82f-4cd7-8d8f-37deaa0ad406",
  "name" : "Medical Plan",
  "description" : "This Plan Is HDMP",
  "carrier_id" : "cf2f4e5a-8e72-40e8-ab57-e1cbdc17eecf",
  "type": "default/High Deductable",
  "out_of_network" : 100.00,
  "emergency" : 100.00,
  "hmo" : true,
  "deductibles" : {
    "individual" : 100.00,
    "family" : 100.00
  },
  "pocket_max" : {
    "individual" : 100.00,
    "family" : 100.00
  },
  "co_pay" : {
    "office" : 100.00,
    "specialist" : 100.00
  },
  "rx" : {
    "deductible" : 100.00,
    "generic" : 100.00,
    "speciality" : 100.00,
    "brand" : 100.00
  },
  "document_url": [
    "https://document.url",
    "https://document.url",
    "https://document.url"
  ],
  "configuration": {
    "start_date" : "2017-10-20T23:59:59.000-08:00",
    "end_date" : "2017-12-20T23:59:59.000-08:00",
    "enrollement_type" : "active",
    "pre_tax" : "yes",
    "new_hire_waiting_period" : "30_days_from_hire_date",
    "benefits_termination_waiting_period" : "same_day_termination",
    "over_age_limit" : 24,
    "over_age_limit_for_part_time_student" : 30
  },
  "rate": {
    "rate_type" : "composite",
    "plan_type" : "buy_up",
    "employee_contributions" : {
       "employee" : 100.00,
       "employee_and_spouse" : 300.00,
       "employee_and_child" :  400.00,
       "employee_and_children" : 300.00,
       "employee_and_family" : 100.00
    },
    "employer_contributions" : {
       "type" : "individual",
       "towards_employee" : 100.00,
       "towards_spouse" : 100.00,
       "towards_child" : 1000.00,
       "towards_children" : 1000.00,
       "towards_family" : 10000.00
    },
    "region_rates": [
      {
        "start_age": 20,
        "end_age": 30,
        "amount": 100
      },
      {
        "start_age": 30,
        "end_age": 40,
        "amount": 200
      },
      {
        "start_age": 40,
        "end_age": 50,
        "amount": 300
      }
    ]
  }
}

Creates a Medical Plan

POST v1/companies/:uuid/plans/medical

New hire waiting period

Benefits termination waiting period

ACA Types

Required fields are:-

Update a Medical Plan

Update a Medical Plan

curl  -X PATCH \
      -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/medical/{medical_plan_id}
      -d '
        {
          "id": "c17d517d-817a-4738-901f-e0ba2c878922"
        }
      '

Updates a Medical Plan

PATCH v1/companies/medical/{medical_plan_id}

Arguments

Type Description
id uuid Medical Plan ID required

Dental Plans

Vision Plans

HSA Plans

FSA Plans

Transit Plans

Group Plans

Voluntary Plans

Deductions

All Deductions

All Deductions

curl  -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/company/{company_id}/deductions
[
  {
    "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/company/{company_id}/deductions

Attributes

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

Individual Deductions

curl  -H 'Accept: application/json' \
      -H 'Authorization:Bearer YOUR-API-TOKEN-HERE' \
      -i https://api.helloflock.com/v1/employees/:employee_id/deductions
[
  {
    "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/employees/:employee_id/deductions

Attributes

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

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.