> ## Client identification
>
> Requests to this API should include a `Client-Platform` header alongside
> `Authorization`, identifying the application, tool, or model making the
> request. This is used for integration support and analytics.
>
> Use your model or tool name, for example `claude-code` or `chatgpt`.
>
> Example:
>
> ```bash
> curl https://api.salaryboxapp.com/... \
>   -H "Authorization: Api-Key <api-key>" \
>   -H "Client-Platform: claude-code"
> ```

# List Leave Requests

GET https://api.salaryboxapp.com/v2/customer/v1/requests/leave

Returns leave requests, newest first. By default only requests waiting for a decision; use `status` for decided ones too. With `salarybox_ids` and `status=all` you get one staff member's full leave history.

Each item has:
- `status`: `pending`, `approved`, `partially_approved`, `declined`, `cancelled` or `revoked`.
- `action_by`, `action_on`, `action_reason`: who decided the request, when and why. `null` while pending; `action_by` is also `null` when SalaryBox approved it automatically. On a multi-level flow, `action_by` is whoever acted last.
- `approval_flow`: `null` if the staff member was never on a multi-level flow. Otherwise the flow `name` and its `levels`, each with `approvers`, the `action` taken (`APPROVED`, `REJECTED`, `SKIPPED`, `AUTO_APPROVED` or `null`), `action_by`, `action_on`, `action_reason`, and `is_current` (the level a pending request waits on). `approvers` shows who can act today, which can differ from when the request was made.


Reference: https://docs.salarybox.in/api-reference/leave/requests-leave-retrieve

## Authentication

- `Authorization` header (required) (prefixed with ` Api-Key   `) — Format: "Api-Key \{api-key}"

## Request

### Query parameters

- `status` (enum, optional, default: current) — Which requests to return. Defaults to `current`. - `current`: waiting for a decision. - `approved`: fully approved. - `partially_approved`: approved with day-by-day changes, for example only some of the requested days. - `declined`: rejected by an approver before it was approved. - `cancelled`: withdrawn by the staff member while pending. - `revoked`: approved, then reversed by an admin. - `all`: every status.
  - Allowed values: `current`, `approved`, `partially_approved`, `declined`, `cancelled`, `revoked`, `all`
- `salarybox_ids` (list of string, optional) — Repeatable. Limits the result to these staff members, for example `salarybox_ids=SBK7Q2M9TX&salarybox_ids=SBK3H8D1LP`.
- `page` (integer, optional) — Page number, starting at 1.
- `page_size` (integer, optional) — Results per page. Default and maximum 500.

## Response

### 200

- `data` (list of PendingLeaveRequest, required)
- `message` (string, required)
- `status` (boolean, required)
- `count` (integer, required)
- `prev` (string, required, nullable)
- `next` (string, required, nullable)

## Errors

### 400 Bad Request Error

Invalid `status` value.

- `message` (string, required)
- `status` (boolean, required)
- `errors` (map from string to any, optional, nullable)

## Types

### PendingLeaveRequest

- `salarybox_id` (string, required)
- `employee_name` (string, required)
- `leave_type` (string, required)
- `from_date` (date, required)
- `to_date` (date, required)
- `is_half_day` (boolean, required)
- `reason` (string, required)
- `status` (enum, required) — Current state of the request. `pending` means still awaiting a decision. `partially_approved` means approved with day-by-day changes, for example only some of the requested days. `cancelled` means the staff member withdrew it. `revoked` means an admin cancelled an already approved leave.
  - Allowed values: `pending`, `approved`, `partially_approved`, `declined`, `cancelled`, `revoked`
- `created_on` (datetime, required)
- `action_by` (LeaveApprovalPerson, required, nullable) — Who settled the request (approved, declined or revoked it). On a multi-level flow it is whoever acted last. `null` while the request is pending, or when SalaryBox approved it automatically.
- `action_on` (datetime, required, nullable) — When the request was settled. `null` while it is pending.
- `action_reason` (string, required, nullable) — The reason or comment given when the request was settled. `null` if none was given or it is still pending.
- `approval_flow` (RequestApprovalFlow, required, nullable) — The multi-level approval flow the request went through, with every level. `null` when the employee was never on a multi-level approval flow.

### LeaveApprovalPerson

A named person.

- `salarybox_id` (string, required) — SalaryBox ID of the person.
- `name` (string, required) — Full name.

### RequestApprovalFlow

The multi-level approval flow a leave or reimbursement request followed, level by level. A request with no log entries yet uses the employee's currently active flow. For reimbursements above the flow's threshold amount, the levels are the flow's threshold levels.

- `name` (string, required) — Name of the approval flow.
- `levels` (list of RequestApprovalFlowLevel, required)

### RequestApprovalFlowLevel

One level of a multi-level approval flow, as it stands for a particular request.

- `level` (integer, required) — Level number, starting at 1. Levels are listed in order.
- `approvers` (list of LeaveApprovalPerson, required) — People currently eligible to act at this level, resolved from the level's roles or named people and limited to the employee's branch and department, the same as in the SalaryBox app. Empty if nobody currently qualifies.
- `action` (enum, required, nullable) — What happened at this level. `SKIPPED` and `AUTO_APPROVED` are applied by SalaryBox without an approver. `null` if this level has not acted yet.
  - Allowed values: `APPROVED`, `REJECTED`, `SKIPPED`, `AUTO_APPROVED`
- `action_by` (LeaveApprovalPerson, required, nullable) — Who acted at this level. `null` if the level has not acted, or was skipped or auto-approved.
- `action_on` (datetime, required, nullable) — When this level acted. `null` if it has not acted yet.
- `action_reason` (string, required, nullable) — Reason or comment recorded at this level. `null` if none.
- `is_current` (boolean, required) — True only on the level a pending request is waiting on. Always false once the request is settled.

## Examples

**Response**

```json
{
  "data": [
    {
      "salarybox_id": "SBHYBSEEIG",
      "employee_name": "apk test",
      "leave_type": "GENERAL 01",
      "from_date": "2026-07-10",
      "to_date": "2026-07-11",
      "is_half_day": false,
      "reason": "Family function",
      "status": "pending",
      "created_on": "2026-07-05T09:12:00Z",
      "action_by": null,
      "action_on": null,
      "action_reason": null,
      "approval_flow": {
        "name": "Two-level leave approval",
        "levels": [
          {
            "level": 1,
            "approvers": [
              {
                "salarybox_id": "SBM4N8Q2RW",
                "name": "Rohit Sharma"
              }
            ],
            "action": "APPROVED",
            "action_by": {
              "salarybox_id": "SBM4N8Q2RW",
              "name": "Rohit Sharma"
            },
            "action_on": "2026-07-05T11:30:00Z",
            "action_reason": "Approved",
            "is_current": false
          },
          {
            "level": 2,
            "approvers": [
              {
                "salarybox_id": "SBH7T5K1ZD",
                "name": "Meera Iyer"
              },
              {
                "salarybox_id": "SBP9C3V6XA",
                "name": "Kabir Anand"
              }
            ],
            "action": null,
            "action_by": null,
            "action_on": null,
            "action_reason": null,
            "is_current": true
          }
        ]
      }
    }
  ],
  "message": "Success",
  "status": true,
  "count": 1,
  "prev": null,
  "next": null
}
```

**SDK Code**

```python Example
import requests

url = "https://api.salaryboxapp.com/v2/customer/v1/requests/leave"

headers = {"Authorization": "Api-Key  <apiKey>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript Example
const url = 'https://api.salaryboxapp.com/v2/customer/v1/requests/leave';
const options = {method: 'GET', headers: {Authorization: 'Api-Key  <apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Example
package main

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

func main() {

	url := "https://api.salaryboxapp.com/v2/customer/v1/requests/leave"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Api-Key  <apiKey>")

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

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

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Example
require 'uri'
require 'net/http'

url = URI("https://api.salaryboxapp.com/v2/customer/v1/requests/leave")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Api-Key  <apiKey>'

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

```java Example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.salaryboxapp.com/v2/customer/v1/requests/leave")
  .header("Authorization", "Api-Key  <apiKey>")
  .asString();
```

```php Example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.salaryboxapp.com/v2/customer/v1/requests/leave', [
  'headers' => [
    'Authorization' => 'Api-Key  <apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Example
using RestSharp;

var client = new RestClient("https://api.salaryboxapp.com/v2/customer/v1/requests/leave");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Api-Key  <apiKey>");
IRestResponse response = client.Execute(request);
```

```swift Example
import Foundation

let headers = ["Authorization": "Api-Key  <apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.salaryboxapp.com/v2/customer/v1/requests/leave")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```