GuidesAPI ReferenceChangelog
Changelog

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/....

v1.26

Introduce people endpoints.

Added

People Endpoints

We're excited to announce the launch of our latest feature, allowing you to retrieve a list of people in your Deel account.

Programmatically fetch, analyze, and leverage a comprehensive list of individuals associated with your organization to enhance team management and strategic decision-making.

Sample Request

curl --location 'https://api.letsdeel.com/rest/v1/people' \
--header 'Authorization: Bearer {token}'

Sample Response

{
    "data": [
        {
            "id": "a4f91c16-2104-4841-ba4e-77fdcb5bc6ee",
            "created_at": "2023-07-21T07:44:58.437Z",
            "first_name": "Whitney",
            "last_name": "Houston",
            "full_name": "Whitney Houston",
            "emails": [
                {
                    "type": "primary",
                    "value": "[email protected]"
                },
                {
                    "type": "work",
                    "value": null
                },
                {
                    "type": "personal",
                    "value": "[email protected]"
                }
            ],
            "birth_date": null,
            "start_date": "2023-08-05",
            "nationality": null,
            "client_legal_entity": {
                "id": 232324,
                "name": "Aleena Moon"
            },
            "state": "BE",
            "seniority": "Lead (Individual Contributor Level 4)",
            "completion_date": "2023-07-21T07:45:11.807Z",
            "direct_manager": null,
            "direct_reports": null,
            "direct_reports_count": 0,
            "employments": [
                {
                    "id": "3edvyng",
                    "name": "Fixed-Rate API- 2023-07-21",
                    "team": {
                        "id": 384149,
                        "name": "Oleena"
                    },
                    "email": "[email protected]",
                    "state": "BE",
                    "country": "GE",
                    "payment": null,
                    "is_ended": true,
                    "timezone": null,
                    "job_title": "QA Engineer",
                    "seniority": "Lead (Individual Contributor Level 4)",
                    "start_date": "2023-08-05",
                    "work_email": null,
                    "hiring_type": "contractor",
                    "hiring_status": "inactive",
                    "completion_date": "2023-07-21T07:45:11.807Z",
                    "contract_status": "cancelled",
                    "voluntarily_left": null,
                    "contract_coverage": null,
                    "new_hiring_status": "inactive",
                    "client_legal_entity": {
                        "id": 232324,
                        "name": "Aleena Moon"
                    },
                    "has_eor_termination": null,
                    "contract_is_archived": false,
                    "contract_has_contractor": false,
                    "is_user_contract_deleted": false,
                    "hris_direct_employee_invitation": null
                }
            ],
            "hiring_status": "inactive",
            "new_hiring_status": "inactive",
            "hiring_type": "contractor",
            "job_title": "QA Engineer",
            "country": "GE",
            "timezone": null,
            "department": null,
            "work_location": null
        }
    ]
}

Improved

EOR Pensions

We have added a pension object in the response of the country guide endpoint that indicates if this country has a pension benefit available or not.

 "pension": {
   "status": "REQUIRED",
   "providers": [
    {
     "id": 0,
     "name": "US Pension",
     "home_page_url": "https://bit.ly/3uW72fp",
     "contribution": {
      "type": "PERCENTAGE",
      "minimum": "5.00",
      "maximum": "10.00"
     }
    }
   ]
  }

To ensure your employees receive this benefit, make sure to include a new pension object while creating an EOR Contract quote (using the POST /eor endpoint). This will allow you to set the preferred pension provider for the employees.
This new pension object has two properties:

  1. id: Pension provider's id
  2. contribution: You should send this value when the pension provider that you choose has a contribution object.

The contribution property should have a value between the minimum and maximum given.

"pension": {
   "id": "0",
   "contribution": "7.00"
  }

SCIM API Filters

We have added email and name filters to the Deel HR SCIM API Users endpoint. Now you can search for a user based on their email, givenName, or familyName.

To search for someone based on their email format the request like this:

curl --request GET \
     --url 'https://api-staging.letsdeel.com/scim/v2/Users?filter=email%20eq%20%22john%22&startIndex=1&count=50' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {token}

To search for someone based on their givenName, format the request like this:

curl --request GET \
     --url 'https://api-staging.letsdeel.com/scim/v2/Users?filter=name.givenName%20eq%20%22john%22&startIndex=1&count=50' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {token}

To search for someone based on their familyName, format the request like this:

curl --request GET \
     --url 'https://api-staging.letsdeel.com/scim/v2/Users?filter=name.familyName%20eq%20%22john%22&startIndex=1&count=50' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {token}