> 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://docs.deel.wtf/api/stable/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.deel.wtf/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.deel.wtf/_mcp/server. # List equity grants with tax events GET https://api.letsdeel.com/rest/equity-grants Use this endpoint to sync an organization's equity grants into an external captable, payroll, or reporting system. Each grant includes its vesting events and any tax events recorded against it. Requires the `equities.view` permission at the organization level. **Token scopes**: `equities:read` Reference: https://docs.deel.wtf/api/reference/endpoints/equity-tokens/list-equity-grants-with-tax-events-v-2026-07-31 ## 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.deel.training/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: 100) — Maximum number of grants to return - `offset` (integer, optional, default: 0) — Number of grants to skip before starting to return results - `search` (string, optional) — Free-text search across grant/worker name and email. Matching is case- and accent-insensitive ## Response ### 200 A paginated list of equity grants, each including its vesting events and associated tax events. - `data` (list of EquityGrantsGetResponsesContentApplicationJsonSchemaDataItems, optional) - `limit` (integer, optional) — The limit applied to this page of results - `total` (integer, optional) — The total number of grants matching the query, independent of limit/offset - `offset` (integer, optional) — The offset applied to this page of results ## Errors ### 400 Bad Request Error One or more query parameters are invalid. See the errors array for detail. - `errors` (list of EquityGrantsGetResponsesContentApplicationJsonSchemaErrorsItems, optional) ### 401 Unauthorized Error Operation failed. - `request` (ApiErrorRequest, optional) - `errors` (list of ApiError, optional) ### 403 Forbidden Error The token does not grant `equities.view` at the organization level. - `errors` (list of EquityGrantsGetResponsesContentApplicationJsonSchemaErrorsItems, optional) ### 404 Not Found Error Operation failed. - `request` (ApiErrorRequest, optional) - `errors` (list of ApiError, optional) ### 500 Internal Server Error An unexpected server error occurred while listing the grants. - `errors` (list of EquityGrantsGetResponsesContentApplicationJsonSchemaErrorsItems, optional) ## Types ### EquityGrantsGetResponsesContentApplicationJsonSchemaDataItems - `id` (string, optional) — The unique identifier of the equity grant - `value` (double, optional, nullable) — The total grant value at the time of issuance, in grant currency - `source` (string, optional, nullable) — The system of record the grant originated from - `quantity` (double, optional, nullable) — The total quantity granted - `tranches` (double, optional, nullable) — The number of vesting tranches - `grant_date` (string, optional, nullable) — The date the grant was issued - `grant_name` (string, optional, nullable) — The name of the grant - `tax_events` (list of EquityGrantsGetResponsesContentApplicationJsonSchemaDataItemsTaxEventsItems, optional) — The tax events reported against this grant - `cliff_period` (double, optional, nullable) — The cliff period in months before any shares vest - `grant_status` (string, optional, nullable) — The lifecycle status of the grant (e.g. GRANTED, PENDING_APPROVAL) - `hris_profile` (EquityGrantsGetResponsesContentApplicationJsonSchemaDataItemsHrisProfile, optional) — Profile information for the EOR worker who holds the grant - `reference_id` (double, optional, nullable) — The human-readable reference number of the grant - `vested_events` (list of EquityGrantsGetResponsesContentApplicationJsonSchemaDataItemsVestedEventsItems, optional) — The individual vesting events recorded for this grant - `exercise_price` (double, optional, nullable) — The per-unit price at which the option or warrant can be exercised, in exercise price currency - `grant_currency` (string, optional, nullable) — The currency of the grant value - `vesting_length` (double, optional, nullable) — The total vesting length in months - `vested_quantity` (double, optional, nullable) — The quantity vested so far - `fmv_when_granted` (double, optional, nullable) — The fair market value of the underlying instrument at grant time - `equity_grant_type` (string, optional, nullable) — The type of equity instrument granted - `option_expiration` (string, optional, nullable) — The date the option expires - `vesting_start_date` (string, optional, nullable) — The date vesting begins - `equity_grant_type_name` (string, optional, nullable) — The organization's custom label for the grant type - `exercise_price_currency` (string, optional, nullable) — The currency of the exercise price - `additional_grant_requirements_and_restrictions` (string, optional, nullable) — Free-text additional requirements or restrictions on the grant ### EquityGrantsGetResponsesContentApplicationJsonSchemaErrorsItems - `code` (string, optional) — A machine-readable code identifying the type of error - `message` (string, optional) — A human-readable description of the error ### ApiErrorRequest - `method` (string, optional) — The HTTP method of the failed request - `url` (string, optional) — The relative URL of the failed request - `status` (double, optional) — The status code of the response - `api_req_id` (string, optional) — The request ID of the failed request - `docs` (string, optional) — A link to the official documentation for the requested endpoint resource - `source` (string, optional) — The source handler which produced the returned error - `code` (double, optional) — The code of the source handler which produced the returned error ### ApiError - `message` (string, optional) — A description of the returned error - `path` (string, optional) — The JSON path where input validation failed ### EquityGrantsGetResponsesContentApplicationJsonSchemaDataItemsTaxEventsItems - `id` (string, optional) — The unique identifier of the tax event - `note` (string, optional, nullable) — A free-text note attached to the tax event - `email` (string, optional) — The worker's email address - `country` (string, optional, nullable) — The ISO 3166-1 alpha-2 country code of the worker's employment country - `fx_rate` (string, optional, nullable) — The exchange rate used to convert local currency to payroll currency - `pic_url` (string, optional, nullable) — URL of the worker's profile picture - `grant_id` (string, optional, nullable) — The unique identifier of the associated grant - `tax_rate` (string, optional, nullable) — The tax rate applied to the benefit in kind - `unit_fmv` (string, optional, nullable) — The fair market value per unit at the time of the event - `last_name` (string, optional, nullable) — The worker's last name - `created_at` (string, optional, nullable) — The date and time the tax event was created - `event_date` (string, optional, nullable) — The date of the tax event - `first_name` (string, optional, nullable) — The worker's first name - `grant_date` (string, optional, nullable) — The date the associated grant was issued - `grant_type` (string, optional, nullable) — The equity instrument type of the associated grant (e.g. RSU, NSO, ISO) - `sale_price` (string, optional, nullable) — The price at which the equity was sold - `updated_at` (string, optional, nullable) — The date and time the tax event was last updated - `archived_at` (string, optional, nullable) — The date and time the tax event was archived - `contract_id` (string, optional) — The unique identifier of the contract associated with the tax event - `external_id` (string, optional, nullable) — An external system identifier for the worker, such as an ID from a cap-table provider - `gross_value` (string, optional, nullable) — The gross value of the equity event, calculated as unit FMV multiplied by quantity exercised or released - `is_archived` (boolean, optional, nullable) — Whether the tax event has been archived - `middle_name` (string, optional, nullable) — The worker's middle name - `plan_currency` (string, optional, nullable) — The currency in which the equity plan was issued - `exercise_price` (string, optional, nullable) — The price at which the equity was exercised - `contract_status` (string, optional) — The lifecycle status of the associated worker contract (e.g. in_progress, completed, cancelled) - `hris_profile_id` (string, optional) — The unique identifier of the worker who holds the grant - `instrument_type` (string, optional, nullable) — The type of equity instrument (e.g. RSU, NSO, ISO, PHANTOM, SARS) - `organization_id` (string, optional) — The unique identifier of the organization - `settlement_date` (string, optional, nullable) — The date the equity event was settled (i.e. when shares were transferred or cash was received) - `created_by_email` (string, optional, nullable) — The email of the user who created the tax event - `payroll_currency` (string, optional, nullable) — The currency in which payroll is processed - `tax_jurisdiction` (string, optional, nullable) — The ISO 3166-1 alpha-2 country code of the worker's contract jurisdiction at the time of the event - `transaction_fees` (string, optional, nullable) — Brokerage or transaction fees associated with the equity event, in plan currency - `organization_name` (string, optional, nullable) — The name of the organization - `grant_reference_id` (double, optional, nullable) — The human-readable reference number of the associated grant - `quantity_remaining` (string, optional, nullable) — The quantity of equity remaining - `verification_status` (string, optional, nullable) — The current verification status of the tax event (PENDING_VERIFICATION, VERIFIED, SENT_FOR_PROCESSING, PROCESSED, MISMATCH) - `taxable_gain_or_loss` (string, optional, nullable) — The taxable gain or loss on the event, typically gross value minus the total exercise price - `total_exercise_price` (string, optional, nullable) — The total exercise price paid for the equity, calculated as exercise price per unit multiplied by quantity exercised - `total_taxes_withheld` (string, optional, nullable) — The total amount of income tax and social contributions withheld on behalf of the worker - `equity_service_status` (string, optional) — The equity service enrollment status for the worker (ONBOARDED, OFFBOARDED, NOT_ONBOARDED, NOT_ELIGIBLE, MORE_INFO_REQUIRED) - `method_of_tax_coverage` (string, optional, nullable) — How the benefit-in-kind (BIK) tax on this equity event is collected. BIK_WITHHOLDING_* values indicate the employer withholds tax from payroll; the suffix identifies the mechanism (e.g. at-source deduction, salary deduction, net settlement, grossed-up bonus). BIK_REPORTING_ONLY reports the BIK without withholding. NO_BIK_NO_WITHHOLDING applies when no taxable benefit arises. AD_HOC covers special cases outside the standard methods. - `sent_for_processing_at` (string, optional, nullable) — The date and time the event was sent for payroll processing - `actual_payroll_cycle_id` (string, optional, nullable) — The unique identifier of the actual payroll cycle - `supporting_documents_id` (string, optional, nullable) — The unique identifier of the supporting documents attached to the event - `actual_payroll_cycle_end` (string, optional, nullable) — The end date of the actual payroll cycle - `contract_completion_date` (string, optional, nullable) — The completion date of the associated contract - `expected_payroll_cycle_id` (string, optional, nullable) — The unique identifier of the expected payroll cycle - `quantity_withheld_or_sold` (string, optional, nullable) — The quantity of equity withheld or sold - `actual_payroll_cycle_start` (string, optional, nullable) — The start date of the actual payroll cycle - `expected_payroll_cycle_end` (string, optional, nullable) — The end date of the expected payroll cycle - `actual_payroll_cycle_cutoff` (string, optional, nullable) — The cutoff date of the actual payroll cycle - `withheld_tax_local_currency` (string, optional, nullable) — The income tax and social contributions withheld, expressed in the worker's local payroll currency - `expected_payroll_cycle_start` (string, optional, nullable) — The start date of the expected payroll cycle - `expected_payroll_cycle_cutoff` (string, optional, nullable) — The cutoff date of the expected payroll cycle - `benefit_in_kind_local_currency` (string, optional, nullable) — The benefit-in-kind (BIK) value reported to payroll, expressed in the worker's local payroll currency - `quantity_exercised_or_released` (string, optional, nullable) — The quantity of equity exercised or released ### EquityGrantsGetResponsesContentApplicationJsonSchemaDataItemsHrisProfile Profile information for the EOR worker who holds the grant - `id` (string, optional) — The unique identifier of the worker - `email` (string, optional) — The worker's email address - `pic_url` (string, optional, nullable) — URL of the worker's profile picture - `job_title` (string, optional, nullable) — The worker's job title - `last_name` (string, optional, nullable) — The worker's last name - `first_name` (string, optional, nullable) — The worker's first name - `hiring_type` (string, optional, nullable) — The worker's engagement type within Deel (e.g. employee, contractor) - `middle_name` (string, optional, nullable) — The worker's middle name ### EquityGrantsGetResponsesContentApplicationJsonSchemaDataItemsVestedEventsItems - `quantity` (double, optional, nullable) — The quantity that vested on this date - `vesting_date` (string, optional, nullable) — The date this tranche vested ## Examples **Response** ```json { "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "value": 50000, "source": "MANUAL", "quantity": 1000, "tranches": 4, "grant_date": "2025-01-15", "grant_name": "RSU Grant 2025", "tax_events": [ { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "note": "Reviewed by payroll team", "email": "jane.doe@example.com", "country": "US", "fx_rate": "0.95904862", "pic_url": "https://cdn.deel.com/avatars/jane-doe.png", "grant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "tax_rate": "0.25", "unit_fmv": "11", "last_name": "Doe", "created_at": "2024-04-02T10:00:00Z", "event_date": "2024-04-01", "first_name": "Jane", "grant_date": "2024-01-01", "grant_type": "RSU", "sale_price": "10", "updated_at": "2024-04-03T10:00:00Z", "archived_at": "2024-07-01T09:00:00Z", "contract_id": "meyv8ek", "external_id": "ext-12345", "gross_value": "100000", "is_archived": false, "middle_name": "Ann", "plan_currency": "USD", "exercise_price": "4.34", "contract_status": "in_progress", "hris_profile_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "instrument_type": "RSU", "organization_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "settlement_date": "2024-06-01", "created_by_email": "admin@example.com", "payroll_currency": "EUR", "tax_jurisdiction": "US", "transaction_fees": "25", "organization_name": "Acme Corp", "grant_reference_id": 1024, "quantity_remaining": "5000", "verification_status": "VERIFIED", "taxable_gain_or_loss": "15000", "total_exercise_price": "225000", "total_taxes_withheld": "1000", "equity_service_status": "ONBOARDED", "method_of_tax_coverage": "BIK_WITHHOLDING_AT_SOURCE_CLIENT", "sent_for_processing_at": "2024-06-05T10:00:00Z", "actual_payroll_cycle_id": "f6a7b8c9-d0e1-2345-f123-456789012345", "supporting_documents_id": "d4e5f6a7-b8c9-0123-def1-234567890123", "actual_payroll_cycle_end": "2024-06-30", "contract_completion_date": "2026-01-01T10:00:00Z", "expected_payroll_cycle_id": "e5f6a7b8-c9d0-1234-ef12-345678901234", "quantity_withheld_or_sold": "5000", "actual_payroll_cycle_start": "2024-06-01", "expected_payroll_cycle_end": "2024-06-30", "actual_payroll_cycle_cutoff": "2024-06-21T06:59:59Z", "withheld_tax_local_currency": "959.05", "expected_payroll_cycle_start": "2024-06-01", "expected_payroll_cycle_cutoff": "2024-06-21T06:59:59Z", "benefit_in_kind_local_currency": "14385.73", "quantity_exercised_or_released": "10000" } ], "cliff_period": 12, "grant_status": "GRANTED", "hris_profile": { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "email": "jane.doe@example.com", "pic_url": "https://cdn.deel.com/avatars/jane-doe.png", "job_title": "Software Engineer", "last_name": "Doe", "first_name": "Jane", "hiring_type": "employee", "middle_name": "Ann" }, "reference_id": 1024, "vested_events": [ { "quantity": 100, "vesting_date": "2025-03-01" } ], "exercise_price": 1.5, "grant_currency": "USD", "vesting_length": 48, "vested_quantity": 400, "fmv_when_granted": 3.2, "equity_grant_type": "RSU", "option_expiration": "2035-01-15", "vesting_start_date": "2025-02-01", "equity_grant_type_name": "Standard RSU", "exercise_price_currency": "USD", "additional_grant_requirements_and_restrictions": "Subject to board approval upon exercise" } ], "limit": 100, "total": 42, "offset": 0 } ``` **SDK Code** ```python import requests url = "https://api.letsdeel.com/rest/equity-grants" querystring = {"limit":"50","offset":"0","search":"Jane Doe"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.letsdeel.com/rest/equity-grants?limit=50&offset=0&search=Jane+Doe'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; 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-grants?limit=50&offset=0&search=Jane+Doe" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") 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-grants?limit=50&offset=0&search=Jane+Doe") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.letsdeel.com/rest/equity-grants?limit=50&offset=0&search=Jane+Doe") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.letsdeel.com/rest/equity-grants?limit=50&offset=0&search=Jane+Doe', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.letsdeel.com/rest/equity-grants?limit=50&offset=0&search=Jane+Doe"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.letsdeel.com/rest/equity-grants?limit=50&offset=0&search=Jane+Doe")! 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() ```