## Deel Integration Guide

##### Learn how to extend Deel compliance with 1099Policy to add fractional insurance options for global contractors and automatically validate COIs for active contracts.

## 1. Overview

Connect Deel contract data to 1099Policy to ensure that every fixed-rate, hourly, or milestone-based engagement is insured or has a validated certificate of insurance (COI) before work begins. This integration automates policy binding, COI validation, and compliance updates between both systems.

By integrating Deel and 1099Policy, you can:

- Bind per-contract coverage once a contract is **Activated**
- Validate and store uploaded **Certificates of Insurance (COIs)**
- Sync coverage status with Deel lifecycle events through 1099Policy webhooks (`policy.*`, `certificate.*`)
- Map Deel compensation to `job.wage` (in cents) and `wage_type`
- Persist the **Deel Contract ID** in `custom_metadata.contract_id` for reconciliation

## 2. Integration Flow

Coverage should be bound as soon as a Deel contract is fully executed but before any services or payments occur. This ensures compliance and protection from the start of the engagement.

- **Primary trigger:** `contract.activated` (Deel Webhooks API)
- **Alternative trigger:** `contract.signed` (if activation is automatic)
- **Event delivery:** Deel Webhooks API (`contract.signed`, `contract.activated`)
- **Required data:** `contract.id`, `worker.id`, `contract_rate.amount`, `payment_unit`, `start_date`, `end_date`
- **Authentication:** Deel API uses bearer tokens for all requests

## 3. Core Concepts

Each Deel object maps directly to a 1099Policy resource, ensuring consistent coverage tracking.

| Deel Object | 1099Policy Object | Description |
| --- | --- | --- |
| Contract | Job + Assignment | Job defines scope and rate; Assignment binds coverage to duration |
| Worker | Contractor | Represents the insured individual |
| Document (COI upload) | Certificate | BYO-COI intake and validation |
| Contract ID | `custom_metadata.contract_id` | Reconciliation key |

## 4. End-to-End Implementation

This section shows how to retrieve Deel data and create corresponding 1099Policy records step-by-step.

### 4.1 Create Contractor

Each Deel Worker must exist in 1099Policy as a Contractor before you can create Quotes or Assignments. Every Contractor must include a unique `contact.email` to ensure tenant-level uniqueness. If Deel does not expose an email address, generate a proxy such as `<worker_id>@relay.yourdomain.com`.

| Deel Field | 1099Policy Contractor | Notes |
| --- | --- | --- |
| `worker.id` | `custom_metadata.deel_worker_id` | Reconciliation key |
| `first_name`, `last_name` | `contact.first_name`, `contact.last_name` | Required |
| `email` | `contact.email` | **Required**; use proxy if missing |
| `country` | `address.country` | Optional |
| `region` / `city` | `address.region` / `address.city` | Optional |

**Source: Deel (REST)**

```
GET https://api.letsdeel.com/rest/v2/workers/{worker_id}
Authorization: Bearer deel_live_***
```

**Destination: 1099Policy (POST /contractors)**

```
POST https://api.1099policy.com/api/v1/contractors
Authorization: Bearer t9k_test_***
Content-Type: application/json
Idempotency-Key: deel-worker-<WORKER_ID>
```

```
{
  "contact": {
    "first_name": "Jordan",
    "last_name": "Cruz",
    "email": "w_8831@relay.yourdomain.com"
  },
  "address": {
    "country": "US",
    "region": "NY",
    "city": "New York"
  },
  "custom_metadata": {
    "deel_worker_id": "w_8831"
  }
}
```

### 4.2 Create Job

Jobs represent the contract scope, category, and compensation. Create a Job when a Deel contract transitions to **Active**.

| 1099Policy Job Field | Deel Source | Notes |
| --- | --- | --- |
| `name` | `contract.title` | Role or contract title |
| `description` | `contract.description` | Scope of work |
| `entity` | Internal client/account ID | Must exist in 1099Policy |
| `category_code` | `job_family` → mapped code | Maintain mapping |
| `wage` (cents) | `contract_rate.amount × 100` | Required |
| `wage_type` | `payment_unit` → "hourly" or "flatfee" | Required |
| `region` | `worker_country` | Defaults to contractor region |
| `custom_metadata.contract_id` | `contract.id` | Reconciliation |

**Source: Deel (REST)**

```
GET https://api.letsdeel.com/rest/v2/contracts/{contract_id}
Authorization: Bearer deel_live_***
```

**Destination: 1099Policy (POST /jobs)**

```
POST https://api.1099policy.com/api/v1/jobs
Authorization: Bearer t9k_test_***
Content-Type: application/json
```

```
{
  "name": "Marketing Design Contract #4451",
  "description": "Create campaign assets and landing pages for Q4 launch",
  "entity": "en_12AbC3",
  "category_code": "MARKETING_DESIGN",
  "wage": 500000,
  "wage_type": "flatfee",
  "region": "US",
  "custom_metadata": { "contract_id": "4451" }
}
```

### 4.3 Create Quote

Quotes determine the policy type and coverage duration for the Deel contract.

| 1099Policy Quote Field | Deel Source | Notes |
| --- | --- | --- |
| `contractor` | Worker → Contractor mapping | Must exist first |
| `job` | Returned Job ID | Required |
| `coverage_type[]` | Compliance requirements | e.g., `["workers-comp","general"]` |
| `effective_date` | `start_date` (epoch UTC) | Required |
| `end_date` | `end_date` (epoch UTC) | Required |
| `custom_metadata.contract_id` | `contract.id` | Reconciliation key |

**Source: Deel (REST)**

```
GET https://api.letsdeel.com/rest/v2/contracts/{contract_id}/details
Authorization: Bearer deel_live_***
```

**Destination: 1099Policy (POST /quotes)**

```
POST https://api.1099policy.com/api/v1/quotes
Authorization: Bearer t9k_test_***
Content-Type: application/json
```

```
{
  "contractor": "cn_Kh18Qs",
  "job": "jb_Dl9n42",
  "coverage_type": ["workers-comp","general"],
  "effective_date": 1764300000,
  "end_date": 1766892000,
  "custom_metadata": { "contract_id": "4451" }
}
```

### 4.4 Create Insurance Application Session

The insurance application session allows the contractor to review and bind their first policy before work begins.

**Destination: 1099Policy (POST /apply/sessions)**

```
POST https://api.1099policy.com/api/v1/apply/sessions
Authorization: Bearer t9k_test_***
Content-Type: application/json
```

```
{
  "quote": "qt_Pf5LmA",
  "success_url": "https://app.deel.com/contracts/4451?coverage=active",
  "cancel_url": "https://app.deel.com/contracts/4451?coverage=canceled",
  "custom_metadata": { "contract_id": "4451" }
}
```

### 4.5 Create Assignment

Assignments apply coverage automatically for returning contractors who already completed their opt-in.

**Destination: 1099Policy (POST /assignments)**

```
POST https://api.1099policy.com/api/v1/assignments
Authorization: Bearer t9k_test_***
Content-Type: application/json
```

```
{
  "contractor": "cn_Kh18Qs",
  "job": "jb_Dl9n42",
  "effective_date": 1764300000,
  "end_date": 1766892000,
  "coverage_type": ["workers-comp","general"],
  "custom_metadata": { "contract_id": "4451" }
}
```

### 4.6 Upload Certificate (BYO-COI)

If a contractor provides their own COI via Deel’s Documents API, upload it to 1099Policy for validation.

**Source: Deel (REST)**

```
GET https://api.letsdeel.com/rest/v2/contracts/{contract_id}/documents
Authorization: Bearer deel_live_***
```

**Destination: 1099Policy (POST /files/certificates)**

(multipart upload)

Fields:

- `certificate=@file.pdf`
- `contractor=cn_Kh18Qs`
- `custom_metadata[contract_id]=4451`

### 4.7 Record Invoice (Optional)

If the contractor’s final pay differs from the original estimate, record the actual remuneration for reconciliation and audit. This step is optional and does not affect insurance coverage.

**Destination: 1099Policy (POST /invoices)**

```
POST https://api.1099policy.com/api/v1/invoices
Authorization: Bearer t9k_test_***
Content-Type: application/json
```

```
{
  "contractor": "cn_ti8eXviE4A",
  "job": "jb_rajdrwMUKi",
  "gross_pay": 1200,
  "paycycle_startdate": 1714419793,
  "paycycle_enddate": 1714419793
}
```

Unix timestamp
Use Unix seconds (UTC) for `paycycle_startdate` and `paycycle_enddate`.

## 5. Webhooks

Webhooks synchronize insurance and contract data across both platforms.

| Source | Event | Action |
| --- | --- | --- |
| Deel | `contract.activated` | Create Job and Quote |
| Deel | `contract.updated` | Adjust Assignment coverage window |
| Deel | `contract.completed` | End coverage |
| 1099Policy | `policy.active` | Mark contract as insured |
| 1099Policy | `policy.canceled` / `policy.expired` | Mark coverage inactive |
| 1099Policy | `certificate.validated` | Mark COI as valid |
| 1099Policy | `certificate.flagged` | Trigger compliance review |

## 6. Testing Checklist

Verify that your integration binds coverage and syncs correctly with Deel events.

- Contractor created with proxy email if missing
- Job created with wage and category mapping
- Quote created with valid coverage window
- Application Session launches and binds coverage
- Assignment aligns with contract term
- Webhook endpoint registered and verified
- Certificate uploads validated

## 7. References

- [Deel Developer Documentation](https://developer.deel.com/)
- [Deel Webhooks API Reference](https://developer.deel.com/reference/webhooks)