Import entitlements

curl --request POST \
  --url https://{host}/timmi-absences/api/public/services/v1.0/leaveEntitlementsImport \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: multipart/form-data' \
  --form File='@example-file' \
  --form 'Description=<string>' \
  --form ReferenceDate=2023-11-07T05:31:56Z

import requests

url = "https://{host}/timmi-absences/api/public/services/v1.0/leaveEntitlementsImport"

files = { "File": ("example-file", open("example-file", "rb")) }
payload = {
    "Description": "<string>",
    "ReferenceDate": "2023-11-07T05:31:56Z"
}
headers = {"Authorization": "<authorization>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('File', '<string>');
form.append('Description', '<string>');
form.append('ReferenceDate', '2023-11-07T05:31:56Z');

const options = {method: 'POST', headers: {Authorization: '<authorization>'}};

options.body = form;

fetch('https://{host}/timmi-absences/api/public/services/v1.0/leaveEntitlementsImport', 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://{host}/timmi-absences/api/public/services/v1.0/leaveEntitlementsImport",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"File\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"Description\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"ReferenceDate\"\r\n\r\n2023-11-07T05:31:56Z\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: multipart/form-data"
  ],
]);

$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://{host}/timmi-absences/api/public/services/v1.0/leaveEntitlementsImport"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"File\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"Description\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"ReferenceDate\"\r\n\r\n2023-11-07T05:31:56Z\r\n-----011000010111000001101001--")

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

	req.Header.Add("Authorization", "<authorization>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{host}/timmi-absences/api/public/services/v1.0/leaveEntitlementsImport")
  .header("Authorization", "<authorization>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"File\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"Description\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"ReferenceDate\"\r\n\r\n2023-11-07T05:31:56Z\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{host}/timmi-absences/api/public/services/v1.0/leaveEntitlementsImport")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"File\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"Description\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"ReferenceDate\"\r\n\r\n2023-11-07T05:31:56Z\r\n-----011000010111000001101001--"

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

{
  "successLinesCount": 0,
  "globalErrors": {
    "columnsFormatNotSupported": "The file must have columns 'login, lastName, firstName' or 'code, employeeNumber, lastName, firstName'."
  },
  "lineErrors": {
    "7": {
      "loginNotFound": "User login not found"
    },
    "8": {
      "duplicatedLine": "Line 8 is identical to line 23"
    },
    "9": {
      "lastLameNotMatchingLogin": "Lastname does not match to the login of this employee",
      "accountNotAvailableForUser": "The user does not have access to the account 6"
    }
  }
}

{
  "Status": 401,
  "Message": "Unauthorized"
}

Imports

Import entitlements

Import entitlements credits leave accounts by adding the values provided in the import file to the employees’ existing balances. Each value in the file is treated as a new credit entry, increasing the current entitlement total. This operation generates new accounting entries of type “entitlements import”. It corresponds to the “Entitlements import” feature in the Lucca Absences UI. See the Entitlements imports guide to understand the differences with Replace entitlements.

Supported file formats:

CSV
- “UTF-8” encoding
- separator “;”
XSLX

Columns to fill in:

Column name	Description
`LegalEntityCode`	Employee legal entity code.
`EmployeeNumber`	Employee payroll number.
`LastName`	Last name.
`FirstName`	First name.
Account number or name (one column per account)	Value to import for the account defined in the header.

Remark: A template file can be downloaded from the import page (Credit / Debit> A group of collaborators> File import).

In the event of a malformed (or unrecognized) file, no data will be imported; the problems detected will be specified in the globalErrors field.

If successful, the number of imported lines is indicated by the “successLinesCount” field; the lines in error are detailed in the lineErrors field.

Remarks: Any import made by the API is of course available in the import history. A simulation returns the same level of information, but does not trigger an import

List of errors handled

Here is the list of fatal errors, which can be returned in the globalErrors:

Unauthorized
FileEmpty,
FileExtensionNotSupported,
ColumnsFormatNotSupported,
AccountColumnMissing,
ColumnNamesDistinct,
LineErrorForbiddenInStrictMode,

The list of line processing errors, which can be restored in the lineErrors:

AccountNotFound,
AccountsNotFound,
AccountColumnsProcessing,
LegalEntityCodesNotFound,
MissingValuesForAccount,
AccountNotAvailableForUser,
LegalEntityCodeRequired,
EmployeeNumberRequired,
LoginRequired,
LoginNotFound,
AccountNumberRequired,
LegalEntityNotFound,
EmployeeNumberNotExist,
EmployeeNumberNotInLegalEntity,
FistNameAndLastNameNotMatching,
FistNameNotMatching,
LastLameNotMatching,
FistNameAndLastNameNotMatchingEmployeeNumber,
FistNameNotMatchingEmployeeNumber,
LastLameNotMatchingEmployeeNumber,
FistNameAndLastNameNotMatchingLogin,
FistNameNotMatchingLogin,
LastLameNotMatchingLogin,
DuplicatedLine,
AmbiguousLegalEntity,
ColumnNotExists,
LegalEntityNameNotAvailable,
AccountNameNotUnique

The list of import generation errors:

UnableToCreditAccount

POST

timmi-absences

api

public

services

v1.0

leaveEntitlementsImport

Import entitlements

curl --request POST \
  --url https://{host}/timmi-absences/api/public/services/v1.0/leaveEntitlementsImport \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: multipart/form-data' \
  --form File='@example-file' \
  --form 'Description=<string>' \
  --form ReferenceDate=2023-11-07T05:31:56Z

import requests

url = "https://{host}/timmi-absences/api/public/services/v1.0/leaveEntitlementsImport"

files = { "File": ("example-file", open("example-file", "rb")) }
payload = {
    "Description": "<string>",
    "ReferenceDate": "2023-11-07T05:31:56Z"
}
headers = {"Authorization": "<authorization>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('File', '<string>');
form.append('Description', '<string>');
form.append('ReferenceDate', '2023-11-07T05:31:56Z');

const options = {method: 'POST', headers: {Authorization: '<authorization>'}};

options.body = form;

fetch('https://{host}/timmi-absences/api/public/services/v1.0/leaveEntitlementsImport', 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://{host}/timmi-absences/api/public/services/v1.0/leaveEntitlementsImport",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"File\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"Description\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"ReferenceDate\"\r\n\r\n2023-11-07T05:31:56Z\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: multipart/form-data"
  ],
]);

$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://{host}/timmi-absences/api/public/services/v1.0/leaveEntitlementsImport"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"File\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"Description\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"ReferenceDate\"\r\n\r\n2023-11-07T05:31:56Z\r\n-----011000010111000001101001--")

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

	req.Header.Add("Authorization", "<authorization>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{host}/timmi-absences/api/public/services/v1.0/leaveEntitlementsImport")
  .header("Authorization", "<authorization>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"File\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"Description\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"ReferenceDate\"\r\n\r\n2023-11-07T05:31:56Z\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{host}/timmi-absences/api/public/services/v1.0/leaveEntitlementsImport")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"File\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"Description\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"ReferenceDate\"\r\n\r\n2023-11-07T05:31:56Z\r\n-----011000010111000001101001--"

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

{
  "successLinesCount": 0,
  "globalErrors": {
    "columnsFormatNotSupported": "The file must have columns 'login, lastName, firstName' or 'code, employeeNumber, lastName, firstName'."
  },
  "lineErrors": {
    "7": {
      "loginNotFound": "User login not found"
    },
    "8": {
      "duplicatedLine": "Line 8 is identical to line 23"
    },
    "9": {
      "lastLameNotMatchingLogin": "Lastname does not match to the login of this employee",
      "accountNotAvailableForUser": "The user does not have access to the account 6"
    }
  }
}

{
  "Status": 401,
  "Message": "Unauthorized"
}

Headers

Authorization

string

required

API key. Value must be formatted like so: lucca application={api_key}.

Query Parameters

strict

boolean

default:false

In strict mode, if the import has errors, nothing is imported. Without strict mode, the lines in error are ignored and those in success are imported.

simulate

boolean

default:false

Allows you to simulate the import. In this case, the response indicates the theoretical result of the import without any data being recorded.

Body

multipart/form-data

File

file

Description

string

Description of the entries generated by the import (visible to users in the account details).

ReferenceDate

string<date-time>

Reference date (text mode). Respect the format: yyyy-MM-ddThh: mm: ss

Response

Example response

successLinesCount

integer

globalErrors

object

lineErrors

object

Documentation

Files

Organization Structure API

Core HR API

Recruitment API

Expenses API

Invoices API

Absences API

Office API

Project API

Schedule API

Timesheet API

Mealvouchers API

Compensation API

Training API

Import entitlements

Headers

Query Parameters

Body

Response