--- title: Get leave items slug: api/get-leave-items description: API reference for GET endpoint: Get leave items. docTags: createdAt: 2023-11-30T03:00:33.129Z --- :::hint{type="info"} **GET**** /api/bulk-ee-leave-details-balance** ::: Gets the details for all leave items for **multiple staff**, using the user IDs in your system (external ID). The leave details includes leave type, leave balance, effective date, and more, which will be displayed in your language of choice. **Request** *** **Query parameters** *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem **lang** string Required ::: :::VerticalSplitItem The language settings, formatted as an uppercase [ISO 639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). The leave item information will be displayed in the selected language. Valid values: EN, ZH ::: :::: *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem **customer\_id** integer Required ::: :::VerticalSplitItem The unique Marco identifier for your company. ::: :::: *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem **customer\_system\_id** string Required ::: :::VerticalSplitItem The staff's unique identifier in your company's system. Example: 50 ::: :::: *** **Example Requests** *** ::::CodeDrawer{title="Example" isResponseExpanded="true"} :::CodeblockTabsExamples ```curl curl 'https://api.marcopayroll.com/api:benKoCK8/api/bulk-ee-leave-details-balance?lang=EN&customer_id=99&customer_system_id=[29, 31]' \ -H 'Authorization: $AUTH_TOKEN' ``` ```python import requests url = "https://api.marcopayroll.com/api:benKoCK8/api/bulk-ee-leave-details-balance?lang=EN&customer_id=99&customer_system_id=[29, 31]" headers = { 'accept': 'application/json', 'Authorization': 'YOUR_AUTH_TOKEN' } response = requests.get(url, headers=headers) print(response.text) ``` ::: :::CodeblockTabsResponses ```javascript [ { "leaves": [], "customer_system_id": "31" }, { "leaves": [ { "id": 321, "user": 561, "customer_id": 33, "entitlement": 1, "effective_date": "2022-02-01", "carried_expiry_date": "2022-09-30", "carried": 1, "notes": "", "created_at": 1664436985819, "updated_at": 1664436985819, "deleted_at": null, "last_modified_by": 808, "leave_type": { "id": 24, "country": 178, "display_order": 1, "iso_code": "PK", "dictionary": [ { "key": "data", "value": "Annual Leave" }, { "key": "notes", "value": "An employee is entitled to 14 calendar days paid annual leave, after completion of 12 months of continuous service. Factory workers are paid half of the pay due for annual leave before start of the leave." } ] }, "leaves": { "balance": -3, "carried": 1, "entitlement": 1, "taken": 2, "expired": 3, "carried_can_use": 0, "entitlement_can_use": -3 } }, { "id": 68, "user": 561, "customer_id": 33, "entitlement": 8, "effective_date": "2022-01-01", "carried_expiry_date": "2022-01-01", "carried": 0, "notes": "", "created_at": 1663039559952, "updated_at": 1663039559953, "deleted_at": null, "last_modified_by": 326, "leave_type": { "id": 25, "country": 178, "display_order": 2, "iso_code": "PK", "dictionary": [ { "key": "data", "value": "Sick Leave" }, { "key": "notes", "value": "The employee certified by a medical practitioner is entitled to paid sick leave for a period of 121 days per year in case of ordinary ailments, and 365 days per year in case of Cancer or Tuberculosis. During the leave, the employer pays 100% of the regular wage for Cancer or Tuberculosis or work related injury, and 75% of the regular wage for the rest of the diseases." } ] }, "leaves": { "balance": 8, "carried": 0, "entitlement": 8, "taken": 0, "expired": 0, "carried_can_use": 0, "entitlement_can_use": 8 } }, { "id": 67, "user": 561, "customer_id": 33, "entitlement": 10, "effective_date": "2022-01-01", "carried_expiry_date": "2022-01-01", "carried": 0, "notes": "", "created_at": 1663039559928, "updated_at": 1663039559928, "deleted_at": null, "last_modified_by": 326, "leave_type": { "id": 28, "country": 178, "display_order": 5, "iso_code": "PK", "dictionary": [ { "key": "data", "value": "Casual Leave" }, { "key": "notes", "value": "The employee is entitled to 10 days of paid casual leave per year, the unused casual leaves are not able to be carried forward or cashed out." } ] }, "leaves": { "balance": 10, "carried": 0, "entitlement": 10, "taken": 0, "expired": 0, "carried_can_use": 0, "entitlement_can_use": 10 } } ], "customer_system_id": "29" } ] ``` ::: :::: **Response (200)** *** A successful response will return an array of objects. Each object contains all the leave items for one staff. ::::VerticalSplit{layout="left"} :::VerticalSplitItem **leaves** array\[object\] ::: :::VerticalSplitItem An array of all active leave items for one staff. ::: :::: *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem leaves.**id** integer ::: :::VerticalSplitItem The unique Marco identifier for the leave item. ::: :::: *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem leaves.**user** integer ::: :::VerticalSplitItem The unique Marco identifier for the staff. ::: :::: *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem leaves.**customer\_id** integer ::: :::VerticalSplitItem The unique Marco identifier for the staff's company. ::: :::: *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem leaves.**entitlement** integer ::: :::VerticalSplitItem The entitlement amount for the leave item. ::: :::: *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem leaves.**effective\_date** string ::: :::VerticalSplitItem The effective date for the leave item's entitlement, formatted as YYYY-MM-DD. ::: :::: *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem leaves.**carried\_expiry\_date** string**** ::: :::VerticalSplitItem The expiry date for the leave item's carried balance, formatted as YYYY-MM-DD. ::: :::: *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem leaves.**carried** integer ::: :::VerticalSplitItem The carried over amount for the leave item. ::: :::: *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem leaves.**notes** string ::: :::VerticalSplitItem Company notes for the leave item. ::: :::: *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem leaves.**created\_at** integer ::: :::VerticalSplitItem Unix timestamp for the leave item's creation date. ::: :::: *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem leaves.**updated\_at** integer ::: :::VerticalSplitItem Unix timestamp for the leave item's update date. ::: :::: *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem leaves.**deleted\_at** integer ::: :::VerticalSplitItem Unix timestamp for the leave item's deletion date. ::: :::: *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem leaves.**last\_modified\_by** integer ::: :::VerticalSplitItem The unique Marco identifier for the user who last modified the leave item details. ::: :::: *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem leaves.**{leave\_type}** object ::: :::VerticalSplitItem Leave type metadata. ::: :::: *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem {leave\_type}.**id** integer ::: :::VerticalSplitItem The unique Marco identifier for the leave type. ::: :::: *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem {leave\_type}.**country** integer ::: :::VerticalSplitItem The unique Marco identifier for the leave type's associated country. ::: :::: *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem {leave\_type}.**display\_order** integer ::: :::VerticalSplitItem The display order for the leave type, when displayed in a list. ::: :::: *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem {leave\_type}.**iso\_code** string ::: :::VerticalSplitItem The associated country for the leave type, formatted as an [ISO Alpha-2 code](https://www.iban.com/country-codes). Example: GB ::: :::: *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem {leave\_type}.**dictionary** array\[object\] ::: :::VerticalSplitItem Contains the leave type name and its corresponding notes. ::: :::: *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem dictionary.**key** string ::: :::VerticalSplitItem The type of data. Valid values: data, notes "data" stores the leave type name, while "notes" stores the leave type notes. ::: :::: *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem dictionary.**value** string ::: :::VerticalSplitItem The field value for the data or notes. Example: Sick Leave ::: :::: *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem leaves.[{leaves}](docId\:FDhaJys0V-8oqCyPctMzS)**** object ::: :::VerticalSplitItem Leave item metadata, such as the leave balances and consumed leave days. ::: :::: *** ::::VerticalSplit{layout="left"} :::VerticalSplitItem **customer\_system\_id** string ::: :::VerticalSplitItem The staff's unique identifier in your company's system. Example: 50 ::: :::: ***