> This page is for API, version 2026-01-01 (Stable) (default).
> For other versions, use one of these documentation indexes:
> - 2026-01-01 (Stable) (default): https://developer.deel.com/api/stable/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.deel.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.deel.com/_mcp/server.

# List equity grant total expense records

GET https://api.letsdeel.com/rest/equity-expenses

Retrieves the total share-based compensation expense recognised per equity grant in an organization, as ingested from Shareworks. Use it at period close to tie the equity expense in the ledger back to the individual grants that produced it. Each record reflects the most recently ingested reporting period; earlier periods are overwritten, so this is not a period history. Requires the `equities.view` permission at the organization level.

 **Token scopes**: `equities:read`

Reference: https://developer.deel.com/api/reference/endpoints/equity-tokens/list-equity-expenses-v-2026-09-09

## Authentication

- `Authorization` header (bearer token, required) — ## Authentication The Deel API uses bearer tokens to authenticate requests. All API calls must be made over HTTPS — calls over plain HTTP or without authentication will fail. ```curl curl -X GET 'https://api.letsdeel.com/rest/v2/contracts' \ -H 'Authorization: Bearer YOUR-TOKEN-HERE' ``` [Learn more about authentication](/api/authentication)
- `Authorization` header (bearer token, required) — Standard OAuth2 security scheme based on https://swagger.io/docs/specification/authentication/

## Servers

- `https://api.letsdeel.com/rest` (Production, default)
- `https://api-staging.letsdeel.com/rest` (Demo)

## Request

### Query parameters

- `limit` (integer, optional, default: 50) — Maximum number of records to return in this page.
- `cursor` (string, optional) — Opaque pagination cursor returned as next_cursor by a previous response. Omit to fetch the first page.
- `employee_number` (string, optional) — Only return records for this exact Shareworks employee number.
- `employee_grant_number` (string, optional) — Only return records for this exact Shareworks grant number.
- `grant_date_from` (string, optional) — Only return records with a grant_date on or after this date (inclusive), in YYYY-MM-DD format.
- `grant_date_to` (string, optional) — Only return records with a grant_date on or before this date (inclusive), in YYYY-MM-DD format.

## Response

### 200

List equity grant total expense records returned successfully.

- `data` (list of EquityExpensesGetResponsesContentApplicationJsonSchemaDataItems, required) — Page of total expense records, one per grant occurrence.
- `has_more` (boolean, required) — Whether another page of results is available.
- `next_cursor` (string, required, nullable) — Cursor for the next page. Null when has_more is false.

## Errors

### 400 Bad Request Error

Bad request — invalid or missing parameters.

- `errors` (list of EquityExpensesGetResponsesContentApplicationJsonSchemaErrorsItems, required) — List of errors that occurred while processing the request.

### 401 Unauthorized Error

Unauthorized — missing or invalid authentication token.

- `errors` (list of EquityExpensesGetResponsesContentApplicationJsonSchemaErrorsItems, required) — List of errors that occurred while processing the request.

### 403 Forbidden Error

Forbidden — caller lacks the equities.view permission, or the caller's organization is not permitted to access this endpoint.

- `errors` (list of EquityExpensesGetResponsesContentApplicationJsonSchemaErrorsItems, required) — List of errors that occurred while processing the request.

### 404 Not Found Error

Not found — the requested resource does not exist.

- `errors` (list of EquityExpensesGetResponsesContentApplicationJsonSchemaErrorsItems, required) — List of errors that occurred while processing the request.

### 500 Internal Server Error

Internal server error.

- `errors` (list of EquityExpensesGetResponsesContentApplicationJsonSchemaErrorsItems, required) — List of errors that occurred while processing the request.

## Types

### EquityExpensesGetResponsesContentApplicationJsonSchemaDataItems

- `id` (string, required) — The unique identifier of the record.
- `row_hash` (string, required) — Hash of the reported values on this record. Compare it between syncs to detect a change without diffing every field.
- `plan_name` (string, required) — Equity plan name, as reported by the ingested file.
- `award_type` (string, required) — Award type (e.g. Restricted Stock - Standard), as reported by the ingested file.
- `created_at` (string, required) — Timestamp this record was first ingested.
- `grant_date` (string, required) — Date the grant was issued, as reported by the ingested file.
- `grant_name` (string, required) — Grant name, as reported by the ingested file.
- `updated_at` (string, required) — Timestamp this record was last upserted, for incremental sync.
- `base_shares` (double, required) — Base share count for this grant, as reported by the ingested file.
- `grant_price` (double, required, nullable) — Strike/grant price per unit, as reported by the ingested file.
- `base_expense` (double, required, nullable) — Base expense amount, as reported by the ingested file.
- `factor_shares` (double, required, nullable) — Shares resulting from the performance factor, as reported by the ingested file.
- `source_file_id` (string, required) — Identifier of the ingested Shareworks report file this record was last upserted from.
- `employee_number` (string, required) — Shareworks employee number, as reported by the ingested file. The intended join key for this record. Some values are non-numeric for legacy or masked records.
- `hris_profile_id` (integer, required, nullable) — Matched HRIS profile id, if employee_number could be resolved to one. Null when unmatched, or when employee_number is non-numeric or blank.
- `occurrence_index` (integer, required) — Discriminates several records the source file reports for the same natural key. Starts at 1, in the order the rows appear in the file.
- `valuation_status` (string, required, nullable) — Valuation status (e.g. Approved, Do Not Expense), as reported by the ingested file.
- `actual_forfeitures` (double, required) — Actual forfeited share count, as reported by the ingested file.
- `fair_value_per_share` (double, required, nullable) — Fair market value per share, as reported by the ingested file.
- `last_seen_dataset_id` (string, required, nullable) — Identifier of the most recent ingested dataset in which this record still appeared. Null for records ingested before dataset tracking began.
- `unvested_repurchased` (double, required, nullable) — Unvested shares repurchased, as reported by the ingested file.
- `employee_grant_number` (string, required) — Shareworks grant number for this employee, as reported by the ingested file.
- `estimated_forfeitures` (double, required, nullable) — Estimated forfeited share count, as reported by the ingested file.
- `forfeiture_rate_percent` (double, required, nullable) — Forfeiture rate, stored as the percent NUMBER itself (e.g. 44.336788 means 44.336788%), NOT a fraction. See parseShareworksPercent.
- `total_estimated_expense` (double, required, nullable) — Total estimated expense, as reported by the ingested file.
- `actual_performance_factor` (double, required, nullable) — Actual performance factor applied, as reported by the ingested file.
- `estimated_performance_factor` (double, required, nullable) — Estimated performance factor, as reported by the ingested file.
- `total_actual_expense_to_accrue` (double, required, nullable) — Total actual expense to accrue, as reported by the ingested file.
- `total_actual_shares_to_expense` (double, required) — Total actual shares to expense, as reported by the ingested file.
- `total_estimated_shares_to_expense` (double, required, nullable) — Total estimated shares to expense, as reported by the ingested file.

### EquityExpensesGetResponsesContentApplicationJsonSchemaErrorsItems

- `message` (string, required) — Human-readable explanation
- `code` (string, optional) — Machine-readable error code
- `field` (string, optional, nullable) — Field that caused the error, if applicable.

## Examples

**Response**

```json
{
  "data": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "row_hash": "9f2c1a7e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a6c8e0b2d4f6a8c0e2b4d6f8a",
      "plan_name": "2020 Stock Plan",
      "award_type": "Options (NQ)",
      "created_at": "2026-08-13T09:01:02.000Z",
      "grant_date": "2022-06-18",
      "grant_name": "06/18/2022 - NQSO - $4.7",
      "updated_at": "2026-08-13T09:01:02.000Z",
      "base_shares": 1000,
      "grant_price": 4.7,
      "base_expense": 4700,
      "factor_shares": 5.5,
      "source_file_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "employee_number": "9001",
      "hris_profile_id": 4821,
      "occurrence_index": 1,
      "valuation_status": "Active",
      "actual_forfeitures": 1000,
      "fair_value_per_share": 4.7,
      "last_seen_dataset_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "unvested_repurchased": 1000,
      "employee_grant_number": "ES-0001",
      "estimated_forfeitures": 1000,
      "forfeiture_rate_percent": 5.5,
      "total_estimated_expense": 4700,
      "actual_performance_factor": 5.5,
      "estimated_performance_factor": 5.5,
      "total_actual_expense_to_accrue": 4700,
      "total_actual_shares_to_expense": 4700,
      "total_estimated_shares_to_expense": 4700
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzb3J0VmFsdWUiOiI5MDAxIiwiaWQiOiJhMWIyYzNkNC1lNWY2LTc4OTAtYWJjZC1lZjEyMzQ1Njc4OTAifQ=="
}
```

**SDK Code**

```python
import requests

url = "https://api.letsdeel.com/rest/equity-expenses"

querystring = {"cursor":"eyJzb3J0VmFsdWUiOiI5MDAxIiwiaWQiOiJhMWIyYzNkNC1lNWY2LTc4OTAtYWJjZC1lZjEyMzQ1Njc4OTAifQ==","employee_grant_number":"ES-0001","employee_number":"9001","grant_date_from":"2026-01-01","grant_date_to":"2026-12-31","limit":"50"}

headers = {"Authorization": "Bearer <token>"}

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

print(response.json())
```

```javascript
const url = 'https://api.letsdeel.com/rest/equity-expenses?cursor=eyJzb3J0VmFsdWUiOiI5MDAxIiwiaWQiOiJhMWIyYzNkNC1lNWY2LTc4OTAtYWJjZC1lZjEyMzQ1Njc4OTAifQ%3D%3D&employee_grant_number=ES-0001&employee_number=9001&grant_date_from=2026-01-01&grant_date_to=2026-12-31&limit=50';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

```go
package main

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

func main() {

	url := "https://api.letsdeel.com/rest/equity-expenses?cursor=eyJzb3J0VmFsdWUiOiI5MDAxIiwiaWQiOiJhMWIyYzNkNC1lNWY2LTc4OTAtYWJjZC1lZjEyMzQ1Njc4OTAifQ%3D%3D&employee_grant_number=ES-0001&employee_number=9001&grant_date_from=2026-01-01&grant_date_to=2026-12-31&limit=50"

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

	req.Header.Add("Authorization", "Bearer <token>")

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

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

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

}
```

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

url = URI("https://api.letsdeel.com/rest/equity-expenses?cursor=eyJzb3J0VmFsdWUiOiI5MDAxIiwiaWQiOiJhMWIyYzNkNC1lNWY2LTc4OTAtYWJjZC1lZjEyMzQ1Njc4OTAifQ%3D%3D&employee_grant_number=ES-0001&employee_number=9001&grant_date_from=2026-01-01&grant_date_to=2026-12-31&limit=50")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

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

HttpResponse<String> response = Unirest.get("https://api.letsdeel.com/rest/equity-expenses?cursor=eyJzb3J0VmFsdWUiOiI5MDAxIiwiaWQiOiJhMWIyYzNkNC1lNWY2LTc4OTAtYWJjZC1lZjEyMzQ1Njc4OTAifQ%3D%3D&employee_grant_number=ES-0001&employee_number=9001&grant_date_from=2026-01-01&grant_date_to=2026-12-31&limit=50")
  .header("Authorization", "Bearer <token>")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.letsdeel.com/rest/equity-expenses?cursor=eyJzb3J0VmFsdWUiOiI5MDAxIiwiaWQiOiJhMWIyYzNkNC1lNWY2LTc4OTAtYWJjZC1lZjEyMzQ1Njc4OTAifQ%3D%3D&employee_grant_number=ES-0001&employee_number=9001&grant_date_from=2026-01-01&grant_date_to=2026-12-31&limit=50', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api.letsdeel.com/rest/equity-expenses?cursor=eyJzb3J0VmFsdWUiOiI5MDAxIiwiaWQiOiJhMWIyYzNkNC1lNWY2LTc4OTAtYWJjZC1lZjEyMzQ1Njc4OTAifQ%3D%3D&employee_grant_number=ES-0001&employee_number=9001&grant_date_from=2026-01-01&grant_date_to=2026-12-31&limit=50");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.letsdeel.com/rest/equity-expenses?cursor=eyJzb3J0VmFsdWUiOiI5MDAxIiwiaWQiOiJhMWIyYzNkNC1lNWY2LTc4OTAtYWJjZC1lZjEyMzQ1Njc4OTAifQ%3D%3D&employee_grant_number=ES-0001&employee_number=9001&grant_date_from=2026-01-01&grant_date_to=2026-12-31&limit=50")! 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()
```