Bizimply Public API
Overview
Apps and partners that wish to use the Bizimply API to extend their system functionality (e.g. automatically sending the newly hired employee data from the ATS into Bizimply for their customers) or access data on behalf of their customers (e.g. get timecard data for better labor cost analysis) need to get their customer’s consent for the scope of permissions their app would have in the interaction with the data in Bizimply.Â
The typical authorization flow is where customers grant external apps the permissions for a required purpose. Each app would have to embed a Bizimply link or button for their customers to start the authorization flow, where they allow your app to interact with their Bizimply data securely via our APIs.
Once a customer completes the authorization flow and grants permission to connect your app to Bizimply, an access token and a refresh token are returned to your app using the fallback URL you provide. That access token is authorized to call Bizimply API on that customer’s behalf while the refresh token is used to generate a new access token every 8 hours.
API Key Deprecation Notice
On March 31, 2023, Bizimply is no longer recommending the use of API key authentication to access API resources. You can continue to use the existing API keys in authentication during the depreciation period until it is EOL on April 30, 2023.
Getting Started
Once your customer gets their API access enabled for their Bizimply account*, getting started with the integration is as easy as 1, 2, 3!
- Create a button or a link on your side for establishing the connection with Bizimply using the following URL:
<BASEURL>/api_keys/new?fallback_url=<URL>&validation=<ATTRIBUTE>
- BASEURL: (mandatory)
- Production: https://app.bizimply.comÂ
- Staging: https://app.shiftdiary.com
- URL: (mandatory)
- Link to a POST request on your side to receive the access_token and refresh_token. It should always return 201 Created
- ATTRIBUTE: (optional)
- A string attribute that you can send us and receive back to verify your request
2. The customer clicks your button/link which redirects them to Bizimply’s API access management page. They select which permissions this key will have access to, according to your integration needs, and click Save
3. A POST request is sent to your fallback URL with the  access_token and refresh_token in the request body, like the sample below:
Â
{
"access_token": "access token",
"refresh_token": "refresh token"
}
Note that your system must respond to the POST request with status code 201 Created for the tokens to be activated, otherwise they will be invalidated immediately
Voila! you now have access to the APIs your customer authorized and you can start making API calls!
* Customers will need to contact their account managers to ensure their account is eligible for the API feature. Once eligibility is confirmed, a request to enable the feature is made. As soon as it’s enabled you can proceed
Making Your First API Call
There are specific request headers that need to be set for the API calls to go through successfully; the Authorization and the Accept headers. The Accept header will have a fixed value but the Authorization header will use the most recent access_token saved in your database.
You will also need to make a periodic PATCH request to refresh the access_token as it expires 8 hours after generation.
Request Headers
You’ll need to add the following headers to all your API requests
Accept: application/public.bizimply.v1
Authorization: Bearer <TOKEN>
- TOKEN: (mandatory)
The most recent access_token available in your database.
Note that the first request will use the access_token received in the initial authorization POST request.Â
Token Refresh
A PATCH request is made with the most recent access_token saved in your database and the refresh_token in the request body, like the sample below:
Method: PATCH
Endpoint: /api/sessions/reauthorize
Sample Body
{
"last_access_token": "access token",
"refresh_token": "refresh token"
}
Sample Response
{
"access_token": "access token",
"refresh_token": "refresh token"
}
List of HR API Endpoints
Listed below are the current API endpoints that are available for the HR module integration, the ones related to company, locations, and employees.
Company APIs
Location APIs
Employee APIs
View Company Details
Using company ID, shows the company details, associated locations IDs.
Method: GET
Endpoint: /api/companies/{{company_id}}
Sample Body: N/A
Sample Response:
{
"data": {
"id": "1234",
"type": "company",
"attributes": {
"name": "Company Name",
"subdomain": "companyname",
"logo": null,
"customer_type": 3,
"expired_trial_from": "2022-04-04T23:00:00.000Z"
},
"relationships": {
"stores": {
"data": [
{
"id": "11111",
"type": "store"
},
{
"id": "22222",
"type": "store"
},
{
"id": "33333",
"type": "store"
},
{
"id": "44444",
"type": "store"
}
]
}
}
}
}
View Company Locations
Using company ID, shows the location details for all locations created under this company.
Method: GET
Endpoint: /api/companies/{{company_id}}/stores
Sample Body: N/A
Sample Response:
{
"data": [
{
"id": "11111",
"type": "store",
"attributes": {
"location_name": "Location Name 1",
"weather_data": [
{
"time": 1650924000,
"summary": "Partly cloudy throughout the day.",
"icon": "partly-cloudy-day",
"sunriseTime": 1650943080,
"sunsetTime": 1650990600,
"moonPhase": 0.87,
"precipIntensity": 0,
"precipIntensityMax": 0,
"precipProbability": 0,
"temperatureHigh": 96.36,
"temperatureHighTime": 1650983280,
"temperatureLow": 61.49,
"temperatureLowTime": 1651029360,
"apparentTemperatureHigh": 95.86,
"apparentTemperatureHighTime": 1650983280,
"apparentTemperatureLow": 61.98,
"apparentTemperatureLowTime": 1651029360,
"dewPoint": 39.45,
"humidity": 0.33,
"pressure": 1009.9,
"windSpeed": 11.31,
"windGust": 25.93,
"windGustTime": 1650996240,
"windBearing": 29,
"cloudCover": 0.43,
"uvIndex": 6,
"uvIndexTime": 1650965580,
"visibility": 10,
"ozone": 309.5,
"temperatureMin": 62.35,
"temperatureMinTime": 1650943860,
"temperatureMax": 96.36,
"temperatureMaxTime": 1650983280,
"apparentTemperatureMin": 62.84,
"apparentTemperatureMinTime": 1650943860,
"apparentTemperatureMax": 95.86,
"apparentTemperatureMaxTime": 1650983280
},
{
"time": 1651010400,
"summary": "Clear throughout the day.",
"icon": "clear-day",
"sunriseTime": 1651029420,
"sunsetTime": 1651077060,
"moonPhase": 0.9,
"precipIntensity": 0,
"precipIntensityMax": 0,
"precipProbability": 0,
"temperatureHigh": 95.41,
"temperatureHighTime": 1651069860,
"temperatureLow": 60.72,
"temperatureLowTime": 1651114620,
"apparentTemperatureHigh": 94.91,
"apparentTemperatureHighTime": 1651069860,
"apparentTemperatureLow": 61.21,
"apparentTemperatureLowTime": 1651114620,
"dewPoint": 37.84,
"humidity": 0.31,
"pressure": 1010,
"windSpeed": 10.64,
"windGust": 25.32,
"windGustTime": 1651081740,
"windBearing": 23,
"cloudCover": 0.09,
"uvIndex": 10,
"uvIndexTime": 1651053240,
"visibility": 10,
"ozone": 318.1,
"temperatureMin": 61.49,
"temperatureMinTime": 1651029360,
"temperatureMax": 95.41,
"temperatureMaxTime": 1651069860,
"apparentTemperatureMin": 61.98,
"apparentTemperatureMinTime": 1651029360,
"apparentTemperatureMax": 94.91,
"apparentTemperatureMaxTime": 1651069860
},
{
"time": 1651096800,
"summary": "Clear throughout the day.",
"icon": "clear-day",
"sunriseTime": 1651115760,
"sunsetTime": 1651163460,
"moonPhase": 0.93,
"precipIntensity": 0,
"precipIntensityMax": 0,
"precipProbability": 0,
"temperatureHigh": 94.98,
"temperatureHighTime": 1651152720,
"temperatureLow": 65.86,
"temperatureLowTime": 1651201080,
"apparentTemperatureHigh": 94.48,
"apparentTemperatureHighTime": 1651152720,
"apparentTemperatureLow": 66.35,
"apparentTemperatureLowTime": 1651201080,
"dewPoint": 36.02,
"humidity": 0.29,
"pressure": 1009.3,
"windSpeed": 10.93,
"windGust": 24.28,
"windGustTime": 1651168920,
"windBearing": 40,
"cloudCover": 0.13,
"uvIndex": 11,
"uvIndexTime": 1651139640,
"visibility": 10,
"ozone": 301.2,
"temperatureMin": 60.72,
"temperatureMinTime": 1651114620,
"temperatureMax": 94.98,
"temperatureMaxTime": 1651152720,
"apparentTemperatureMin": 61.21,
"apparentTemperatureMinTime": 1651114620,
"apparentTemperatureMax": 94.48,
"apparentTemperatureMaxTime": 1651152720
},
{
"time": 1651183200,
"summary": "Partly cloudy throughout the day.",
"icon": "partly-cloudy-day",
"sunriseTime": 1651202100,
"sunsetTime": 1651249920,
"moonPhase": 0.97,
"precipIntensity": 0.0001,
"precipIntensityMax": 0.0018,
"precipIntensityMaxTime": 1651269600,
"precipProbability": 0.04,
"precipType": "rain",
"temperatureHigh": 101.17,
"temperatureHighTime": 1651236900,
"temperatureLow": 67.75,
"temperatureLowTime": 1651287420,
"apparentTemperatureHigh": 100.67,
"apparentTemperatureHighTime": 1651236900,
"apparentTemperatureLow": 68.24,
"apparentTemperatureLowTime": 1651287420,
"dewPoint": 19.72,
"humidity": 0.13,
"pressure": 1006.4,
"windSpeed": 10.57,
"windGust": 30.08,
"windGustTime": 1651254300,
"windBearing": 53,
"cloudCover": 0.4,
"uvIndex": 8,
"uvIndexTime": 1651224420,
"visibility": 10,
"ozone": 290,
"temperatureMin": 65.86,
"temperatureMinTime": 1651201080,
"temperatureMax": 101.17,
"temperatureMaxTime": 1651236900,
"apparentTemperatureMin": 66.35,
"apparentTemperatureMinTime": 1651201080,
"apparentTemperatureMax": 100.67,
"apparentTemperatureMaxTime": 1651236900
},
{
"time": 1651269600,
"summary": "Clear throughout the day.",
"icon": "clear-day",
"sunriseTime": 1651288440,
"sunsetTime": 1651336320,
"moonPhase": 1,
"precipIntensity": 0.0003,
"precipIntensityMax": 0.0021,
"precipIntensityMaxTime": 1651273620,
"precipProbability": 0.04,
"precipType": "rain",
"temperatureHigh": 99.67,
"temperatureHighTime": 1651322400,
"temperatureLow": 60.97,
"temperatureLowTime": 1651372620,
"apparentTemperatureHigh": 99.17,
"apparentTemperatureHighTime": 1651322400,
"apparentTemperatureLow": 61.67,
"apparentTemperatureLowTime": 1651372800,
"dewPoint": 41.33,
"humidity": 0.29,
"pressure": 1007.5,
"windSpeed": 13.36,
"windGust": 29.95,
"windGustTime": 1651291200,
"windBearing": 353,
"cloudCover": 0.02,
"uvIndex": 11,
"uvIndexTime": 1651312380,
"visibility": 10,
"ozone": 300.7,
"temperatureMin": 67.07,
"temperatureMinTime": 1651356000,
"temperatureMax": 99.67,
"temperatureMaxTime": 1651322400,
"apparentTemperatureMin": 67.57,
"apparentTemperatureMinTime": 1651356000,
"apparentTemperatureMax": 99.17,
"apparentTemperatureMaxTime": 1651322400
},
{
"time": 1651356000,
"summary": "Partly cloudy throughout the day.",
"icon": "partly-cloudy-day",
"sunriseTime": 1651374780,
"sunsetTime": 1651422780,
"moonPhase": 0.03,
"precipIntensity": 0,
"precipIntensityMax": 0,
"precipProbability": 0,
"temperatureHigh": 93.54,
"temperatureHighTime": 1651411440,
"temperatureLow": 63.57,
"temperatureLowTime": 1651458660,
"apparentTemperatureHigh": 93.04,
"apparentTemperatureHighTime": 1651411440,
"apparentTemperatureLow": 64.06,
"apparentTemperatureLowTime": 1651458660,
"dewPoint": 50.92,
"humidity": 0.5,
"pressure": 1011.7,
"windSpeed": 8.09,
"windGust": 20.87,
"windGustTime": 1651426860,
"windBearing": 355,
"cloudCover": 0.37,
"uvIndex": 9,
"uvIndexTime": 1651398240,
"visibility": 10,
"ozone": 296.5,
"temperatureMin": 60.97,
"temperatureMinTime": 1651372620,
"temperatureMax": 93.54,
"temperatureMaxTime": 1651411440,
"apparentTemperatureMin": 61.67,
"apparentTemperatureMinTime": 1651372800,
"apparentTemperatureMax": 93.04,
"apparentTemperatureMaxTime": 1651411440
},
{
"time": 1651442400,
"summary": "Partly cloudy throughout the day.",
"icon": "partly-cloudy-day",
"sunriseTime": 1651461120,
"sunsetTime": 1651509240,
"moonPhase": 0.06,
"precipIntensity": 0,
"precipIntensityMax": 0,
"precipProbability": 0,
"temperatureHigh": 100.36,
"temperatureHighTime": 1651497780,
"temperatureLow": 68.5,
"temperatureLowTime": 1651546320,
"apparentTemperatureHigh": 99.86,
"apparentTemperatureHighTime": 1651497780,
"apparentTemperatureLow": 68.99,
"apparentTemperatureLowTime": 1651546320,
"dewPoint": 42.33,
"humidity": 0.32,
"pressure": 1007.4,
"windSpeed": 6.19,
"windGust": 26.05,
"windGustTime": 1651524060,
"windBearing": 45,
"cloudCover": 0.66,
"uvIndex": 11,
"uvIndexTime": 1651483680,
"visibility": 10,
"ozone": 292.9,
"temperatureMin": 63.57,
"temperatureMinTime": 1651458660,
"temperatureMax": 100.36,
"temperatureMaxTime": 1651497780,
"apparentTemperatureMin": 64.06,
"apparentTemperatureMinTime": 1651458660,
"apparentTemperatureMax": 99.86,
"apparentTemperatureMaxTime": 1651497780
},
{
"time": 1651528800,
"summary": "Windy in the morning.",
"icon": "wind",
"sunriseTime": 1651547520,
"sunsetTime": 1651595640,
"moonPhase": 0.09,
"precipIntensity": 0,
"precipIntensityMax": 0,
"precipProbability": 0,
"temperatureHigh": 93,
"temperatureHighTime": 1651582200,
"temperatureLow": 60.37,
"temperatureLowTime": 1651632180,
"apparentTemperatureHigh": 92.5,
"apparentTemperatureHighTime": 1651582200,
"apparentTemperatureLow": 60.86,
"apparentTemperatureLowTime": 1651632240,
"dewPoint": 53.68,
"humidity": 0.43,
"pressure": 1007.2,
"windSpeed": 10.87,
"windGust": 40.12,
"windGustTime": 1651559100,
"windBearing": 346,
"cloudCover": 0.81,
"uvIndex": 5,
"uvIndexTime": 1651571520,
"visibility": 10,
"ozone": 296.3,
"temperatureMin": 67.04,
"temperatureMinTime": 1651615200,
"temperatureMax": 93,
"temperatureMaxTime": 1651582200,
"apparentTemperatureMin": 67.53,
"apparentTemperatureMinTime": 1651615200,
"apparentTemperatureMax": 92.5,
"apparentTemperatureMaxTime": 1651582200
},
{
"updated_at": "2022-04-26T12:03:43.534+02:00"
}
],
"deactivated": false
},
"links": {
"self": "/api/companies/1234/stores/11111"
}
},
{
"id": "22222",
"type": "store",
"attributes": {
"location_name": "Location Name 2",
"weather_data": null,
"deactivated": false
},
"links": {
"self": "/api/companies/1234/stores/22222"
}
}
],
"meta": {
"total": 2
},
"links": {
"self": "https://app.bizimply.com/api/companies/1234/stores?",
"next": "https://app.bizimply.com/api/companies/1234/stores?page%5Bnumber%5D=1",
"prev": "https://app.bizimply.com/api/companies/1234/stores?page%5Bnumber%5D=1",
"first": "https://app.bizimply.com/api/companies/1234/stores?page%5Bnumber%5D=1",
"last": "https://app.bizimply.com/api/companies/1234/stores?page%5Bnumber%5D=1"
}
}
Create Company Locations
Using company ID, add a new location under this company using at least location name attribute. Allowed attributes listed below in the Request Body
Method: POST
Endpoint: /api/companies/{{company_id}}/stores
Sample Body:
{
"location_name":"Location Name",
"payroll_code": "Payroll Code"
}
Sample Response: N/A
Status Code: 201 Created
View Locations
Using location ID, shows the location details and weather forecast for 7 days
Method: GET
Endpoint: /api/stores/{{store_id}}
Sample Body: N/A
Sample Response:
{
"data": [
{
"id": "11111",
"type": "store",
"attributes": {
"location_name": "Location Name 1",
"weather_data": [
{
"time": 1649282400,
"summary": "Partly cloudy throughout the day.",
"icon": "partly-cloudy-day",
"sunriseTime": 1649302620,
"sunsetTime": 1649348220,
"moonPhase": 0.21,
"precipIntensity": 0,
"precipIntensityMax": 0,
"precipProbability": 0,
"temperatureHigh": 100.37,
"temperatureHighTime": 1649332800,
"temperatureLow": 68.58,
"temperatureLowTime": 1649393880,
"apparentTemperatureHigh": 99.87,
"apparentTemperatureHighTime": 1649332800,
"apparentTemperatureLow": 69.07,
"apparentTemperatureLowTime": 1649393880,
"dewPoint": 26.6,
"humidity": 0.16,
"pressure": 1012.2,
"windSpeed": 7.57,
"windGust": 21.09,
"windGustTime": 1649367840,
"windBearing": 195,
"cloudCover": 0.54,
"uvIndex": 9,
"uvIndexTime": 1649326020,
"visibility": 10,
"ozone": 294.3,
"temperatureMin": 65.17,
"temperatureMinTime": 1649297700,
"temperatureMax": 100.37,
"temperatureMaxTime": 1649332800,
"apparentTemperatureMin": 65.66,
"apparentTemperatureMinTime": 1649297700,
"apparentTemperatureMax": 99.87,
"apparentTemperatureMaxTime": 1649332800
},
{
"updated_at": "2022-04-07T17:19:37.891+02:00"
}
],
"deactivated": false
},
"links": {
"self": "/api/companies/1234/stores/11111"
}
},
{
"id": "22222",
"type": "store",
"attributes": {
"location_name": "Location Name 2",
"weather_data": null,
"deactivated": false
},
"links": {
"self": "/api/companies/1234/stores/22222"
}
}
],
"meta": {
"total": 2
},
"links": {
"self": "https://app.bizimply.com/api/companies/1234/stores?",
"next": "https://app.bizimply.com/api/companies/1234/stores?page%5Bnumber%5D=1",
"prev": "https://app.bizimply.com/api/companies/1234/stores?page%5Bnumber%5D=1",
"first": "https://app.bizimply.com/api/companies/1234/stores?page%5Bnumber%5D=1",
"last": "https://app.bizimply.com/api/companies/1234/stores?page%5Bnumber%5D=1"
}
}
Update Location
Using location ID, update the location details such as name and payroll code.
Method: PUT
Endpoint: /api/stores/{{store_id}}
Sample Body:
{
"location_name":"Updated Location Name",
"payroll_code": "Updated Payroll Code",
}
Sample Response
{
"data": {
"id": "11111",
"type": "store",
"attributes": {
"location_name": "Updated Location Name",
"weather_data": null,
"deactivated": false
},
"links": {
"self": "/api/companies/1234/stores/11111"
}
},
"meta": {
"message": "Location was successfully updated."
}
}
Deactivate Locations
Using location ID, deactivate the location.
Method: POST
Endpoint: /api/stores/{{store_id}}/deactivate
Sample Body: N/A
Sample Response: N/A
Status Code: 204 No Content
Delete Locations
Using location ID, permanently delete the location. Note that this is an irreversible action so only use when absolutely necessary.
Method: DELETE
Endpoint: /api/stores/{{store_id}}
Sample Body: N/A
Sample Response: N/A
Status Code: 204 No Content
Create Employee Locations
Using location ID, add a new employee for this location using at least first_name and last_name attributes. Allowed attributes listed below in the sample request body
Method: POST
Endpoint: /api/stores/{{store_id}}/employees
Sample Body:
{
"employee": {
"title": "Ms",
"first_name": "First Name",
"last_name": "Last Name",
"email": "email@company.com",
"phone_number": "+000000000000",
"date_of_birth": "31/12/1999",
"gender": "prefer_not_to_say",
"ethnicity": "Ethnicity",
"nationality": "Nationality",
"marital_status": "it's complicated",
"passport_expiry": "30/11/2022",
"visa_expiry": "30/11/2022",
"start_date": "30/11/2020",
"emergency_contacts_attributes":[
{
"name":"Emergency Contact Name",
"phone":"00000000000",
"relationship":"father"
},
{
"name":"Emergency Contact Name",
"phone":"00000000000",
"relationship":"mother"
}
],
"employee_number": "ABC123",
"national_identifier": "123456",
"key_staff": "false",
"schedule_name": "Name",
"hourly": "false",
"pay_rate_weekly":"300.51",
"Labour_costing":0,
"pay_rate_hourly":"20.25",
"sunday_rate":"10.50",
"bank_holiday_rate":"10.00",
"overtime_rate_1":"11.00",
"overtime_rate_2":"10.00",
"max_daily_hours":"9",
"max_weekly_hours":"45",
"min_weekly_hours":"35",
"contracted_hours":"140",
"bank_detail_attributes":{
"bank_name":"Bank Name",
"branch_name":"Branch Name",
"bic":"BIC123",
"sort_code":"123456",
"account_number":"12345678",
"account_holder":"Account Holder Name",
"iban":"XX123412341XXX"
}
}
}
Sample Response: N/A
Status Code: 201 Created
Update Employee
Using employee ID, update a current employee’s information. Allowed attributes listed below in the sample request body
Method: PUT
Endpoint: /api/employees/{{employee_id}}
Sample Body:
{
"employee": {
"title": "Ms",
"first_name": "Updated First Name",
"last_name": "Updated Last Name",
"email": "updatedemail@company.com",
"phone_number": "+000000000000",
"date_of_birth": "31/12/1999",
"gender": "prefer_not_to_say",
"ethnicity": "Ethnicity",
"nationality": "Nationality",
"marital_status": "it's complicated",
"passport_expiry": "30/11/2022",
"visa_expiry": "30/11/2022",
"start_date": "30/11/2020",
"emergency_contacts_attributes":[
{
"name":"Emergency Contact Name",
"phone":"00000000000",
"relationship":"father"
}],
"employee_number": "ABC123",
"national_identifier": "123456",
"key_staff": "false",
"schedule_name": "Name",
"hourly": "false",
"pay_rate_weekly":"300.51",
"Labour_costing":0,
"pay_rate_hourly":"20.25",
"sunday_rate":"10.50",
"bank_holiday_rate":"10.00",
"overtime_rate_1":"11.00",
"overtime_rate_2":"10.00",
"max_daily_hours":"9",
"max_weekly_hours":"45",
"min_weekly_hours":"35",
"contracted_hours":"140",
"bank_detail_attributes":{
"bank_name":"Bank Name",
"branch_name":"Branch Name",
"bic":"BIC123",
"sort_code":"123456",
"account_number":"12345678",
"account_holder":"Account Holder Name",
"iban":"XX123412341XXX"
}
}
}
Sample Response
{
"data": {
"id": "123456",
"type": "employee",
"attributes": {
"first_name": "Updated First Name",
"last_name": "Updated Last Name",
"email": "updatedemail@company.com"
},
"links": {
"self": "/api/stores/11111/employees/123456"
}
},
"meta": {
"message": "Employee was successfully updated."
}
}
Status Code: 200 OK
Deactivate Employee
Using employee ID, deactivate a current employee.
Method: POST
Endpoint: /api/employees/{{employee_id}}/deactivate
Sample Body: N/A
Sample Response: N/A
Status Code: 204 No Content
Reactivate Employee
Using employee ID, reactivate a deactivated employee.Â
Method: POST
Endpoint: /api/employees/{{employee_id}}/reactivate
Sample Body: N/A
Sample Response: N/A
Status Code: 204 No Content