Hiring Contractors | Deel

This guide outlines the end-to-end programmatic hiring flow. It moves beyond simple API references to explain how your system should orchestrate the transition from a “New Hire” in your internal database to an “Active Contractor” ready for payroll.

The hiring lifecycle is a multi-step process involving your backend, the Deel API, and the human contractor. Understanding the state transitions is key to a successful integration.

Phase 1: Preparation (Resource Mapping)

Before creating a contract, you must map your internal organization data to Deel’s system IDs.

Organization Context: Retrieve your team_id and legal_entity_id.
Job Metadata: Fetch job_title_id and seniority_id.
Worker Info: Ensure you have the contractor’s legal name and a unique personal email address.

Phase 2: Contract Provisioning (The “Draft” State)

In this phase, you define the commercial terms. The contract is created but is not yet legally binding.

1. Create the Contract Object

Submit a POST /contracts request. This creates the “Legal Shell.”

Action: Set the type (e.g., ongoing_time_based for fixed-rate).
Result: You receive a contract_id. The status is now draft.

2. Apply Client Signature

A contract cannot be sent to a worker until the Employer (you) has signed it.

Endpoint: POST /contracts/{contract_id}/signatures
Mechanism: Most integrations use a “Standard Template” so the signature can be applied programmatically via the API.

Phase 3: The Invitation (The “Onboarding” State)

Now that the contract is signed by the employer, you must invite the worker to the Deel platform to complete their side of the deal.

1. Trigger the Invite

Endpoint: POST /contracts/{contract_id}/invitations
Action: This sends the official Deel onboarding email to the worker.

2. Worker Action (Outside the API)

The worker receives the email and must:

Create or log in to their Deel Account.
Complete Identity Verification (KYC).
Review and Sign the Contract.

Phase 4: Activation (The “Live” State)

The contract only becomes “Active” once the worker has completed all onboarding requirements.

Monitoring Status: Use a Webhook listener for contract.status.updated.
The Goal: When the status changes to active, the worker is now eligible for payment inputs (bonuses, timesheets, etc.).

The Complete Table

Step	Action	API Endpoint	Status	Result
1	Create Contract	`POST /contracts`	`draft`	Terms are saved in Deel.
2	Sign (Employer)	`POST /signatures`	`awaiting_worker_signature`	Ready for the worker.
3	Send Invite	`POST /invitations`	`invited`	Email sent to worker.
4	Worker Signs	(User Action)	`active`	Contract is live.

Implementation Best Practices

Webhook Resilience: Do not rely solely on the API response for the “Active” state. The worker might take days to sign. Build a listener for the contract.status.updated event to update your internal database.
External ID Mapping: Always pass your internal Employee/Candidate ID into the external_id field during Step 1. This is the only way to reconcile your data once the contract is active.
Proration Awareness: If the worker signs halfway through a month, Deel will automatically handle the proration based on the active date.