GuidesAPI ReferenceChangelog
Changelog

v1.25

New additions: Managers API.

Added

Managers Endpoints

We're excited to announce the launch of our latest feature that allows developers to seamlessly integrate Deel with their existing systems.

With the Deel API, you can now add client users (managers) to your Deel accounts and effortlessly list existing managers.

The key impacts of this feature include streamlined integration, enhanced efficiency in user management, scalability, improved user experience, and future expansions in functionality such as role assignment and user removal.

Simplify your onboarding and user management with Deel API Manager Integration.

Sample Request

POST 'https://api.letsdeel.com/rest/v1/managers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {token}' \
--data-raw '{ 
    "data": {
            "first_name": "Nic",
            "last_name": "Jokic",
            "email": "[email protected]",
    }
}'

Read more about this endpoint here.

v1.22

Introducing Onboarding API.

Added

Onboarding API

Create candidates in Deel with a simple and minimal API call. Deel partners don't need extensive information to create people in Deel. Whether you're an ATS or a job board, you can use Deel Onboarding API to create candidates in Deel.

POST 'https://api.letsdeel.com/rest/v1/candidates' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {token}' \
--header 'x-client-id: {client_id}' \
--data-raw '{ 
    "data": {
      "id": "dhzj64mgen",
      "first_name": "Taylor",
      "last_name": "Swift",
      "status": "offer-accepted",
      "link": "https://your-ats.com/path/to/candidate/dhzj64mgen",
      "email": "[email protected]"
    }
}'

Candidates created with the API will show up in Deel at the top of the People list. Clients can click the "Review & Onboard" button to onboard candidates.

SCIM API: Edit User

You can now edit users in Deel HR SCIM API. The latest PATCH User endpoint enables you to edit a user's work email and manager.

Improved

OAuth app creation flow

We have changed the OAuth app creation flow to make it easy for you to get started with OAuth.

Sandbox: All OAuth apps created in Sandbox/Demo will be automatically published. You don't need to wait for our approval anymore.

Production: All OAuth apps created in production will be automatically submitted for review. Once reviewed the app will be published.

v1.21

Introducing Organization Tokens and more.

Added

Organization Tokens

We are introducing a new type of API access token: Organization Token. This token unlike the Personal access token is not tied to a read user. Hence this token transcends user permissions and can access all data in an organization. This token remains valid even if the user account that generated this token becomes deactivated.

Head to Developer Center to generate an organization token for your organization.

Sandbox in API Playground

You can now call Sandbox API from the Deel API reference page. Click on the BASE URL option in the right toolbar to select the server you want to use.

Add Document Endpoint

You can now attach documents to a contract using Deel API. If you have the need to add additional documents to a contract, use this endpoint. Head to the API reference to see this endpoint.

Sample Request

curl --location 'https://api.letsdeel.com/rest/v1/contracts/{id}/documents' \
--header 'Authorization: Bearer {token}' \
--form 'file=@"/path/to/file/file.pdf"'

Sample Response

{
    "data": {
        "filename": "Screenshot 2023-05-09 at 19.38.23.png",
        "key": "AxWzjRhpTn4Qkn_VnEF1K"
    }
}

OAuth: Organization Apps

We have added app type to OAuth. Now you can choose whether to create a personal or organization app. The organization app generates organization access tokens whereas the personal app generates a personal access token.

If you are building on SCIM API, you must create an organization app as SCIM API only works with organization tokens. Learn more.

v1.20

Bug fixed and improvements.

Improved

Invoice adjustment pagination

We have added offset-based pagination to the Invoice adjustment GET endpoint. You can make use of theoffset and limit properties to paginate requests.

Sample Request

curl --location 'https://api.letsdeel.com/rest/v1/invoice-adjustments?limit=10&offset=2' \
--header 'Authorization: Bearer {token}'

Sample Response

{
    "data": [... ],
    "page": {
        "total_rows": 132,
        "items_per_page": 10,
        "offset": 2
    }
}

Fixed

Invoice adjustment offset limit

The invoice adjustment offset was limited to 99. This bug has been fixed.

v1.19

In this release we are introducing the following endpoints:

  1. Add external Id to a contract.
  2. Preview contract agreement.

We have also made the following updates:

  1. Added employments to SCIM API response schema.
  2. Added country and state to SCIM API response schema.

Add external Id to a contract

You can now add an external id to a contract. This enables you to add a 3rd-party platform's reference id to a Deel contract so that you can search for this contract later using the external id.

Adding the external Id is simple. Below is a cURL example of this request:

curl --request PATCH \
     --url https://api.letsdeel.com/rest/v1/contracts/:contract_id \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {token}' \
     --header 'content-type: application/json' \
     --data '
{
  "data": {
    "external_id": "ext_123"
  }
}
'

You can search for a contract using the external Id as a query parameter in the listing contract endpoint:

curl --request GET \
     --url 'https://api.letsdeel.com/rest/v1/contracts?external_id=ext_123' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {token}'

View this endpoint in the API reference.

Preview contract agreement

You can retrieve an IC contract agreement content in HTML. Please note: this endpoint does not support EOR and Global Payroll contract types.

Example request:

curl --request GET \
     --url https://api.letsdeel.com/rest/v1/contracts/:contrat_id/preview \
     --header 'accept: text/html' \
     --header 'authorization: Bearer {token}'

View this endpoint in the API reference.

SCIM API Updated

We have added employments, country and state in the User schema response.

Example:

{
    ...
    "urn:ietf:params:scim:schemas:extension:2.0:User": {
        "startDate": "2023-04-26",
        "endDate": "",
        "state": null,
        "country": "NG",
        "employments": [
            {
                "contractId": "7GBVRoFjo7er7HKHFaszL",
                "title": "Direct Marketing Administrator",
                "startDate": "2023-04-26",
                "contractType": "hris_direct_employee",
                "state": null,
                "country": "NG",
                "active": true
            }
        ]
    },
	 ...
}

v1.18

In this release, we are introducing the Deel HR SCIM API beta.

Deel HR SCIM API

Deel HR SCIM API is used by partners to provision, manage, and de-provision users.

The SCIM API is based on the Open standard: System for Cross-domain Identity Management 2.

Implemented features

Our SCIM implementation supports the User resource.

With SCIM you can:

  1. Get all users in a company.

Features not implemented

You cannot do the following things yet:

  1. Create or delete Users via the SCIM API.
  2. Update, activate, or deactivate users.
  3. Delete users.

v1.17

In this release, we are introducing an endpoint to calculate the first payment amount and date

Calcualte first payment amount

This API endpoint enables you to calculate the pro-rata first payment based on the contractor's start date and payment cycle details.

Sample Request 

{
  "data": {
    "compensation_details": {
      "payment_due_type": "REGULAR",
      "work_week_start": "Monday",
      "currency_code": "EUR",
      "scale": "monthly",
      "amount": 3000,
      "cycle_end": 31,
      "cycle_end_type": "DAY_OF_MONTH",
      "payment_due_days": 1,
      "calculation_type": "WORK_DAYS",
      "work_week_end": "Friday"
    },
    "country_code": "NL",
    "type": "ongoing_time_based",
    "start_date": "2023-03-15"
  }
}

Sample response
The total field shows the calculated pro-rate amount. first_payment_dates array shows the possible first payment dates. 

{
  "data": {
    "pro_rata": {
      "rate": 3000,
      "daily_rate": 130.4348,
      "total": 1695.65,
      "calculation_type": "WORK_DAYS",
      "cycle_work_days": 13,
      "work_week_start": "Monday",
      "work_week_end": "Friday",
      "cycle_start": "2023-03-15",
      "cycle_end": "2023-03-31"
    },
    "first_payment_dates": [
      {
        "due": "2023-04-01T22:59:59.999Z"
      },
      {
        "due": "2023-05-01T22:59:59.999Z"
      },
      {
        "due": "2023-06-01T22:59:59.999Z"
      },
      {
        "due": "2023-07-01T22:59:59.999Z"
      },
      {
        "due": "2023-08-01T22:59:59.999Z"
      },
      {
        "due": "2023-09-01T22:59:59.999Z"
      },
      {
        "due": "2023-10-01T22:59:59.999Z"
      },
      {
        "due": "2023-11-01T23:59:59.999Z"
      },
      {
        "due": "2023-12-01T23:59:59.999Z"
      },
      {
        "due": "2024-01-01T23:59:59.999Z"
      }
    ]
  }
}

v1.16.12

In this release, we are made a few improvements to v1.16.

Improvement list:

  1. The retrieve country guide endpoint has an updated response.
  2. Deel OAuth screen will show your App name instead of your Developer account name.
  3. Bug fix: Job title pagination does not return a 500 error anymore.

v1.16

In this release, we are introducing Accounting API (beta).

Accounting API

Accounting API endpoints enable you to retrieve accounting-related information from Deel. The following endpoints are available:

  1. Retrieve paid invoices.
  2. Retrieve the payment summary of payments made to Deel.
  3. Retrieve a full breakdown of a payment made to Deel.

Accounting API is currently in (beta) and only available upon request. Please reach other to support to request access.

Country fields

We have added the following new fields in the 'retrieve a single contract' response body.

  1. nationality in the worker object.
  2. country in the employment_details object.
  3. state in the employment_details object.

Timesheets improvements

We have improved the timesheets API so that it returns the created resource information.

Previously, upon creating a timesheet, you would have gotten the following response from Deel API:

{
    "data": {
        "created": true
    }
}

Now, you will get more information about the created resource. Id, status, and created date fields will be returned. 

{
    "data": {
        "created": true,
        "created_at": "2022-12-23T09:03:01.267Z",
        "status": "pending",
        "id": 15629734
    }
}

Invocie adjustment improvements

We have improved the invoice adjustment API so that it returns the created resource information.

Previously, upon creating an adjustment, you would have gotten the following response from Deel API:

{
    "data": {
        "created": true
    }
}

Now, you will get more information about the created resource. Id, status, and created date fields will be returned

{
    "data": {
        "created": true,
        "created_at": "2022-12-23T09:03:01.267Z",
        "status": "pending",
        "id": 15629711
    }
}

Webhook Events

We have added timesheets and invoice adjustment webhooks events to the API. You can now subscribe to the following events:

  1. timesheet.created: triggered when a new timesheet is created.
  2. timesheet.reviewed: triggered when a timesheet is approved or denied.
  3. invoice-adjustment.created: triggered when a new invoice adjustment is created.
  4. invoice-adjustment.reviewed: triggered when an invoice adjustment is approved or denied.
  5. time-off.created: triggered when a new EOR contract time off is created.
  6. time-off.reviewed: triggered when an EOR time off is approved or denied.
  7. time-off.updated: triggered when an EOR time off is updated.

Bug fixes

Further, in this release, we have fixed the following bugs:

  1. Incorrect job_title value for EOR contracts in the 'retrieve a single contract' response body.
  2. Incorrect 'full_nameandemail` values in the worker object for EOR contracts.

v1.15.2

In this release, we are introducing improvements to EOR endpoints.

Deel Healthcare

In some countries, it is mandatory to have healthcare coverage for employees. The following updates enable you to add healthcare plans to contracts when creating contracts with Deel API.

Retrieve healthcare plans

The EOR country guide endpoint (link) now returns healthcare options available in each country. Below is an example of a US country guide including health insurance providers. 

{
  "data": {
    "holiday": {
      "min": "15"
    },
    "part_time_holiday": {
      "type": null,
      "min": "15"
    },
    "sick_days": {
      "min": "0",
      "max": "84"
    },
    "salary": {
      "min": "35568.00",
      "max": "1900000.00"
    },
    "probation": {
      "min": null,
      "max": null
    },
    "part_time_probation": {
      "min": null,
      "max": null
    },
    "work_schedule": {
      "days": {
        "max": null,
        "min": "5.0000"
      },
      "hours": {
        "max": null,
        "min": "8.0000"
      }
    },
    "insurance_fee": "30.00",
    "currency": "USD",
    "hiring_guide_country_name": "united-states",
    "start_date_buffer": 2,
    "definite_contract": {
      "type": "ALLOWED_WITHOUT_LIMITATION",
      "maximum_limitation": null
    },
    "adjustments_information_box": "For reimbursable costs connected to carrying out work, choose “expenses”.\nFor fixed or recurring amounts provided as a benefit to employee, choose “allowances”.",
    "health_insurance": {
      "status": "REQUIRED",
      "providers": [
        {
          "name": "United Healthcare, VSP Vision & Delta Dental: Singles Only",
          "is_unisure": false,
          "home_page_url": "https://bit.ly/3uW72fp",
          "currency": "USD",
          "type": "PLAN",
          "ending_rule": "END_OF_MONTH",
          "days_to_cancel": null,
          "pricing_info_link": null,
          "fixed_price": true,
          "attachments": [
            {
              "id": 2342,
              "label": "Deel USA Health Care Packet.pdf"
            }
          ],
          "client_info_banner": null,
          "is_available_for_new_quotes": false,
          "plan_groups": [
            {
              "name": "Tier",
              "plans": [
                {
                  "id": 72,
                  "name": "USA Healthcare Plan",
                  "price": "570.00",
                  "currency": "USD",
                  "index": 0,
                  "is_enabled": true
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Create a contract with a healthcare plan

When creating an EOR contract, provide the health insurance plan id in the request payload to indicate the chosen healthcare plan. In the example above, the plan id resides in the following path. data.health_insurance.providers[].plan_groups[].plans[].id

Below is an example request payload to create an EOR contract with the healthcare plan included:

curl --request POST \
     --url https://api.letsdeel.com/rest/v1/eor \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {token}' \
     --header 'content-type: application/json' \
     --data '
{
     "data": {
          "employee": {
               "first_name": "Jane",
               "last_name": "Doe",
               "email": "[email protected]",
               "nationality": "US"
          },
          "employment": {
               "country": "US",
               "state": "CA",
               "type": "Full-time",
               "work_visa_required": false,
               "start_date": "2022-12-31",
               "time_off_type": "STANDARD"
          },
          "client": {
               "legal_entity": {
                    "id": 12345
               },
               "team": {
                    "id": 12345
               }
          },
          "compensation_details": {
               "salary": 45000,
               "currency": "USD"
          },
          "job_title": "Sales Manager",
          "health_plan_id": "72"
     }
}
'