Migrate from leaves v2

Introduction

The v2 API will be shut down on March 31, 2026, and will no longer respond after this date.

This guide helps you migrate from the deprecated v2 leaves API endpoint to the v3. Why is the v2 deprecated? The v2 leaves API endpoint:

suffers from significant performance issues, that also affect other API endpoints;
relies on older technology, that may suffer from security vulnerabilities.

Whereas the v3 leaves API endpoint:

offers faster response times;
gives you additional features (pagination, sorting);
shares the same authentication system than v2.

Are you affected by this change? If there’s any HTTP request against the /api/leaves API endpoint in your integration, then you are affected by this and must migrate to /api/v3/leaves before 2026-03-31. Otherwise, you are free to skip this.

Changes

The V3 Leaves API endpoint is documented in the API Reference.

Routes

V2	V3
`/api/leaves`	`/api/v3/leaves`

Query parameters

api v2	api v3	Description
`owner.id`	`leavePeriod.ownerId`	Filter leaves by the employee ID they belong to.

Note: other query parameters did not change.

Response

In V2, all responses are a JSON object with a data property which is:

a JSON object for a response containing a singular resource;
a JSON array for a response containing a collection of resources.

In V3, all responses are a JSON object with a data property which is always a JSON object. For collections, it contains an items property, which is a JSON aray which contains the representations of resources in the collection.

type: object
properties:
  data:
    oneOf:
      - title: Single Leave
        $ref: "#/leave"
      - title: Collection of Leaves
        type: array
        items:
          $ref: "#/leave"

type: object
properties:
  data:
    oneOf:
      - title: Single Leave
        $ref: "#/leave"
      - title: Collection of Leaves
        type: object
        properties:
          items:
            type: array
            items:
              $ref: "#/leave"

Fields

Some of the fields were renamed, moved, removed and/or changed type.

V2	V3 Equivalent	Description
`id: string`	`id: string`	ID generation pattern changed-see below.
`status: string<enum>`	`status: string<enum>`	Represents the approval status of the leave. The enum was changed-see below.
`owner.id: integer`	`leavePeriod.ownerId: integer`	ID of the employee this leave belongs to. The owner is now a property of the `leavePeriod`.
`owner.name: string`	`leavePeriod.owner.name: string`	Name of the employee this leave belongs to.
`owner.mail: string<email>`	N/A	No longer available for security reasons*.
`owner.login: string`	N/A	No longer available for security reasons*.
`owner.matricule: string`	N/A	No longer available for security reasons*.
`name: string`	`leaveAccount.name: string`	In v2, the `name` was equal to the name of the leave account.
`duration: integer`	`duration: string<time>`	Duration of the leave, in minutes in v2 (e.g. `720`), as a time in v3 (e.g. `"12:00:00"`).
`accountCode: string`	`leaveAccount.id: integer`	Unique identifier of the leave account.
`accountLabel: string`	`leaveAccount.name: string`	Name of the leave account (e.g. “Vacations”, “Sickness” …)
N/A	`isActive`	Whether the leave was deleted. A deleted leave used to completely disappear in v2, but it can still be retrieved in v3.
`leaveScope: string = ‘AM’ \| ‘PM’`	`isAM: boolean`	Whether the leave belong to the morning or the afternoon.

* : Fields related to the leave owner are no longer available in v3 in order to prevent data leaks. You may retrieve them with a complementary request to /api/v3/users.

Note: other fields did not change.

About Leave ID

V2 ABNF Syntax for Leave ID

leave-id = owner-id "-" date-time "-" meridiem

; Owner identifier (adjust as needed)
owner-id = 1*(ALPHA / DIGIT / "_" / "-")

; Date and time: dd/MM/yyyy hh:mm:ss
date-time = day "/" month "/" year SP hour ":" minute ":" second

day    = 2DIGIT  ; 01–31 (range not enforced in ABNF)
month  = 2DIGIT  ; 01–12
year   = 4DIGIT

hour   = 2DIGIT  ; 01–12
minute = 2DIGIT  ; 00–59
second = 2DIGIT  ; 00–59

meridiem = "AM" / "PM"

SP = %x20

; Example: 416-05/09/2025 11:42:30-AM

V3 ABNF Syntax for Leave ID

leave-id = leave-period-id "-" date "-" meridiem

; Leave period identifier (adjust as needed)
leave-period-id = 1*(ALPHA / DIGIT / "_" / "-")

; Date in YYYYMMDD format
date  = year month day

year  = 4DIGIT
month = 2DIGIT  ; 01–12 (range not enforced)
day   = 2DIGIT  ; 01–31 (range not enforced)

meridiem = "AM" / "PM"

; Example: 416-20250905-AM

About Leave Status

V2 Leave Status Enum

enum EV2Status {
  // Leave request was submitted but still has not been touched by a manager.
  NonValidated = 0,
  // The request has been partially approved by management.
  SemiValidated = 1, 
  // The request was approved by all required managers.
  Validated = 2, 
  // The request was rejected by a manager.
  Rejected = 3, 
  // The request was cancelled by the requesting employee themselves.
  Cancelled = 4, 
}

V3 Leave Status Enum

enum EV3Status {
  // The leave request has been submitted but is not approved
  // (can still be partially approved).
  Temporary = 0,
  // The leave request is formally approved.
  Confirmed = 1,
}

Code Examples

JSON Examples

{
  "header": {
    "generated": "2025-12-09T14:20:38.7951403+01:00",
    "serverTime": 17716,
    "queryTime": 17642,
    "processId": 1336
  },
  "data": [
    {
      "id": "3464-11/07/2025 00:00:00-AM",
      "name": "Télétravail",
      "owner": {
        "id": 3464,
        "name": "Daniel HERNANDEZ"
      },
      "date": "2025-07-11T00:00:00",
      "duration": 720,
      "status": 1
    },
    {
      "id": "3464-11/07/2025 12:00:00-PM",
      "name": "RTT 2025",
      "owner": {
        "id": 3464,
        "name": "Daniel HERNANDEZ"
      },
      "date": "2025-07-11T12:00:00",
      "duration": 720,
      "status": 1
    }
  ]
}

{
  "header": {
    "generated": "2025-12-09T14:19:57.0907857",
    "principal": "Lucca Admin",
    "processId": 2492
  },
  "data": {
    "items": [
      {
        "id": "217979-20250711-AM",
        "leavePeriod": {
          "owner": {
            "name": "Daniel HERNANDEZ",
            "id": 3464
          }
        },
        "name": "217979-20250711-AM",
        "date": "2025-07-11T00:00:00",
        "status": 1,
        "duration": "12:00:00"
      },
      {
        "id": "215197-20250711-PM",
        "leavePeriod": {
          "owner": {
            "name": "Daniel HERNANDEZ",
            "id": 3464
          }
        },
        "name": "215197-20250711-PM",
        "date": "2025-07-11T00:00:00",
        "status": 1,
        "duration": "12:00:00"
      }
    ]
  },
  "metadata": null

Example Mapper

enum EV2Status {
  NonValidated = 0,
  SemiValidated = 1,
  Validated = 2,
  Rejected = 3,
  Cancelled = 4,
}

enum EV3Status {
  Temporary = 0,
  Confirmed = 1,
}

interface IV2Leave {
    id: string;
    date: string;
    owner: {
      id: number;
      name: string;
      mail: string | null;
      login: string | null;
      matricule: string | null;
    };
    name: string;
    status: EV2Status;
    duration: number;
    accountCode: string;
    accountLabel: string;
    leaveScope: 'am' | 'pm';
}

interface IV3Leave {
    id: string;
    date: string;
    leavePeriod: {
        owner: {
            id: number;
            name: string;
        },
    };
    status: EV3Status;
    isActive: boolean;
    leaveAccount: {
        id: number;
        name: string;
    };
    duration: string;
    isAm: boolean;
}

function minutesSinceMidnight(timeStr: string) {
  const [hours, minutes, seconds = 0] = timeStr.split(':').map(Number);

  return hours * 60 + minutes + seconds / 60;
}


function v3ToV2Leave(v3leave: IV3Leave): IV2Leave {
  function v3ToV2Status(v3leave: IV3Leave): EV2Status {
    if (!v3leave.isActive) return EV2Status.Rejected
    if (v3leave.status === EV3Status.Temporary) {
      return EV2Status.NonValidated;
    } else {
      return EV2Status.Validated;
    }
  }
  function v3ToV2Id(v3leave: IV3Leave): string {
    const match = v3leave.id.match(/^(.+)-(\d{4})(\d{2})(\d{2})-(AM|PM)$/);

    if (!match) {
      throw new Error("Invalid leave ID format");
    }

    const [, leavePeriodId, year, month, day, meridiem] = match;

    const time = meridiem === "AM" ? "00:00:00" : "12:00:00";

    return `${v3leave.leavePeriod.ownerId}-${day}/${month}/${year} ${time}-${meridiem}`;
  }

  return {
    id: v3ToV2Id(v3leave),
    date: v3leave.date,
    owner: {
      id: v3leave.leavePeriod.owner.id,
      name: v3leave.leavePeriod.owner.name,
      mail: null, // No longer available for security reasons, you may fetch the user with GET /api/v3/users/{id}?fields=mail.
      login: null, // No longer available for security reasons, you may fetch the user with GET /api/v3/users/{id}?fields=login.
      matricule: null, // No longer available for security reasons, you may fetch the user with GET /api/v3/users/{id}?fields=employeeNumber.
    },
    name: v3leave.leaveAccount.name,
    status: v3ToV2Status(v3leave),
    duration: minutesSinceMidnight(v3leave.duration),
    accountCode: v3leave.leaveAccount.id.toString(),
    accountLabel: v3leave.leaveAccount.name,
    leaveScope: v3leave.isAm ? 'am' : 'pm',
  }
}

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

Migrate from leaves v2

Introduction

Changes

Routes

Query parameters

Response

Fields

About Leave ID

About Leave Status

Code Examples

JSON Examples

Example Mapper

​Introduction

​Changes

​Routes

​Query parameters

​Response

​Fields

​About Leave ID

​About Leave Status

​Code Examples

​JSON Examples

​Example Mapper

Introduction

Changes

Routes

Query parameters

Response

Fields

About Leave ID

About Leave Status

Code Examples

JSON Examples

Example Mapper