What is Deel HRIS?

Deel HRIS (Human Resource Information System) is a comprehensive platform designed to manage global workforce needs. It integrates various HR functionalities, enabling organizations to hire, onboard, and manage employees and contractors across multiple countries while ensuring compliance with local regulations.

In this guide, we’ll explore how to integrate Deel HRIS into your applications, key features and look at common use cases of the Deel API. Whether you’re a developer, HR-tech professional, or part of a tech team evaluating Deel, this blog aims to help you leverage the API effectively.

Note - This is an educational article on Deel API. If you’re looking for an easier way to launch integrations with Deel, check out Bindbee.

‍

Our Unified API connects you to 50+ HRIS, ATS and Payroll Platforms in minutes. Zero maintenance, no-code Integrations that lets you launch at one-tenth the cost of custom Integrations.

That said, Here’s what we’ll cover in this article:

• A step-by-step Deel API integration guide using Direct API and other key methodologies.
• An overview of the API’s capabilities and key features.
• Best practices and troubleshooting tips for easier API operations.

‍

What is Deel API?

Deel API is a RESTful API that facilitates data exchange and automation within the Deel HRIS, particularly for managing contractors and remote teams.

‍

Key Features of the Deel API

1. API Structure

Deel’s API is designed around RESTful principles, providing standard HTTP methods such as GET, POST, PUT, and DELETE to manage resources. This allows for clear and intuitive interactions with Deel's platform.

‍

2. Key Functional Endpoints

‍

3. Sandbox Environment

Deel offers a sandbox environment to help developers test their API integrations without affecting production data. This is a critical feature for ensuring that your integration behaves as expected before going live.

‍Sandbox Setup Process

1. Create a Sandbox Account: Set up a sandbox account through Deel’s developer portal.
2. Test API Calls: Use the sandbox environment to experiment with endpoints, submit test data, and simulate payroll or contract management workflows.
3. Review Logs: Monitor and review logs for debugging and troubleshooting during the testing phase.

‍

4. Webhooks

Deel supports webhooks, enabling real-time notifications when key events occur (e.g., contract updates, payment status changes).

This allows for seamless data synchronization across external systems.

‍Webhook Setup

1. Subscribe to Events: Use the API to subscribe to specific events, such as contract_created, payment_completed, or timesheet_submitted.
2. Configure Listener URL: Provide a URL for Deel to send POST requests whenever the event occurs.
3. Handle Notifications: The event payload will include details such as contract updates or payment statuses, which your system can use to stay synchronized.

‍

Example: Webhook Payload

{
  "event": "payment_completed",
  "payment_id": "12345",
  "amount": "1000",
  "currency": "USD",
  "status": "completed"
}

‍

5. Documentation and Support

Deel provides extensive API documentation that explains how to use each endpoint, including request and response formats, sample API calls, and error codes. This documentation is available through Deel’s developer portal.

‍

6. Use Cases for Integration

• Onboarding New Hires: Automate the provisioning of new hires across multiple platforms (e.g., Deel + payroll + internal HR tools).
• Payroll Automation: Sync payroll data directly with Deel, minimizing manual data entry.
• Real-Time Notifications: Receive notifications about contract updates or payment completions via webhooks for seamless synchronization.

‍

‍

Deel API Integration Guide

We’ll walk you through two key methodologies to integrate with Deel API.

Method 1 - Direct API Integration

Step 1: Access the Deel Developer Center

Before you can begin integrating with Deel’s API, you must access the Developer Center, which contains all the tools and resources you need to manage API access and tokens.

Step-by-Step Instructions:

1. Log in to Deel:
2. Navigate to the Deel homepage and log in with your credentials.
3. Open Developer Center:
   • Click on the Hub icon at the top of the page.
   • Select the Apps tab.
   • Click on the Developer Center button to access the platform.

The Developer Center is the central hub for managing API access, tokens, and integrations.

‍

Step 2: Generate an Access Token

Access tokens authenticate requests to Deel’s API.

Depending on your use case, Deel offers two types of tokens: Personal Tokens and Organization Tokens.

Steps to Generate an Access Token:

1. Select API Access:
2. In the Developer Center, navigate to the API Access & Sandbox tab.
3. Choose Token Type:
   • Personal Token: Tied to your user profile; it will expire if you leave the company.
   • Organization Token: Not linked to a specific user and does not expire, but it cannot be used for signing contracts.
4. Generate Token:
   • Click on Generate Token.
   • Select the required scopes (permissions) for your access, ensuring you have all the necessary permissions to interact with the required endpoints.
   • Copy the token securely: Tokens are shown only once after generation, so ensure you store it securely, as you won’t be able to access it later.

Example: Authenticating with Access Token

curl -X GET <https://api.deel.com/v1/contracts> \\
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

This cURL command demonstrates how to include the generated access token in the header of API requests to authenticate them.

‍

Step 3: Create an API Sandbox Account

The sandbox environment is a crucial tool for testing your API integration without affecting live data. It provides a safe space to simulate real-world API interactions using sample data.

Steps to Create a Sandbox Account:

1. Create Sandbox Account:
   • In the Developer Center, select the option to create a new sandbox account.
   • Enter your email address and password, and confirm account creation.
2. Access Sandbox:
   • Once the sandbox account is set up, click on Go To Sandbox to enter the testing environment.
   • The sandbox contains sample data that allows you to test API calls and simulate real-world scenarios.

Example Use Case: Testing Cont̨racts API in Sandbox

curl -X GET <https://sandbox-api.deel.com/v1/contracts> \\
     -H "Authorization: Bearer YOUR_SANDBOX_ACCESS_TOKEN"

‍

Step 4: Explore API Endpoints

Deel provides a variety of endpoints for managing different HR-related tasks. Familiarizing yourself with the available API endpoints is essential to ensure you are using the correct ones for your specific integration needs.

Key Endpoints Overview

‍

Refer to the Deel API documentation for detailed information on request parameters, response formats, and usage examples.

‍

Step 5: Implement Data Mapping

If your integration involves transferring data between your system and Deel, it's important to define how fields from your application correspond to Deel’s API fields to ensure data consistency.

Best Practices

1. Identify Key Fields:
2. Map fields like employee names, contract start dates, or payment amounts between your system and Deel.
3. Automate Synchronization:
4. Use the API to automate data syncing, ensuring accurate and up-to-date information between Deel and your platform, which reduces manual errors.

‍

Step 6: Set Up Webhooks (Optional)

Webhooks enable real-time notifications when specific events occur in Deel, such as contract updates or payment statuses. This is an optional but highly useful feature for synchronizing data between Deel and other platforms in real time.

Steps to Set Up Webhooks:

1. Subscribe to Events:
2. Use Deel’s API to subscribe to event notifications, such as payment_completed or contract_updated.
3. Configure Webhook URL:
4. Provide a URL that Deel will use to send the event data as a POST request.

Example: Webhook Notification Payload

{
  "event": "payment_completed",
  "payment_id": "12345",
  "status": "completed",
  "amount": "2000",
  "currency": "USD"
}

This webhook payload provides details about a completed payment, allowing your system to update financial records in real time.

‍

Step 7: Testing and Validation

Before deploying your integration, use the sandbox environment to test all API calls and ensure your integration works as expected. Validate that data is being transferred correctly between Deel and your application.

Key Testing Steps

• Test each endpoint interaction (e.g., contracts, payments) to ensure proper functionality.
• Validate the data mapping, ensuring data consistency between your platform and Deel.
• Test webhooks to confirm your system receives real-time updates from Deel.

‍

Step 8: Deployment to Production

After thorough testing and validation in the sandbox environment, it’s time to move to production.

1. Switch to Production Tokens:
2. Replace sandbox access tokens with live API tokens for production use.
3. Monitor Performance:
4. After deployment, monitor the integration’s performance, including API call success rates and webhook activity. Make any necessary adjustments based on user feedback and system performance.
5. Ongoing Maintenance:
6. Ensure regular maintenance of the integration to accommodate any API updates from Deel and address potential system changes.

‍

‍

Method 3: Integrating with Deel Using Bindbee

Overview - Bindbee is a unified API platform that lets you integrate with Deel (and 50+ HRIS, ATS & Payroll Platforms) in just a few minutes. No-code, zero-maintenance integrations that offers round-the-clock data sync at one-tenth the cost of custom Integrations. Check out Bindbee today!

‍

Setting up Deel Integration with Bindbee

• Sign up with Bindbee and navigate to the dashboard.

• Create a Connector:
  • Click on Create Connector from the dashboard.
  • Select HRIS as the type of integration. Enter customer details and give your connector a unique ID (e.g., Deel_Integration).
• Generate a Magic Link:
  • After setting up the connector, click Create Link to generate a magic link. This will allow the customer to authenticate the connection with Deel API.
  • Open the link and enter the necessary credentials (e.g., Deel key, subdomain). This step establishes the connection between the platform and Bindbee.
• Sync the Connector:
  • Once the connection is made, the connector will begin syncing data from Deel. This may take a few minutes depending on the size of the data. You can track the sync status in the connector section.
• Access the Synced Data:
  • After syncing, go to the Employee section in the Bindbee dashboard and select Get Employees to retrieve employee data from Namely.
• Get the API Key and Connector Token:
  • Copy the API key and the x-connector-token from the Bindbee dashboard, which you will need to make authenticated API requests.

‍

Retrieving Employee Data with Bindbee

Once the Deel data has been synced, you can retrieve employee data on to your application via the Bindbee API.

Here’s a step-by-step process for accessing synced data from Deel through Bindbee’s unified API:

1. Request Setup:
   • Use the Bindbee API to send a request for employee data. You’ll need both your Bindbee API token and the x-connector-token.
2. Example Request:
   • Using Python:

import requests

url = "https://api.bindbee.com/hris/v1/employees"
headers = {
    "Authorization": "Bearer YOUR_BINDBEE_API_KEY",
    "x-connector-token": "YOUR_CONNECTOR_TOKEN",
    "Accept": "application/json"
}
response = requests.get(url, headers=headers)
print(response.json())

• Using cURL:

curl --request GET \
  --url https://api.bindbee.com/hris/v1/employees \
  --header 'Authorization: Bearer YOUR_BINDBEE_API_KEY' \
  --header 'x-connector-token: YOUR_CONNECTOR_TOKEN'

This request will return a list of employee objects, including details like the employee’s first name, last name, job title, department, and contact information.

‍

Sample Response:

{
  "items": [
    {
      "id": "018b18ef-c487-703c-afd9-0ca478ccd9d6",
      "first_name": "John",
      "last_name": "Doe",
      "job_title": "Chief Technology Officer",
      "department": "Engineering",
      "work_email": "john@johndoe.dev"
    }
  ]
}

‍

Bulk Employee Data Retrieval

For retrieving large datasets, Bindbee simplifies the process by allowing you to fetch bulk employee data from Deel.

The pagination feature helps manage large responses by returning results in pages.

‍

What is Pagination?

“Pagination is the process of dividing a large dataset into smaller, manageable chunks or pages, allowing users to navigate through the data more easily without overwhelming them with too much information at once.”

‍

• Pagination Parameters:
  • Use the cursor and page_size parameters to navigate through the results. By default, Bindbee returns 50 records per page.
  • Example of a paginated request:

url = "https://api.bindbee.com/hris/v1/employees?cursor=MDE4YjE4ZWYtYzk5Yy03YTg2LTk5NDYtN2I3YzlkNTQzM2U1&page_size=50"
response = requests.get(url, headers=headers)

• Querying for Specific Employee Data:
  • You can further refine your request by filtering based on specific fields, such as manager_id, remote_id, or company_id to get employees under a particular manager or company.

‍Check out the entire documentation here - Bindbee’s API documentation.

‍

Get Started with Deel API Using Bindbee

Integrating with Deel shouldn’t be an engineering battle.

Yet, for most teams, it feels like a huge time sink—draining valuable engineering resources.

Let us handle the heavy lifting. You focus on growth, what say?

Book a demo with our experts today.