GuidesAPI ReferenceChangelog
Changelog

v1.35

New Adjustments endpoints

Added

Retrieve adjustments

Get all adjustments for your organization.

Endpoint: POST rest/v1/adjustments

Sample request

curl --request GET \
     --url https://api.letsdeel.com/rest/v1/adjustments \
     --header 'accept: application/json' \
     --header 'authorization: Bearer toke'

Create new adjustment

Create a new adjustment.

Endpoint: POST rest/v1/adjustments

Sample request

curl --request POST \
     --url https://api.letsdeel.com/rest/v1/adjustments \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token' \
     --header 'content-type: application/json' \
     --data '
{
  "data": {
    "contract_id": "m3jk2j",
    "amount": 100.25,
    "date_of_adjustment": "1999-12-31",
    "title": "Your title here",
    "description": "Your description here",
    "cycle_reference": "my_cycle_reference",
    "adjustment_category_id": "c9cf4c2c0165f48f494415390c3b49",
    "move_next_cycle": true
  }
}
'

Retrieve an adjustment

Retrieve an adjustment.

Endpoint: GET rest/v1/adjustments/{adjustment_id}

Sample request

curl --request GET \
     --url https://api.letsdeel.com/rest/v1/adjustments/adjustment_id \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token'

Update an adjustment

Update an adjustment.

Endpoint: PATCH rest/v1/adjustments/{adjustment_id}

Sample request

curl --request PATCH \
     --url https://api.letsdeel.com/rest/v1/adjustments/adjustment_id \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token' \
     --header 'content-type: application/json' \
     --data '
{
  "data": {
    "amount": 100.25,
    "title": "Your title here",
    "description": "Your description here",
    "cycle_reference": "my_cycle_reference"
  }
}
'

Delete an adjustment

Delete an adjustment.

Endpoint: DELETE rest/v1/adjustments/{adjustment_id}

Sample request

curl --request DELETE \
     --url https://api.letsdeel.com/rest/v1/adjustments/adjustment_id \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token'

Retrieve categories

Get all categories for your organization.

Endpoint: GET rest/v1/adjustments/categories

Sample request

curl --request GET \
     --url https://api.letsdeel.com/rest/v1/adjustments/categories \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token'

v1.34

New Global Payroll endpoints

Added

Add bank account

Add a new bank account for an employee.

Endpoint: POST rest/v1/gp/workers/{worker_id}/banks

Sample request

curl --request POST \
     --url https://api.letsdeel.com/rest/v1/gp/workers/worker_id/banks \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token' \
     --header 'content-type: application/json' \
     --data '
{
  "data": {
    "full_name": "John Doe",
    "phone": "+1234567890",
    "address_line1": "1234 Main St",
    "address_line2": "Apartment 101",
    "city": "Springfield",
    "province_state": "Ontario",
    "postal": "12345",
    "bank_name": "Bank of Examples",
    "country_code": "US",
    "bank_country_code": "US",
    "swift_bic": "EXAMPLEBIC",
    "account_number": "123456789012",
    "bank_code": "123",
    "original_name": "Johnathan Doe",
    "tax_id": "123-45-6789",
    "branch_code": "001",
    "currency_code": "USD",
    "bank_branch_name": "Main Street Branch",
    "iban": "GB29NWBK60161331926819",
    "email": "[email protected]",
    "rib_number": "12345678901",
    "account_type": "12345678901",
    "ach_routing_number": "12345678901"
  }
}
'

Retrieve bank accounts

Retrieve all bank accounts for an employee.

Endpoint: GET rest/v1/gp/workers/{worker_id}/banks

Sample request

curl --request GET \
     --url https://api.letsdeel.com/rest/v1/gp/workers/worker_id/banks \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token'

Modify bank account

Modify bank account for an employee.

Endpoint: PATCH rest/v1/gp/workers/{worker_id}/banks/{bank_id}

Sample request

curl --request PATCH \
     --url https://api.letsdeel.com/rest/v1/gp/workers/worker_id/banks/bank_id \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token' \
     --header 'content-type: application/json' \
     --data '
{
  "data": {
    "full_name": "John Doe",
    "phone": "+1234567890",
    "address_line1": "1234 Main St",
    "address_line2": "Apartment 101",
    "city": "Springfield",
    "province_state": "Ontario",
    "postal": "12345",
    "bank_name": "Bank of Examples",
    "country_code": "US",
    "bank_country_code": "US",
    "swift_bic": "EXAMPLEBIC",
    "account_number": "123456789012",
    "bank_code": "123",
    "original_name": "Johnathan Doe",
    "tax_id": "123-45-6789",
    "branch_code": "001",
    "currency_code": "USD",
    "bank_branch_name": "Main Street Branch",
    "iban": "GB29NWBK60161331926819",
    "email": "[email protected]",
    "rib_number": "12345678901",
    "account_type": "12345678901",
    "ach_routing_number": "12345678901"
  }
}
'

Retrieve bank guide

Retrieve the bank form guide for employee.

Endpoint: GET rest/v1/gp/workers/{worker_id}/banks/{bank_id}

Sample request

curl --request GET \
     --url https://api.letsdeel.com/rest/v1/gp/workers/worker_id/banks/guide \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token'

Remove

Webhook Events

We have removed the contract.archived webhoook.

v1.33

New EOR endpoints

Added

Employee Cost Calculator

Determine EOR employee costs across the globe.

Endpoint: POST /rest/v1/eor/employment_cost

Sample request

curl --request POST \
     --url https://api.letsdeel.com/rest/v1/eor/employment_cost \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token' \
     --header 'content-type: application/json' \
     --data '
{
  "data": {
    "salary": 50000,
    "country": "Germany",
    "currency": "EUR"
  }
}
'

v1.32

New fields in Tasks endpoints

Added

POST /contracts/{contract_id}/tasks

We added id and status properties in the response of POST /contracts/{contract_id}/tasks endpoint.

Sample response

{
  "data": {
    "created": true,
    "id": "0d636d0d-a869-4e29-8f64-889869a444d9",
    "status": "approved"
  }
}

v2.0

New Accounting V2 endpoints

Added

Retrieve invoices

Retrieve a list of paid invoices for your workforce.

Endpoint: GET /rest/v2/invoices

Sample request

curl --request GET \
     --url https://api.letsdeel.com/rest/v2/invoices \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token'

Retrieve Deel invoices

Retrieve a list of invoices related to Deel fees.
Endpoint: GET /rest/v2/invoices/deel

Sample request

curl --request GET \
     --url https://api.letsdeel.com/rest/v2/invoices/deel \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token'

Download invoice

Get link to download the invoice PDF.

Endpoint: GET /rest/v2/invoices/{invoice_id}/download

Sample request

curl --request GET \
     --url https://api.letsdeel.com/rest/v2/invoices/invoice_id/download \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token'

v1.31

New People endpoints

Added

Retrieve Departments

Retrieve the list of departments in your organization.

Endpoint: GET /rest/v1/departments

Sample request

curl --request GET \
     --url https://api.letsdeel.com/rest/v1/departments \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token'

Update Department

Update department for a specific worker using the worker's ID.
Endpoint: PUT /rest/v1/people/worker_id/department

Sample request

curl --request PUT \
     --url https://api.letsdeel.com/rest/v1/people/worker_id/department \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token' \
     --header 'content-type: application/json' \
     --data '
{
  "data": {
    "department_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}
'

Retrieve Working Locations

Retrieve the list of working locations in your organization.

Endpoint: GET /rest/v1/working-locations

Sample request

curl --request GET \
     --url https://api.letsdeel.com/rest/v1/working-locations \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token'

Update Working Location

Update working location for a specific worker using the worker's ID.
Endpoint: PUT /rest/v1/people/worker_id/working-location

Sample request

curl --request PUT \
     --url https://api.letsdeel.com/rest/v1/people/worker_id/working-location \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token' \
     --header 'content-type: application/json' \
     --data '
{
  "data": {
    "working_location_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}
'

v1.30

New EOR endpoints

Added

Retrieve Payslips

Retrieve a list of payslips for a specific worker by their worker ID.

Endpoint: GET /rest/v1/eor/workers/{worker_id}/payslips

Sample request

curl --request GET \
     --url https://api.letsdeel.com/rest/v1/eor/workers/0123abcd-e031-4f1e-93d4-6bc66e8c4727/payslips \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token'

Download Specific Payslip

Download a specific payslip for a worker using the payslip’s ID.
Endpoint: GET /rest/v1/eor/workers/{worker_id}/payslips/{payslip_id}/download

Sample request

curl --request GET \
     --url https://api.letsdeel.com/rest/v1/eor/workers/0123abcd-e031-4f1e-93d4-6bc66e8c4727/payslips/ApdZbLvq0r0E/download \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token'

v1.29

New Global Payroll endpoints

Added

Retrieve Payslips

Retrieve a list of payslips for a specific worker by their worker ID.

Endpoint: GET /rest/v1/gp/workers/{worker_id}/payslips

Sample request

curl --request GET \
     --url https://api.letsdeel.com/rest/v1/gp/workers/0123abcd-e031-4f1e-93d4-6bc66e8c4727/payslips \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token'

Download Specific Payslip

Download a specific payslip for a worker using the payslip’s ID.
Endpoint: GET /rest/v1/gp/workers/{worker_id}/payslips/{payslip_id}/download

Sample request

curl --request GET \
     --url https://api.letsdeel.com/rest/v1/gp/workers/0123abcd-e031-4f1e-93d4-6bc66e8c4727/payslips/ApdZbLvq0r0E/download \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token'

Update Address

Update the address details of a worker using their worker ID.
Endpoint: PATCH /rest/v1/gp/workers/{worker_id}/address

Sample request

curl --request PATCH \
     --url https://api.letsdeel.com/rest/v1/gp/workers/0123abcd-e031-4f1e-93d4-6bc66e8c4727/address \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token' \
     --header 'content-type: application/json' \
     --data '
{
  "data": {
    "city": "London",
    "street": "123 Deel Street",
    "zip": "12345"
  }
}
'

Modify Compensation

Modify the compensation details of a specific worker.
Endpoint: PATCH /rest/v1/gp/workers/{worker_id}/compensation

Sample request

curl --request PATCH \
     --url https://api.letsdeel.com/rest/v1/gp/workers/0123abcd-e031-4f1e-93d4-6bc66e8c4727/compensation \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token' \
     --header 'content-type: application/json' \
     --data '
{
  "data": {
    "scale": "YEAR",
    "salary": 50000,
    "effective_date": "1999-12-31"
  }
}
'

Adjust PTO Policy

Adjust the Paid Time Off (PTO) policy for a specific worker.
Endpoint: PATCH /rest/v1/gp/workers/{worker_id}/pto-policy

Sample request

curl --request PATCH \
     --url https://api.letsdeel.com/rest/v1/gp/workers/0123abcd-e031-4f1e-93d4-6bc66e8c4727/pto-policy \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token' \
     --header 'content-type: application/json' \
     --data '
{
  "data": {
    "accrual_start_date": "1999-12-31",
    "yearly_allowance": "15"
  }
}
'

Update Employee Information

Update general employee information for a worker by their ID.
Endpoint: PATCH /rest/v1/gp/workers/{worker_id}/employee-information

Sample request

curl --request PATCH \
     --url https://api.letsdeel.com/rest/v1/gp/workers/worker_id/employee-information \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token' \
     --header 'content-type: application/json' \
     --data '
{
  "data": {
    "first_name": "Jane",
    "middle_name": "Jay",
    "last_name": "Doe",
    "date_of_birth": "1999-12-31",
    "gender": "string",
    "marital_status": "Single"
  }
}
'

Custom fields in GET /people/:id endpoint

We added custom_fields property in the response of GET /people/:id endpoint. Now, you can get custom fields for an employee.

Sample response

{
    "custom_fields": [
        {
            "name": "Job title",
            "value": "Software Engineer II"
        }
    ]
}

v1.28

New Time-off endpoints.

Added

Time-off API

We have released a whole new time-off API which makes it even easier to add, update, and review employee PTO. The new API uses worker_id as the identifier vs contract_id.

Sample Request

Create a time-off request using the following format

curl --request POST \
     --url https://api.letsdeel.com/rest/v1/people/0123abcd-e031-4f1e-93d4-6bc66e8c4727/time-offs \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {token}' \
     --header 'content-type: multipart/form-data' \
     --form type=VACATION \
     --form start_date=2023-11-03 \
     --form end_date=2023-11-05 \
     --form reason=Holiday

v1.27

OAuth updates.

Updated

OAuth Server Change

We have moved the OAuth server to the same domain as the Deel app. You can now use app.deel.com/oauth2/... for all of your OAuth-related requests to Deel.

For example, the API call to exchange and auth grant for an access token will look like this:

POST 'https://app.deel.com/oauth2/tokens' \
--header 'Authorization: Basic d3dzZm5lbG84MDowYWZzN3h2MGQ5' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code={authorization_code}' \
--data-urlencode 'redirect_uri={redirectUri}'

OAuth calls to demo can be made to this host:demo.letsdeel.com/oauth2/....