Create Time Off

curl --request POST \
  --url https://api.bindbee.dev/api/hris/v1/time-off \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Connector-Token: <api-key>' \
  --data '
{
  "employee": "018b4bfb-5ece-70b1-ad5e-862a9433aa65",
  "approver": "018b4bfb-6065-7f83-b11d-e85ea49e37c3",
  "status": "APPROVED",
  "employee_note": "Paid paid vacation! Scuba diving in Hawaii.",
  "units": "HOURS",
  "amount": 12
}
'

import requests

url = "https://api.bindbee.dev/api/hris/v1/time-off"

payload = {
    "employee": "018b4bfb-5ece-70b1-ad5e-862a9433aa65",
    "approver": "018b4bfb-6065-7f83-b11d-e85ea49e37c3",
    "status": "APPROVED",
    "employee_note": "Paid paid vacation! Scuba diving in Hawaii.",
    "units": "HOURS",
    "amount": 12
}
headers = {
    "Authorization": "Bearer <token>",
    "X-Connector-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'X-Connector-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    employee: '018b4bfb-5ece-70b1-ad5e-862a9433aa65',
    approver: '018b4bfb-6065-7f83-b11d-e85ea49e37c3',
    status: 'APPROVED',
    employee_note: 'Paid paid vacation! Scuba diving in Hawaii.',
    units: 'HOURS',
    amount: 12
  })
};

fetch('https://api.bindbee.dev/api/hris/v1/time-off', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bindbee.dev/api/hris/v1/time-off",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'employee' => '018b4bfb-5ece-70b1-ad5e-862a9433aa65',
    'approver' => '018b4bfb-6065-7f83-b11d-e85ea49e37c3',
    'status' => 'APPROVED',
    'employee_note' => 'Paid paid vacation! Scuba diving in Hawaii.',
    'units' => 'HOURS',
    'amount' => 12
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-Connector-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bindbee.dev/api/hris/v1/time-off"

	payload := strings.NewReader("{\n  \"employee\": \"018b4bfb-5ece-70b1-ad5e-862a9433aa65\",\n  \"approver\": \"018b4bfb-6065-7f83-b11d-e85ea49e37c3\",\n  \"status\": \"APPROVED\",\n  \"employee_note\": \"Paid paid vacation! Scuba diving in Hawaii.\",\n  \"units\": \"HOURS\",\n  \"amount\": 12\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("X-Connector-Token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.bindbee.dev/api/hris/v1/time-off")
  .header("Authorization", "Bearer <token>")
  .header("X-Connector-Token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"employee\": \"018b4bfb-5ece-70b1-ad5e-862a9433aa65\",\n  \"approver\": \"018b4bfb-6065-7f83-b11d-e85ea49e37c3\",\n  \"status\": \"APPROVED\",\n  \"employee_note\": \"Paid paid vacation! Scuba diving in Hawaii.\",\n  \"units\": \"HOURS\",\n  \"amount\": 12\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bindbee.dev/api/hris/v1/time-off")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Connector-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"employee\": \"018b4bfb-5ece-70b1-ad5e-862a9433aa65\",\n  \"approver\": \"018b4bfb-6065-7f83-b11d-e85ea49e37c3\",\n  \"status\": \"APPROVED\",\n  \"employee_note\": \"Paid paid vacation! Scuba diving in Hawaii.\",\n  \"units\": \"HOURS\",\n  \"amount\": 12\n}"

response = http.request(request)
puts response.read_body

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

POST

api

hris

time-off

Create Time Off

curl --request POST \
  --url https://api.bindbee.dev/api/hris/v1/time-off \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Connector-Token: <api-key>' \
  --data '
{
  "employee": "018b4bfb-5ece-70b1-ad5e-862a9433aa65",
  "approver": "018b4bfb-6065-7f83-b11d-e85ea49e37c3",
  "status": "APPROVED",
  "employee_note": "Paid paid vacation! Scuba diving in Hawaii.",
  "units": "HOURS",
  "amount": 12
}
'

import requests

url = "https://api.bindbee.dev/api/hris/v1/time-off"

payload = {
    "employee": "018b4bfb-5ece-70b1-ad5e-862a9433aa65",
    "approver": "018b4bfb-6065-7f83-b11d-e85ea49e37c3",
    "status": "APPROVED",
    "employee_note": "Paid paid vacation! Scuba diving in Hawaii.",
    "units": "HOURS",
    "amount": 12
}
headers = {
    "Authorization": "Bearer <token>",
    "X-Connector-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'X-Connector-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    employee: '018b4bfb-5ece-70b1-ad5e-862a9433aa65',
    approver: '018b4bfb-6065-7f83-b11d-e85ea49e37c3',
    status: 'APPROVED',
    employee_note: 'Paid paid vacation! Scuba diving in Hawaii.',
    units: 'HOURS',
    amount: 12
  })
};

fetch('https://api.bindbee.dev/api/hris/v1/time-off', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bindbee.dev/api/hris/v1/time-off",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'employee' => '018b4bfb-5ece-70b1-ad5e-862a9433aa65',
    'approver' => '018b4bfb-6065-7f83-b11d-e85ea49e37c3',
    'status' => 'APPROVED',
    'employee_note' => 'Paid paid vacation! Scuba diving in Hawaii.',
    'units' => 'HOURS',
    'amount' => 12
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-Connector-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bindbee.dev/api/hris/v1/time-off"

	payload := strings.NewReader("{\n  \"employee\": \"018b4bfb-5ece-70b1-ad5e-862a9433aa65\",\n  \"approver\": \"018b4bfb-6065-7f83-b11d-e85ea49e37c3\",\n  \"status\": \"APPROVED\",\n  \"employee_note\": \"Paid paid vacation! Scuba diving in Hawaii.\",\n  \"units\": \"HOURS\",\n  \"amount\": 12\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("X-Connector-Token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.bindbee.dev/api/hris/v1/time-off")
  .header("Authorization", "Bearer <token>")
  .header("X-Connector-Token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"employee\": \"018b4bfb-5ece-70b1-ad5e-862a9433aa65\",\n  \"approver\": \"018b4bfb-6065-7f83-b11d-e85ea49e37c3\",\n  \"status\": \"APPROVED\",\n  \"employee_note\": \"Paid paid vacation! Scuba diving in Hawaii.\",\n  \"units\": \"HOURS\",\n  \"amount\": 12\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bindbee.dev/api/hris/v1/time-off")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Connector-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"employee\": \"018b4bfb-5ece-70b1-ad5e-862a9433aa65\",\n  \"approver\": \"018b4bfb-6065-7f83-b11d-e85ea49e37c3\",\n  \"status\": \"APPROVED\",\n  \"employee_note\": \"Paid paid vacation! Scuba diving in Hawaii.\",\n  \"units\": \"HOURS\",\n  \"amount\": 12\n}"

response = http.request(request)
puts response.read_body

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

Usecases

Create a Time Off Request - submit a time off request into the customer’s HRIS

This endpoint creates a Timeoff Entry in the connected HRIS via Bindbee’s unified Time Off model.

Provider-specific behavior

Different HRIS systems can have slightly different requirements and behaviors when creating timeoff entries. Use the accordions below to see details for each provider.

ADP

When the underlying HRIS is ADP, a Timesheet Entry can be created using a payload like:

{
    "employee": "01929f6e-c6c1-74b4-8119-a7d9efc0c8b8",
    "amount": 8,
    "start_time": "2024-09-04T08:00:00Z",
    "end_time": "2024-09-04T16:00:00Z",
    "request_type": "VACATION"
}

Authorizations

Authorization

string

header

default:<BINDBEE_API_KEY>

required

Your Bindbee API key, sent as Authorization: Bearer <BINDBEE_API_KEY>. Required on every request.

X-Connector-Token

string

header

default:<CONNECTOR_TOKEN>

required

The connector token for one customer's connection. This is not your Bindbee API key. Required on requests that read or write a single customer's data.

Headers

x-idempotency-key

string | null

Key to guarantee idempotent write execution.

Body

application/json

ADP
Dayforce
Workday

employee

string<uuid>

required

The employee requesting time off.

Example:

"018b4bfb-5ece-70b1-ad5e-862a9433aa65"

status

enum<string>

required

The status of this time off request. If the value is not one of the defined enum values, the original value passed through will be returned.

Available options:

REQUESTED,

APPROVED,

DECLINED,

CANCELLED,

DELETED

Example:

"CANCELLED"

units

enum<string>

required

The measurement that the third-party integration uses to count time requested. If the value is not one of the defined enum values, the original value passed through will be returned.

Available options:

HOURS,

DAYS

Example:

"HOURS"

amount

number | null

required

The time off quantity measured by the prescribed “units”.

Example:

12

request_type

string

required

The type of time off request. If the value is not one of the defined enum values, the original value passed through will be returned.

Example:

"VACATION"

start_time

string

required

The start date time of the time off in ISO 8601 format.

Example:

"2026-03-26T06:42:43.324Z"

end_time

string

required

The end date time of the time off in ISO 8601 format.

Example:

"2026-03-26T08:42:43.324Z"

employee_note

string | null

default:""

The employee note for this time off request.

Example:

"Paid paid vacation! Scuba diving in Hawaii."

additional_attributes

Additional Attributes · object

Additional attributes that Bindbee doesn't supports but you might want to pass for the write operation.

Example:

{
  "notes": "The leave is approved by manager"
}

Response

Successful Response

API Basics

Platform

HR & Payroll (HRIS)

Recruiting (ATS)

Learning (LMS)

Create Time Off

Provider-specific behavior

Authorizations

Headers

Body

Response

​Provider-specific behavior

Authorizations

Headers

Body

Response

Provider-specific behavior