Deel: List equity grants with tax events — 200 response body — data item tax events item

List equity grants with tax events: 200 response body, field data / item / tax_events / item. Complete fields and constraints for contract 2026-10-27.

API reference · Contract 2026-10-27

SDK schema: List equity grants with tax events — 200 response body — data item tax events item

Field	Type	Presence	Description and constraints
`$`	object	Root
`actual_payroll_cycle_cutoff`	JSON	Optional
`actual_payroll_cycle_cutoff (anyOf 1)`	string	Alternative	The cutoff date of the actual payroll cycle Format: date-time
`actual_payroll_cycle_cutoff (anyOf 2)`	null	Alternative	The cutoff date of the actual payroll cycle Format: date-time
`actual_payroll_cycle_end`	JSON	Optional
`actual_payroll_cycle_end (anyOf 1)`	string	Alternative	The end date of the actual payroll cycle Format: date
`actual_payroll_cycle_end (anyOf 2)`	null	Alternative	The end date of the actual payroll cycle Format: date
`actual_payroll_cycle_id`	JSON	Optional
`actual_payroll_cycle_id (anyOf 1)`	string	Alternative	The unique identifier of the actual payroll cycle Format: uuid
`actual_payroll_cycle_id (anyOf 2)`	null	Alternative	The unique identifier of the actual payroll cycle Format: uuid
`actual_payroll_cycle_start`	JSON	Optional
`actual_payroll_cycle_start (anyOf 1)`	string	Alternative	The start date of the actual payroll cycle Format: date
`actual_payroll_cycle_start (anyOf 2)`	null	Alternative	The start date of the actual payroll cycle Format: date
`archived_at`	JSON	Optional
`archived_at (anyOf 1)`	string	Alternative	The date and time the tax event was archived Format: date-time
`archived_at (anyOf 2)`	null	Alternative	The date and time the tax event was archived Format: date-time
`benefit_in_kind_local_currency`	JSON	Optional
`benefit_in_kind_local_currency (anyOf 1)`	string	Alternative	The benefit-in-kind (BIK) value reported to payroll, expressed in the worker’s local payroll currency
`benefit_in_kind_local_currency (anyOf 2)`	null	Alternative	The benefit-in-kind (BIK) value reported to payroll, expressed in the worker’s local payroll currency
`contract_completion_date`	JSON	Optional
`contract_completion_date (anyOf 1)`	string	Alternative	The completion date of the associated contract Format: date-time
`contract_completion_date (anyOf 2)`	null	Alternative	The completion date of the associated contract Format: date-time
`contract_id`	string	Optional	The unique identifier of the contract associated with the tax event
`contract_status`	string	Optional	The lifecycle status of the associated worker contract (e.g. in_progress, completed, cancelled)
`country`	JSON	Optional
`country (anyOf 1)`	string	Alternative	The ISO 3166-1 alpha-2 country code of the worker’s employment country
`country (anyOf 2)`	null	Alternative	The ISO 3166-1 alpha-2 country code of the worker’s employment country
`created_at`	JSON	Optional
`created_at (anyOf 1)`	string	Alternative	The date and time the tax event was created Format: date-time
`created_at (anyOf 2)`	null	Alternative	The date and time the tax event was created Format: date-time
`created_by_email`	JSON	Optional
`created_by_email (anyOf 1)`	string	Alternative	The email of the user who created the tax event Format: email
`created_by_email (anyOf 2)`	null	Alternative	The email of the user who created the tax event Format: email
`email`	string	Optional	The worker’s email address Format: email
`equity_service_status`	string	Optional	The equity service enrollment status for the worker (ONBOARDED, OFFBOARDED, NOT_ONBOARDED, NOT_ELIGIBLE, MORE_INFO_REQUIRED)
`event_date`	JSON	Optional
`event_date (anyOf 1)`	string	Alternative	The date of the tax event Format: date
`event_date (anyOf 2)`	null	Alternative	The date of the tax event Format: date
`exercise_price`	JSON	Optional
`exercise_price (anyOf 1)`	string	Alternative	The price at which the equity was exercised
`exercise_price (anyOf 2)`	null	Alternative	The price at which the equity was exercised
`expected_payroll_cycle_cutoff`	JSON	Optional
`expected_payroll_cycle_cutoff (anyOf 1)`	string	Alternative	The cutoff date of the expected payroll cycle Format: date-time
`expected_payroll_cycle_cutoff (anyOf 2)`	null	Alternative	The cutoff date of the expected payroll cycle Format: date-time
`expected_payroll_cycle_end`	JSON	Optional
`expected_payroll_cycle_end (anyOf 1)`	string	Alternative	The end date of the expected payroll cycle Format: date
`expected_payroll_cycle_end (anyOf 2)`	null	Alternative	The end date of the expected payroll cycle Format: date
`expected_payroll_cycle_id`	JSON	Optional
`expected_payroll_cycle_id (anyOf 1)`	string	Alternative	The unique identifier of the expected payroll cycle Format: uuid
`expected_payroll_cycle_id (anyOf 2)`	null	Alternative	The unique identifier of the expected payroll cycle Format: uuid
`expected_payroll_cycle_start`	JSON	Optional
`expected_payroll_cycle_start (anyOf 1)`	string	Alternative	The start date of the expected payroll cycle Format: date
`expected_payroll_cycle_start (anyOf 2)`	null	Alternative	The start date of the expected payroll cycle Format: date
`external_id`	JSON	Optional
`external_id (anyOf 1)`	string	Alternative	An external system identifier for the worker, such as an ID from a cap-table provider
`external_id (anyOf 2)`	null	Alternative	An external system identifier for the worker, such as an ID from a cap-table provider
`first_name`	JSON	Optional
`first_name (anyOf 1)`	string	Alternative	The worker’s first name
`first_name (anyOf 2)`	null	Alternative	The worker’s first name
`fx_rate`	JSON	Optional
`fx_rate (anyOf 1)`	string	Alternative	The exchange rate used to convert local currency to payroll currency
`fx_rate (anyOf 2)`	null	Alternative	The exchange rate used to convert local currency to payroll currency
`grant_date`	JSON	Optional
`grant_date (anyOf 1)`	string	Alternative	The date the associated grant was issued Format: date
`grant_date (anyOf 2)`	null	Alternative	The date the associated grant was issued Format: date
`grant_id`	JSON	Optional
`grant_id (anyOf 1)`	string	Alternative	The unique identifier of the associated grant Format: uuid
`grant_id (anyOf 2)`	null	Alternative	The unique identifier of the associated grant Format: uuid
`grant_reference_id`	JSON	Optional
`grant_reference_id (anyOf 1)`	JSON	Alternative
`grant_reference_id (anyOf 1) (anyOf 1)`	number	Alternative	The human-readable reference number of the associated grant Format: double
`grant_reference_id (anyOf 1) (anyOf 2)`	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
`grant_reference_id (anyOf 2)`	null	Alternative	The human-readable reference number of the associated grant Format: double
`grant_type`	JSON	Optional
`grant_type (anyOf 1)`	string	Alternative	The equity instrument type of the associated grant (e.g. RSU, NSO, ISO)
`grant_type (anyOf 2)`	null	Alternative	The equity instrument type of the associated grant (e.g. RSU, NSO, ISO)
`gross_value`	JSON	Optional
`gross_value (anyOf 1)`	string	Alternative	The gross value of the equity event, calculated as unit FMV multiplied by quantity exercised or released
`gross_value (anyOf 2)`	null	Alternative	The gross value of the equity event, calculated as unit FMV multiplied by quantity exercised or released
`hris_profile_id`	string	Optional	The unique identifier of the worker who holds the grant Format: uuid
`id`	string	Optional	The unique identifier of the tax event Format: uuid
`instrument_type`	JSON	Optional
`instrument_type (anyOf 1)`	string	Alternative	The type of equity instrument (e.g. RSU, NSO, ISO, PHANTOM, SARS)
`instrument_type (anyOf 2)`	null	Alternative	The type of equity instrument (e.g. RSU, NSO, ISO, PHANTOM, SARS)
`is_archived`	JSON	Optional
`is_archived (anyOf 1)`	boolean	Alternative	Whether the tax event has been archived
`is_archived (anyOf 2)`	null	Alternative	Whether the tax event has been archived
`last_name`	JSON	Optional
`last_name (anyOf 1)`	string	Alternative	The worker’s last name
`last_name (anyOf 2)`	null	Alternative	The worker’s last name
`method_of_tax_coverage`	JSON	Optional
`method_of_tax_coverage (anyOf 1)`	string	Alternative	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.
`method_of_tax_coverage (anyOf 2)`	null	Alternative	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.
`middle_name`	JSON	Optional
`middle_name (anyOf 1)`	string	Alternative	The worker’s middle name
`middle_name (anyOf 2)`	null	Alternative	The worker’s middle name
`note`	JSON	Optional
`note (anyOf 1)`	string	Alternative	A free-text note attached to the tax event
`note (anyOf 2)`	null	Alternative	A free-text note attached to the tax event
`organization_id`	string	Optional	The unique identifier of the organization Format: uuid
`organization_name`	JSON	Optional
`organization_name (anyOf 1)`	string	Alternative	The name of the organization
`organization_name (anyOf 2)`	null	Alternative	The name of the organization
`payroll_currency`	JSON	Optional
`payroll_currency (anyOf 1)`	string	Alternative	The currency in which payroll is processed
`payroll_currency (anyOf 2)`	null	Alternative	The currency in which payroll is processed
`pic_url`	JSON	Optional
`pic_url (anyOf 1)`	string	Alternative	URL of the worker’s profile picture
`pic_url (anyOf 2)`	null	Alternative	URL of the worker’s profile picture
`plan_currency`	JSON	Optional
`plan_currency (anyOf 1)`	string	Alternative	The currency in which the equity plan was issued
`plan_currency (anyOf 2)`	null	Alternative	The currency in which the equity plan was issued
`quantity_exercised_or_released`	JSON	Optional
`quantity_exercised_or_released (anyOf 1)`	string	Alternative	The quantity of equity exercised or released
`quantity_exercised_or_released (anyOf 2)`	null	Alternative	The quantity of equity exercised or released
`quantity_remaining`	JSON	Optional
`quantity_remaining (anyOf 1)`	string	Alternative	The quantity of equity remaining
`quantity_remaining (anyOf 2)`	null	Alternative	The quantity of equity remaining
`quantity_withheld_or_sold`	JSON	Optional
`quantity_withheld_or_sold (anyOf 1)`	string	Alternative	The quantity of equity withheld or sold
`quantity_withheld_or_sold (anyOf 2)`	null	Alternative	The quantity of equity withheld or sold
`sale_price`	JSON	Optional
`sale_price (anyOf 1)`	string	Alternative	The price at which the equity was sold
`sale_price (anyOf 2)`	null	Alternative	The price at which the equity was sold
`sent_for_processing_at`	JSON	Optional
`sent_for_processing_at (anyOf 1)`	string	Alternative	The date and time the event was sent for payroll processing Format: date-time
`sent_for_processing_at (anyOf 2)`	null	Alternative	The date and time the event was sent for payroll processing Format: date-time
`settlement_date`	JSON	Optional
`settlement_date (anyOf 1)`	string	Alternative	The date the equity event was settled (i.e. when shares were transferred or cash was received) Format: date
`settlement_date (anyOf 2)`	null	Alternative	The date the equity event was settled (i.e. when shares were transferred or cash was received) Format: date
`supporting_documents_id`	JSON	Optional
`supporting_documents_id (anyOf 1)`	string	Alternative	The unique identifier of the supporting documents attached to the event Format: uuid
`supporting_documents_id (anyOf 2)`	null	Alternative	The unique identifier of the supporting documents attached to the event Format: uuid
`tax_jurisdiction`	JSON	Optional
`tax_jurisdiction (anyOf 1)`	string	Alternative	The ISO 3166-1 alpha-2 country code of the worker’s contract jurisdiction at the time of the event
`tax_jurisdiction (anyOf 2)`	null	Alternative	The ISO 3166-1 alpha-2 country code of the worker’s contract jurisdiction at the time of the event
`tax_rate`	JSON	Optional
`tax_rate (anyOf 1)`	string	Alternative	The tax rate applied to the benefit in kind
`tax_rate (anyOf 2)`	null	Alternative	The tax rate applied to the benefit in kind
`taxable_gain_or_loss`	JSON	Optional
`taxable_gain_or_loss (anyOf 1)`	string	Alternative	The taxable gain or loss on the event, typically gross value minus the total exercise price
`taxable_gain_or_loss (anyOf 2)`	null	Alternative	The taxable gain or loss on the event, typically gross value minus the total exercise price
`total_exercise_price`	JSON	Optional
`total_exercise_price (anyOf 1)`	string	Alternative	The total exercise price paid for the equity, calculated as exercise price per unit multiplied by quantity exercised
`total_exercise_price (anyOf 2)`	null	Alternative	The total exercise price paid for the equity, calculated as exercise price per unit multiplied by quantity exercised
`total_taxes_withheld`	JSON	Optional
`total_taxes_withheld (anyOf 1)`	string	Alternative	The total amount of income tax and social contributions withheld on behalf of the worker
`total_taxes_withheld (anyOf 2)`	null	Alternative	The total amount of income tax and social contributions withheld on behalf of the worker
`transaction_fees`	JSON	Optional
`transaction_fees (anyOf 1)`	string	Alternative	Brokerage or transaction fees associated with the equity event, in plan currency
`transaction_fees (anyOf 2)`	null	Alternative	Brokerage or transaction fees associated with the equity event, in plan currency
`unit_fmv`	JSON	Optional
`unit_fmv (anyOf 1)`	string	Alternative	The fair market value per unit at the time of the event
`unit_fmv (anyOf 2)`	null	Alternative	The fair market value per unit at the time of the event
`updated_at`	JSON	Optional
`updated_at (anyOf 1)`	string	Alternative	The date and time the tax event was last updated Format: date-time
`updated_at (anyOf 2)`	null	Alternative	The date and time the tax event was last updated Format: date-time
`verification_status`	JSON	Optional
`verification_status (anyOf 1)`	string	Alternative	The current verification status of the tax event (PENDING_VERIFICATION, VERIFIED, SENT_FOR_PROCESSING, PROCESSED, MISMATCH)
`verification_status (anyOf 2)`	null	Alternative	The current verification status of the tax event (PENDING_VERIFICATION, VERIFIED, SENT_FOR_PROCESSING, PROCESSED, MISMATCH)
`withheld_tax_local_currency`	JSON	Optional
`withheld_tax_local_currency (anyOf 1)`	string	Alternative	The income tax and social contributions withheld, expressed in the worker’s local payroll currency
`withheld_tax_local_currency (anyOf 2)`	null	Alternative	The income tax and social contributions withheld, expressed in the worker’s local payroll currency

Report an issue with this page