> 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. # Create a request to exercise equity. POST https://api.letsdeel.com/rest/equity/exercise Content-Type: application/json Submits a new equity exercise request, associating the specified option grant and stakeholder details with a worker. The request is created in a pending state; employer approval is handled as a separate operation. **Token scopes**: `contracts:write` Reference: https://developer.deel.com/api/reference/endpoints/contracts/create-a-request-to-exercise-equity-v-2026-01-01 ## 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 ### Body (application/json) This endpoint expects an object. - `fmv` (string, required) — The fair market value of the equity. - `quantity` (double, required) — The quantity of equity to exercise. Must be a positive number. - `issuer_id` (string, required) — The unique identifier of the issuer. - `worker_id` (string, required) — The public UUID of the worker. Must correspond to an existing worker in the system. - `address_zip` (string, required) — The zip code of the address. - `exercise_id` (string, required) — The unique identifier of the exercise. - `address_city` (string, required) — The city of the address. - `address_state` (string, required) — The state of the address. - `address_street` (string, required) — The street of the address. - `stakeholder_id` (string, required) — The unique identifier of the stakeholder. - `address_country` (string, required) — The country of the address. - `option_grant_id` (string, required) — The numeric identifier of the option grant. Must contain only digits. - `fmv_currency_code` (string, required) — The currency code of the fair market value (ISO 4217). - `stakeholder_email` (string, required) — The email address of the stakeholder. - `option_grant_issue` (string, required) — The issue of the option grant. - `option_grant_label` (string, required) — The label of the option grant. - `option_grant_currency` (string, required) — The currency of the option grant (ISO 4217). - `option_grant_issue_date` (string, required) — The issue date of the option grant (ISO 8601 date). - `option_grant_expiry_date` (string, required) — The expiry date of the option grant (ISO 8601 date). - `stakeholder_relationship` (string, required) — The relationship of the stakeholder. - `option_grant_strike_price` (string, required) — The strike price of the option grant. ## Response ### 201 Equity exercise request created successfully. - `data` (EquityExercisePostResponsesContentApplicationJsonSchemaData, required) ## Errors ### 400 Bad Request Error Request validation failed. A required field is missing, has an invalid format, or the worker is not eligible for equity exercise. - `errors` (list of EquityExercisePostResponsesContentApplicationJsonSchemaErrorsItems, required) ### 401 Unauthorized Error Authentication failed. The access token is missing, expired, or invalid. - `errors` (list of EquityExercisePostResponsesContentApplicationJsonSchemaErrorsItems, required) ### 403 Forbidden Error Access denied. The authenticated user does not have the required contracts:write scope. - `errors` (list of EquityExercisePostResponsesContentApplicationJsonSchemaErrorsItems, required) ### 404 Not Found Error The worker profile associated with the given worker_id was not found. - `errors` (list of EquityExercisePostResponsesContentApplicationJsonSchemaErrorsItems, required) ### 422 Unprocessable Entity Error A request with the same exercise_id already exists. Each exercise_id can only be used once. - `errors` (list of EquityExercisePostResponsesContentApplicationJsonSchemaErrorsItems, required) ### 429 Too Many Requests Error Rate limit exceeded. - `errors` (list of EquityExercisePostResponsesContentApplicationJsonSchemaErrorsItems, required) ### 500 Internal Server Error Internal server error. Possible causes include missing EOR contract for the worker, FX rate service failure, or database errors. - `errors` (list of EquityExercisePostResponsesContentApplicationJsonSchemaErrorsItems, required) ## Types ### EquityExercisePostResponsesContentApplicationJsonSchemaData - `id` (string, required) — Unique identifier of the equity exercise request. - `status` (string, required) — The initial status of the newly created equity exercise request. - `created_at` (string, required) — ISO 8601 timestamp when the equity exercise request was created. - `updated_at` (string, required) — ISO 8601 timestamp when the equity exercise request was last updated. ### EquityExercisePostResponsesContentApplicationJsonSchemaErrorsItems - `message` (string, required) — General error description for logging and debugging. ## Examples **Request** ```json { "fmv": "100.00", "quantity": 100, "issuer_id": "d290f1ee-6c54-4b01-90e6-d701748f0851", "worker_id": "d290f1ee-6c54-4b01-90e6-d701748f0851", "address_zip": "94107", "exercise_id": "d290f1ee-6c54-4b01-90e6-d701748f0851", "address_city": "San Francisco", "address_state": "CA", "address_street": "123 Main St", "stakeholder_id": "SH-001234", "address_country": "US", "option_grant_id": "12345", "fmv_currency_code": "USD", "stakeholder_email": "stakeholder@example.com", "option_grant_issue": "Series A", "option_grant_label": "Stock Option Grant #1", "option_grant_currency": "USD", "option_grant_issue_date": "2022-01-01", "option_grant_expiry_date": "2032-01-01", "stakeholder_relationship": "employee", "option_grant_strike_price": "10.50" } ``` **Response** ```json { "data": { "id": "d290f1ee-6c54-4b01-90e6-d701748f0851", "status": "WTH_TAX_CALCULATION_REQUESTED", "created_at": "2023-05-01T12:00:00.000Z", "updated_at": "2023-05-01T12:00:00.000Z" } } ``` **SDK Code** ```python Contracts_createARequestToExerciseEquity-v2026-01-01_example import requests url = "https://api.letsdeel.com/rest/equity/exercise" payload = { "fmv": "100.00", "quantity": 100, "issuer_id": "d290f1ee-6c54-4b01-90e6-d701748f0851", "worker_id": "d290f1ee-6c54-4b01-90e6-d701748f0851", "address_zip": "94107", "exercise_id": "d290f1ee-6c54-4b01-90e6-d701748f0851", "address_city": "San Francisco", "address_state": "CA", "address_street": "123 Main St", "stakeholder_id": "SH-001234", "address_country": "US", "option_grant_id": "12345", "fmv_currency_code": "USD", "stakeholder_email": "stakeholder@example.com", "option_grant_issue": "Series A", "option_grant_label": "Stock Option Grant #1", "option_grant_currency": "USD", "option_grant_issue_date": "2022-01-01", "option_grant_expiry_date": "2032-01-01", "stakeholder_relationship": "employee", "option_grant_strike_price": "10.50" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Contracts_createARequestToExerciseEquity-v2026-01-01_example const url = 'https://api.letsdeel.com/rest/equity/exercise'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"fmv":"100.00","quantity":100,"issuer_id":"d290f1ee-6c54-4b01-90e6-d701748f0851","worker_id":"d290f1ee-6c54-4b01-90e6-d701748f0851","address_zip":"94107","exercise_id":"d290f1ee-6c54-4b01-90e6-d701748f0851","address_city":"San Francisco","address_state":"CA","address_street":"123 Main St","stakeholder_id":"SH-001234","address_country":"US","option_grant_id":"12345","fmv_currency_code":"USD","stakeholder_email":"stakeholder@example.com","option_grant_issue":"Series A","option_grant_label":"Stock Option Grant #1","option_grant_currency":"USD","option_grant_issue_date":"2022-01-01","option_grant_expiry_date":"2032-01-01","stakeholder_relationship":"employee","option_grant_strike_price":"10.50"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Contracts_createARequestToExerciseEquity-v2026-01-01_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.letsdeel.com/rest/equity/exercise" payload := strings.NewReader("{\n \"fmv\": \"100.00\",\n \"quantity\": 100,\n \"issuer_id\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"worker_id\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"address_zip\": \"94107\",\n \"exercise_id\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"address_city\": \"San Francisco\",\n \"address_state\": \"CA\",\n \"address_street\": \"123 Main St\",\n \"stakeholder_id\": \"SH-001234\",\n \"address_country\": \"US\",\n \"option_grant_id\": \"12345\",\n \"fmv_currency_code\": \"USD\",\n \"stakeholder_email\": \"stakeholder@example.com\",\n \"option_grant_issue\": \"Series A\",\n \"option_grant_label\": \"Stock Option Grant #1\",\n \"option_grant_currency\": \"USD\",\n \"option_grant_issue_date\": \"2022-01-01\",\n \"option_grant_expiry_date\": \"2032-01-01\",\n \"stakeholder_relationship\": \"employee\",\n \"option_grant_strike_price\": \"10.50\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Contracts_createARequestToExerciseEquity-v2026-01-01_example require 'uri' require 'net/http' url = URI("https://api.letsdeel.com/rest/equity/exercise") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"fmv\": \"100.00\",\n \"quantity\": 100,\n \"issuer_id\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"worker_id\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"address_zip\": \"94107\",\n \"exercise_id\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"address_city\": \"San Francisco\",\n \"address_state\": \"CA\",\n \"address_street\": \"123 Main St\",\n \"stakeholder_id\": \"SH-001234\",\n \"address_country\": \"US\",\n \"option_grant_id\": \"12345\",\n \"fmv_currency_code\": \"USD\",\n \"stakeholder_email\": \"stakeholder@example.com\",\n \"option_grant_issue\": \"Series A\",\n \"option_grant_label\": \"Stock Option Grant #1\",\n \"option_grant_currency\": \"USD\",\n \"option_grant_issue_date\": \"2022-01-01\",\n \"option_grant_expiry_date\": \"2032-01-01\",\n \"stakeholder_relationship\": \"employee\",\n \"option_grant_strike_price\": \"10.50\"\n}" response = http.request(request) puts response.read_body ``` ```java Contracts_createARequestToExerciseEquity-v2026-01-01_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.letsdeel.com/rest/equity/exercise") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"fmv\": \"100.00\",\n \"quantity\": 100,\n \"issuer_id\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"worker_id\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"address_zip\": \"94107\",\n \"exercise_id\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"address_city\": \"San Francisco\",\n \"address_state\": \"CA\",\n \"address_street\": \"123 Main St\",\n \"stakeholder_id\": \"SH-001234\",\n \"address_country\": \"US\",\n \"option_grant_id\": \"12345\",\n \"fmv_currency_code\": \"USD\",\n \"stakeholder_email\": \"stakeholder@example.com\",\n \"option_grant_issue\": \"Series A\",\n \"option_grant_label\": \"Stock Option Grant #1\",\n \"option_grant_currency\": \"USD\",\n \"option_grant_issue_date\": \"2022-01-01\",\n \"option_grant_expiry_date\": \"2032-01-01\",\n \"stakeholder_relationship\": \"employee\",\n \"option_grant_strike_price\": \"10.50\"\n}") .asString(); ``` ```php Contracts_createARequestToExerciseEquity-v2026-01-01_example request('POST', 'https://api.letsdeel.com/rest/equity/exercise', [ 'body' => '{ "fmv": "100.00", "quantity": 100, "issuer_id": "d290f1ee-6c54-4b01-90e6-d701748f0851", "worker_id": "d290f1ee-6c54-4b01-90e6-d701748f0851", "address_zip": "94107", "exercise_id": "d290f1ee-6c54-4b01-90e6-d701748f0851", "address_city": "San Francisco", "address_state": "CA", "address_street": "123 Main St", "stakeholder_id": "SH-001234", "address_country": "US", "option_grant_id": "12345", "fmv_currency_code": "USD", "stakeholder_email": "stakeholder@example.com", "option_grant_issue": "Series A", "option_grant_label": "Stock Option Grant #1", "option_grant_currency": "USD", "option_grant_issue_date": "2022-01-01", "option_grant_expiry_date": "2032-01-01", "stakeholder_relationship": "employee", "option_grant_strike_price": "10.50" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Contracts_createARequestToExerciseEquity-v2026-01-01_example using RestSharp; var client = new RestClient("https://api.letsdeel.com/rest/equity/exercise"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"fmv\": \"100.00\",\n \"quantity\": 100,\n \"issuer_id\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"worker_id\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"address_zip\": \"94107\",\n \"exercise_id\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"address_city\": \"San Francisco\",\n \"address_state\": \"CA\",\n \"address_street\": \"123 Main St\",\n \"stakeholder_id\": \"SH-001234\",\n \"address_country\": \"US\",\n \"option_grant_id\": \"12345\",\n \"fmv_currency_code\": \"USD\",\n \"stakeholder_email\": \"stakeholder@example.com\",\n \"option_grant_issue\": \"Series A\",\n \"option_grant_label\": \"Stock Option Grant #1\",\n \"option_grant_currency\": \"USD\",\n \"option_grant_issue_date\": \"2022-01-01\",\n \"option_grant_expiry_date\": \"2032-01-01\",\n \"stakeholder_relationship\": \"employee\",\n \"option_grant_strike_price\": \"10.50\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Contracts_createARequestToExerciseEquity-v2026-01-01_example import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "fmv": "100.00", "quantity": 100, "issuer_id": "d290f1ee-6c54-4b01-90e6-d701748f0851", "worker_id": "d290f1ee-6c54-4b01-90e6-d701748f0851", "address_zip": "94107", "exercise_id": "d290f1ee-6c54-4b01-90e6-d701748f0851", "address_city": "San Francisco", "address_state": "CA", "address_street": "123 Main St", "stakeholder_id": "SH-001234", "address_country": "US", "option_grant_id": "12345", "fmv_currency_code": "USD", "stakeholder_email": "stakeholder@example.com", "option_grant_issue": "Series A", "option_grant_label": "Stock Option Grant #1", "option_grant_currency": "USD", "option_grant_issue_date": "2022-01-01", "option_grant_expiry_date": "2032-01-01", "stakeholder_relationship": "employee", "option_grant_strike_price": "10.50" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.letsdeel.com/rest/equity/exercise")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data 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() ```